@lostgradient/weft 0.2.0

package/dist/core/types/message-handles.d.ts

@@ -0,0 +1,229 @@
+import { type DefinitionSchema, type InferSchemaOutput } from './definition-schema.ts';
+/**
+ * Typed handle for a workflow signal. The runtime value is `{ name }` plus an
+ * optional `inputSchema` carried for introspection and boundary validation;
+ * the generic parameter exists to carry the payload type through call sites.
+ *
+ * @example
+ * ```ts
+ * import { signal, type SignalDefinition } from '@lostgradient/weft';
+ *
+ * declare const handle: {
+ *   signal(definition: SignalDefinition<{ approved: boolean }>, input: { approved: boolean }): Promise<void>;
+ * };
+ * const approval: SignalDefinition<{ approved: boolean }> = signal('approval');
+ * await handle.signal(approval, { approved: true });
+ * ```
+ */
+export interface SignalDefinition<TInput = void> {
+    readonly name: string;
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+    readonly _input?: (input: TInput) => void;
+}
+/**
+ * Typed handle for a workflow update. Updates accept an input payload and
+ * return a response to the caller. Optional `inputSchema` and `outputSchema`
+ * carry validation metadata to the boundary.
+ *
+ * @example
+ * ```ts
+ * import { update, type UpdateDefinition } from '@lostgradient/weft';
+ *
+ * declare const handle: {
+ *   update(
+ *     definition: UpdateDefinition<{ orderId: string }, { status: string }>,
+ *     input: { orderId: string },
+ *   ): Promise<{ status: string }>;
+ * };
+ * const approveOrder: UpdateDefinition<{ orderId: string }, { status: string }> =
+ *   update('approveOrder');
+ * const result = await handle.update(approveOrder, { orderId: 'ord_123' });
+ * void result.status;
+ * ```
+ */
+export interface UpdateDefinition<TInput = void, TOutput = unknown> {
+    readonly name: string;
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+    readonly outputSchema?: DefinitionSchema<unknown, TOutput>;
+    readonly _input?: (input: TInput) => void;
+    readonly _output?: () => TOutput;
+}
+/**
+ * Typed handle for a workflow query. Queries are read-only accessors and may
+ * optionally accept an input payload. Optional `inputSchema` and
+ * `outputSchema` carry validation metadata to the boundary.
+ *
+ * @example
+ * ```ts
+ * import { query, type QueryDefinition } from '@lostgradient/weft';
+ *
+ * declare const handle: {
+ *   query(
+ *     definition: QueryDefinition<{ orderId: string }, { state: string }>,
+ *     input: { orderId: string },
+ *   ): Promise<{ state: string }>;
+ * };
+ * const orderStatus: QueryDefinition<{ orderId: string }, { state: string }> =
+ *   query('orderStatus');
+ * const status = await handle.query(orderStatus, { orderId: 'ord_123' });
+ * void status.state;
+ * ```
+ */
+export interface QueryDefinition<TInput = void, TOutput = unknown> {
+    readonly name: string;
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+    readonly outputSchema?: DefinitionSchema<unknown, TOutput>;
+    readonly _input?: (input: TInput) => void;
+    readonly _output?: () => TOutput;
+}
+export type MessageDefinition = QueryDefinition<unknown> | SignalDefinition<unknown> | UpdateDefinition<unknown>;
+export type MessageName = string | {
+    readonly name: string;
+};
+/**
+ * Options accepted by {@link signal} when declaring schema metadata.
+ *
+ * @example
+ * ```ts
+ * import type { SignalOptions } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const options: SignalOptions<{ approved: boolean }> = {
+ *   inputSchema: z.object({ approved: z.boolean() }),
+ * };
+ * void options;
+ * ```
+ */
+export interface SignalOptions<TInput = void> {
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+}
+/**
+ * Options accepted when sending a signal to a workflow.
+ *
+ * @example
+ * ```ts
+ * import type { SignalDeliveryOptions } from '@lostgradient/weft';
+ *
+ * const options: SignalDeliveryOptions = { signalId: 'approval-123' };
+ * void options;
+ * ```
+ */
+export interface SignalDeliveryOptions {
+    readonly signalId?: string;
+}
+/**
+ * Create a typed workflow signal handle. When an `inputSchema` is supplied
+ * via options, the payload type is inferred from the schema's
+ * `~standard.types.output` marker — no explicit generic required, and
+ * transform schemas surface their parsed payload type.
+ *
+ * @example
+ * ```ts
+ * import { signal } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const approval = signal<{ approved: boolean }>('approval');
+ *
+ * const approval2 = signal('approval', { inputSchema: z.object({ approved: z.boolean() }) });
+ * void approval2;
+ * ```
+ */
+export declare function signal<TSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    inputSchema: TSchema;
+}): SignalDefinition<InferSchemaOutput<TSchema>>;
+export declare function signal<TInput = void>(name: string, options?: SignalOptions<TInput>): SignalDefinition<TInput>;
+/**
+ * Options accepted by {@link update} when declaring schema metadata.
+ *
+ * @example
+ * ```ts
+ * import type { UpdateOptions } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const options: UpdateOptions<{ id: string }, { ok: true }> = {
+ *   inputSchema: z.object({ id: z.string() }),
+ *   outputSchema: z.object({ ok: z.literal(true) }),
+ * };
+ * void options;
+ * ```
+ */
+export interface UpdateOptions<TInput = void, TOutput = unknown> {
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+    readonly outputSchema?: DefinitionSchema<unknown, TOutput>;
+}
+/**
+ * Create a typed workflow update handle. When `inputSchema` and/or
+ * `outputSchema` are supplied via options, payload types are inferred from
+ * the schemas — no explicit generic required.
+ *
+ * @example
+ * ```ts
+ * import { update } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const approve = update<{ id: string }, { accepted: boolean }>('approve');
+ *
+ * const approve2 = update('approve', {
+ *   inputSchema: z.object({ id: z.string() }),
+ *   outputSchema: z.object({ accepted: z.boolean() }),
+ * });
+ * void approve2;
+ * ```
+ */
+export declare function update<TInputSchema extends DefinitionSchema<unknown, unknown>, TOutputSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    inputSchema: TInputSchema;
+    outputSchema: TOutputSchema;
+}): UpdateDefinition<InferSchemaOutput<TInputSchema>, InferSchemaOutput<TOutputSchema>>;
+export declare function update<TInputSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    inputSchema: TInputSchema;
+}): UpdateDefinition<InferSchemaOutput<TInputSchema>>;
+export declare function update<TInput = void, TOutput = unknown>(name: string, options?: UpdateOptions<TInput, TOutput>): UpdateDefinition<TInput, TOutput>;
+/**
+ * Options accepted by {@link query} when declaring schema metadata.
+ *
+ * @example
+ * ```ts
+ * import type { QueryOptions } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const options: QueryOptions<{ id: string }, { state: string }> = {
+ *   inputSchema: z.object({ id: z.string() }),
+ *   outputSchema: z.object({ state: z.string() }),
+ * };
+ * void options;
+ * ```
+ */
+export interface QueryOptions<TInput = void, TOutput = unknown> {
+    readonly inputSchema?: DefinitionSchema<unknown, TInput>;
+    readonly outputSchema?: DefinitionSchema<unknown, TOutput>;
+}
+/**
+ * Create a typed workflow query handle. When `inputSchema` and/or
+ * `outputSchema` are supplied via options, payload types are inferred from
+ * the schemas — no explicit generic required.
+ *
+ * @example
+ * ```ts
+ * import { query } from '@lostgradient/weft';
+ * import { z } from 'zod';
+ *
+ * const status = query<void, { state: string }>('status');
+ *
+ * const status2 = query('status', {
+ *   outputSchema: z.object({ state: z.string() }),
+ * });
+ * void status2;
+ * ```
+ */
+export declare function query<TInputSchema extends DefinitionSchema<unknown, unknown>, TOutputSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    readonly inputSchema: TInputSchema;
+    readonly outputSchema: TOutputSchema;
+}): QueryDefinition<InferSchemaOutput<TInputSchema>, InferSchemaOutput<TOutputSchema>>;
+export declare function query<TOutputSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    readonly outputSchema: TOutputSchema;
+}): QueryDefinition<void, InferSchemaOutput<TOutputSchema>>;
+export declare function query<TInputSchema extends DefinitionSchema<unknown, unknown>>(name: string, options: {
+    readonly inputSchema: TInputSchema;
+}): QueryDefinition<InferSchemaOutput<TInputSchema>>;
+export declare function query<TInput = void, TOutput = unknown>(name: string, options?: QueryOptions<TInput, TOutput>): QueryDefinition<TInput, TOutput>;
+export declare function messageName(definition: MessageName): string;

package/dist/core/types/message-handles.js

@@ -0,0 +1,36 @@
+import {
+  validateDefinitionSchemaMetadata
+} from "./definition-schema.js";
+export function signal(name, options) {
+  if (options?.inputSchema !== void 0)
+    validateDefinitionSchemaMetadata(options.inputSchema, `signal("${name}").inputSchema`);
+  return {
+    name,
+    ...options?.inputSchema !== void 0 ? { inputSchema: options.inputSchema } : {}
+  };
+}
+export function update(name, options) {
+  if (options?.inputSchema !== void 0)
+    validateDefinitionSchemaMetadata(options.inputSchema, `update("${name}").inputSchema`);
+  if (options?.outputSchema !== void 0)
+    validateDefinitionSchemaMetadata(options.outputSchema, `update("${name}").outputSchema`);
+  return {
+    name,
+    ...options?.inputSchema !== void 0 ? { inputSchema: options.inputSchema } : {},
+    ...options?.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+  };
+}
+export function query(name, options) {
+  if (options?.inputSchema !== void 0)
+    validateDefinitionSchemaMetadata(options.inputSchema, `query("${name}").inputSchema`);
+  if (options?.outputSchema !== void 0)
+    validateDefinitionSchemaMetadata(options.outputSchema, `query("${name}").outputSchema`);
+  return {
+    name,
+    ...options?.inputSchema !== void 0 ? { inputSchema: options.inputSchema } : {},
+    ...options?.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+  };
+}
+export function messageName(definition) {
+  return typeof definition === "string" ? definition : definition.name;
+}

package/dist/core/types/name-grammar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared name-grammar validator for workflow and activity names.
+ *
+ * The wire format used by the remote worker protocol qualifies activity names
+ * as `${workflowType}.${activityName}` (introduced in Phase 4). To keep that
+ * encoding unambiguous, the dot separator must never appear inside a workflow
+ * or activity name, and names must start with a letter or underscore. The
+ * permitted character class is `[A-Za-z_][A-Za-z0-9_-]*`.
+ *
+ * This helper is called from public construction and registration sites:
+ *
+ *   1. `workflow({ name })` — rejects invalid workflow names.
+ *   2. `engine.register(workflowDefinition)` — rejects invalid structural
+ *      workflow names before they reach the workflow registry.
+ *   3. `WorkflowBuilder.activities({ ... })` keys — rejects invalid activity
+ *      names supplied as the outer object key.
+ *   4. `activity({ name })` — rejects invalid names on the canonical
+ *      activity-definition constructor.
+ *   5. `ActivityRegistry.register(name, fn)` — rejects invalid names before
+ *      they reach local or global activity registries.
+ *
+ * Keep this list in sync with Phase 4's worker SDK key validation: any name
+ * that passes here must also pass on the worker side, and vice versa.
+ */
+/**
+ * Discriminator for the error message so callers see which construction site
+ * rejected the name. Add new kinds here when new entry points need validation.
+ */
+export type NameKind = 'workflow' | 'activity';
+export declare function validateWorkflowOrActivityName(name: string, kind: NameKind): void;

package/dist/core/types/name-grammar.js

@@ -0,0 +1,9 @@
+const NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/, RULE_DESCRIPTION = "must match /^[A-Za-z_][A-Za-z0-9_-]*$/ \u2014 start with a letter or underscore, " + "use only letters, digits, underscores, or hyphens, and contain no '.' characters. The remote worker protocol encodes activity names as `${workflowType}.${activityName}` on the wire, so a '.' inside either name would break the qualifier split. If you previously used dotted names like 'payments.charge', rename to 'payments-charge' or 'paymentsCharge' before adopting the workflow-builder API.";
+export function validateWorkflowOrActivityName(name, kind) {
+  if (typeof name !== "string" || name.length === 0)
+    throw Error(`${kind} name must be a non-empty string \u2014 ${RULE_DESCRIPTION}`);
+  if (name.includes("."))
+    throw Error(`${kind} name "${name}" contains '.', which is reserved for qualified activity names. ${RULE_DESCRIPTION}`);
+  if (!NAME_PATTERN.test(name))
+    throw Error(`${kind} name "${name}" is invalid \u2014 ${RULE_DESCRIPTION}`);
+}

package/dist/core/types/options.d.ts

@@ -0,0 +1,360 @@
+import type { AlertingOptions } from '../../alerting/types.ts';
+import type { Storage as WeftStorage } from '../../storage/interface.ts';
+import type { CompressionOptions } from '../compression.ts';
+import type { Interceptor } from '../interceptor.ts';
+import type { ArchiveAdapter } from './archive-adapter.ts';
+import type { HistoryPolicy } from './history-policy.ts';
+import type { FailureCategory, WorkflowStatus } from './identity.ts';
+import type { PayloadSizePolicy } from './payload-size-policy.ts';
+import type { Duration, RetentionPolicy } from './retry-retention.ts';
+import type { SearchAttributeHandle, SearchAttributeValue } from './search-attributes.ts';
+import type { Serializer } from './serializer.ts';
+/**
+ * Options accepted by `engine.start(type, input, options?)`.
+ *
+ * Every field is optional. `id` lets you specify your own workflow ID;
+ * `idempotencyKey` enforces single-execution semantics within a window;
+ * `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
+ * execution; `tags` and `searchAttributes` make the workflow discoverable
+ * via filters.
+ *
+ * `HttpClient.start` forwards `searchAttributes` to the server. It rejects
+ * `idempotencyKey` until the HTTP start protocol exposes matching
+ * single-execution semantics, so callers do not accidentally rely on a
+ * silently dropped option.
+ *
+ * @example Start a delayed workflow with tags and search attributes
+ * ```ts
+ * import { workflow, Engine, type StartOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'greet' }).execute(async function* () {
+ *     return 'hi';
+ *   }),
+ * );
+ *
+ * const options: StartOptions = {
+ *   id: 'greeting-2026-04-29',
+ *   startAfter: '5m',
+ *   tags: ['nightly', 'ops'],
+ *   searchAttributes: { customerId: 'acme' },
+ * };
+ * const handle = await engine.start('greet', null, options);
+ * void handle;
+ * ```
+ */
+export interface StartOptions {
+    id?: string;
+    idempotencyKey?: string;
+    executionTimeout?: Duration;
+    startAt?: number;
+    startAfter?: Duration;
+    tags?: string[];
+    searchAttributes?: Record<string, SearchAttributeValue>;
+}
+/**
+ * Options for {@link Engine.fork}. Controls which checkpoint step to fork
+ * from; defaults to the latest persisted checkpoint when omitted.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, type ForkOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'process' }).execute(async function* () { return 'done'; }));
+ *
+ * const original = await engine.start('process', null);
+ * await original.result();
+ *
+ * const options: ForkOptions = { fromStep: 2 };
+ * const forked = await engine.fork(original.id, options);
+ * void forked;
+ * ```
+ */
+export interface ForkOptions {
+    fromStep?: number;
+}
+/**
+ * Configuration options for the {@link Engine} constructor.
+ *
+ * All fields are optional. Common overrides include `storage`, `retention`,
+ * `development`, `serializer`, `compression`, `workflowExecutionMode`,
+ * `workerExecution`, and `alerts`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type EngineOptions } from '@lostgradient/weft';
+ *
+ * const options: EngineOptions = {
+ *   development: true,
+ *   retention: { completed: '7d', failed: '30d' },
+ *   checkpointSizeWarningThreshold: 128_000,
+ * };
+ *
+ * const engine = new Engine(options);
+ * void engine;
+ * ```
+ */
+export interface EngineOptions {
+    storage?: WeftStorage;
+    development?: boolean;
+    serializer?: Serializer;
+    retention?: RetentionPolicy;
+    retentionSweepInterval?: Duration;
+    retentionSweepBatchSize?: number;
+    /**
+     * History circuit-breaker thresholds. When `history.maxEvents` is set, a
+     * workflow whose event-log record count would exceed it is forced to a
+     * terminal `timed-out` state with reason {@link HISTORY_CIRCUIT_BREAKER_REASON}.
+     * Omit to disable. There are no baked-in defaults.
+     */
+    history?: HistoryPolicy;
+    /**
+     * Operator-supplied sink for event-log ranges discarded by
+     * `history.retentionWindow` compaction. Best-effort export only — see
+     * {@link ArchiveAdapter}. Omit for no archival (the default).
+     */
+    archive?: ArchiveAdapter;
+    /**
+     * Payload-size cap thresholds. When `payloadSize.maxBytes` is set, a workflow
+     * input, signal payload, or activity result whose serialized (codec-encoded)
+     * size would exceed it is rejected at admission with `PayloadSizeExceededError`
+     * before any storage write. Omit to disable. There are no baked-in defaults.
+     */
+    payloadSize?: PayloadSizePolicy;
+    /** Payload compression applied at the storage layer. */
+    compression?: CompressionOptions;
+    checkpointHistory?: number;
+    checkpointSizeWarningThreshold?: number;
+    maxNestingDepth?: number;
+    /** Enable BroadcastChannel for cross-worker event coordination. Default: false. */
+    broadcastEvents?: boolean;
+    /**
+     * Select where workflow generator turns execute. Omitting this defaults to
+     * `'inline'`, which steps the generator in the engine isolate and is
+     * appropriate only when workflow code is trusted. Use `'worker'` for
+     * untrusted deployments: it requires `workerExecution` and applies hardened
+     * Worker turn-timeout and protocol-message-size limits. Explicit `'inline'`
+     * rejects `workerExecution`.
+     */
+    workflowExecutionMode?: 'inline' | 'worker';
+    /**
+     * Enable Worker-based workflow execution. When provided, workflow generator
+     * turns run in Web Workers instead of inline on the engine isolate. Activities
+     * are still executed on the main thread via the activity registry unless
+     * `activityExecution` is also configured.
+     *
+     * Explicit `workflowExecutionMode: 'worker'` requires this object, applies
+     * hardened defaults for Worker turn timeout and protocol-message size, and
+     * rejects invalid runtime values. Explicit `workflowExecutionMode: 'inline'`
+     * rejects this object to avoid ambiguous trust posture.
+     *
+     * Worker execution protects engine liveness and engine heap access. It is not
+     * an operating-system sandbox: workflow code can still access APIs exposed in
+     * the Worker runtime.
+     */
+    workerExecution?: {
+        /** URL of the worker script, for example `new URL('./workflow-worker.ts', import.meta.url)`. */
+        workerUrl: string | URL;
+        /** Maximum number of concurrent workers. Default: 4. */
+        poolSize?: number;
+        /** Use Bun's `smol` worker option for smaller memory footprint. */
+        smol?: boolean;
+        /**
+         * Host-enforced wall-clock timeout for each Worker `run` or `resume` turn.
+         * Defaults to `1_000` in Worker mode. Provide a positive safe integer to
+         * override the default.
+         */
+        workflowTurnTimeoutMs?: number;
+        /**
+         * Maximum encoded size of Weft-owned Worker protocol messages. Defaults to
+         * `1_048_576` in explicit Worker mode. The minimum accepted value is
+         * `4_096` so bounded failure envelopes can always cross the protocol.
+         */
+        maxProtocolMessageBytes?: number;
+    };
+    /**
+     * Enable worker-based activity execution. When provided, activity functions
+     * run in isolated Web Workers instead of on the main thread. Activities must
+     * be pre-registered in the worker via `createActivityWorkerEntryUrl`.
+     */
+    activityExecution?: {
+        /** URL of the activity worker script (created via `createActivityWorkerEntryUrl`). */
+        workerUrl: string | URL;
+        /** Maximum number of concurrent activity workers. Default: 4. */
+        poolSize?: number;
+        /** Use Bun's `smol` worker option for smaller memory footprint. */
+        smol?: boolean;
+    };
+    /** Built-in alerting configuration. */
+    alerts?: AlertingOptions;
+    /**
+     * Unified interceptors registered at construction. This is equivalent to
+     * calling `addInterceptor` for each entry; each interceptor participates in
+     * the workflow and/or activity pipeline based on which hooks it implements.
+     * The engine takes a defensive copy at construction — mutating this array
+     * after passing it has no effect.
+     */
+    interceptors?: readonly Interceptor[];
+}
+/**
+ * Filter criteria for {@link Engine.list}. All fields are optional and
+ * combine with AND semantics. `status` accepts a single value or an array;
+ * `attributes` is a list of attribute predicates evaluated on indexed search
+ * attributes. Pairs with `limit`/`offset` for pagination.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type ListFilter } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const filter: ListFilter = {
+ *   status: ['running', 'pending'],
+ *   tags: ['nightly'],
+ *   attributes: [{ key: 'customerId', value: 'acme' }],
+ *   limit: 20,
+ *   offset: 0,
+ * };
+ * const result = await engine.list(filter);
+ * console.log(result.items.length);
+ * ```
+ */
+/**
+ * Numeric half-open range bound, used by visibility filters that match a
+ * stored numeric field (timestamps, deadlines). Provide at least one of the
+ * four bounds. `gt`/`gte` are mutually exclusive on the lower side; `lt`/`lte`
+ * are mutually exclusive on the upper side.
+ */
+export interface TimeRange {
+    gte?: number;
+    lte?: number;
+    gt?: number;
+    lt?: number;
+}
+/**
+ * Filter passed to {@link Engine.list} (and equivalent visibility transports)
+ * to narrow which {@link WorkflowSummary} entries are returned. Every field
+ * is optional; combining fields applies them as AND.
+ *
+ * @example
+ * ```ts
+ * import { Engine, type ListFilter } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const filter: ListFilter = {
+ *   status: ['running', 'failed'],
+ *   createdAt: { gte: Date.now() - 60_000 },
+ * };
+ *
+ * const page = await engine.list(filter);
+ * ```
+ */
+export interface ListFilter {
+    /** Match workflows whose {@link WorkflowState.status} is one of the listed values. */
+    status?: WorkflowStatus | WorkflowStatus[];
+    /**
+     * Match workflows by registered workflow type (e.g. `'order-fulfillment'`).
+     *
+     * @example
+     * ```ts
+     * import type { ListFilter } from '@lostgradient/weft';
+     * const filter: ListFilter = { type: 'order-fulfillment' };
+     * ```
+     */
+    type?: string;
+    /** Match workflows that carry every listed tag. */
+    tags?: string[];
+    /** Filter on indexed search attributes (equality or range). */
+    attributes?: readonly AttributeFilter[];
+    /** Maximum number of summaries to return. Server enforces an upper bound. */
+    limit?: number;
+    /** Number of summaries to skip before returning results. */
+    offset?: number;
+    /**
+     * Workflow id prefix. Restricted to `[A-Za-z0-9_-]+`; values containing
+     * other characters are rejected during validation. Matches by raw
+     * `state.id.startsWith(idPrefix)` after candidate enumeration.
+     */
+    idPrefix?: string;
+    /** Range filter on `WorkflowState.createdAt` (ms epoch). */
+    createdAt?: TimeRange;
+    /** Range filter on `WorkflowState.updatedAt` (ms epoch). */
+    updatedAt?: TimeRange;
+    /** Range filter on `WorkflowState.executionDeadline` (ms epoch). */
+    executionDeadline?: TimeRange;
+    /**
+     * Match by the workflow's `failureCategory`. The engine uses the
+     * `failureCategory` search-attribute index to narrow candidate workflow IDs,
+     * then still verifies the loaded `WorkflowState.failureCategory` so state
+     * remains authoritative when index entries are stale.
+     */
+    failureCategory?: FailureCategory | FailureCategory[];
+}
+/**
+ * Projection options for {@link Engine.list}. These options do not change
+ * which workflows match the list filter; they only control optional summary
+ * fields that may require additional storage reads.
+ *
+ * @example Include failure categories projected from search attributes
+ * ```ts
+ * import { Engine, type ListOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const options: ListOptions = { includeFailureCategory: true };
+ * const page = await engine.list({ status: 'failed' }, options);
+ * void page;
+ * ```
+ */
+export interface ListOptions {
+    /**
+     * Populate `WorkflowSummary.failureCategory` for failed workflows from the
+     * stored `failureCategory` search attribute when the workflow state itself
+     * does not carry a category. Defaults to `false`.
+     */
+    includeFailureCategory?: boolean;
+}
+export type AttributeFilterKey = string | SearchAttributeHandle;
+export type AttributeFilterValue<TKey extends AttributeFilterKey> = TKey extends SearchAttributeHandle<infer TValue> ? TValue extends string[] ? string : TValue : SearchAttributeValue;
+export type AttributeRangeValue<TKey extends AttributeFilterKey> = TKey extends SearchAttributeHandle<infer TValue> ? Extract<TValue, Date | number> : SearchAttributeValue;
+export type AttributeFilter<TKey extends AttributeFilterKey = AttributeFilterKey> = TKey extends SearchAttributeHandle ? {
+    key: TKey;
+    value?: AttributeFilterValue<TKey>;
+    gt?: never;
+    lt?: never;
+    gte?: never;
+    lte?: never;
+} | {
+    key: TKey;
+    value?: never;
+    gt?: AttributeRangeValue<TKey>;
+    lt?: AttributeRangeValue<TKey>;
+    gte?: AttributeRangeValue<TKey>;
+    lte?: AttributeRangeValue<TKey>;
+} : {
+    key: TKey;
+    value?: SearchAttributeValue;
+    gt?: SearchAttributeValue;
+    lt?: SearchAttributeValue;
+    gte?: SearchAttributeValue;
+    lte?: SearchAttributeValue;
+};
+export type AttributeFilterList<TAttributeKeys extends readonly AttributeFilterKey[]> = {
+    readonly [TIndex in keyof TAttributeKeys]: AttributeFilter<TAttributeKeys[TIndex]>;
+};
+export type TypedListFilter<TAttributeKeys extends readonly AttributeFilterKey[]> = Omit<ListFilter, 'attributes'> & {
+    attributes?: AttributeFilterList<TAttributeKeys>;
+};
+/**
+ * Generic paginated response envelope returned by list operations such as
+ * {@link Engine.list} and `engine.listSchedules`. `total` is the full count
+ * matching the filter; `items` is the current page slice. `items.length` is
+ * bounded by `limit`; the consumer reaches the end of the result set when
+ * `offset + items.length >= total`.
+ */
+export interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    offset: number;
+    limit: number;
+}