@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -0,0 +1,146 @@
+import type { FailureCategory, WorkflowStatus } from './identity.ts';
+import type { SearchAttributeHandle, SearchAttributeValue } from './search-attributes.ts';
+/**
+ * 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, string any-of, 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 AttributeFilterScalarValue = Exclude<SearchAttributeValue, string[]>;
+export type AttributeFilterValue<TKey extends AttributeFilterKey> = TKey extends SearchAttributeHandle<infer TValue> ? TValue extends string[] ? string : TValue : AttributeFilterScalarValue;
+export type AttributeFilterAnyOfValue<TKey extends AttributeFilterKey> = TKey extends SearchAttributeHandle<infer TValue> ? TValue extends string[] ? string[] : TValue extends AttributeFilterScalarValue ? TValue[] : never : AttributeFilterScalarValue[];
+export type AttributeRangeValue<TKey extends AttributeFilterKey> = TKey extends SearchAttributeHandle<infer TValue> ? Extract<TValue, Date | number> : AttributeFilterScalarValue;
+export type AttributeFilter<TKey extends AttributeFilterKey = AttributeFilterKey> = TKey extends SearchAttributeHandle ? {
+    key: TKey;
+    value?: AttributeFilterValue<TKey> | AttributeFilterAnyOfValue<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;
+    /**
+     * Match a single indexed scalar value, or provide a scalar array to match
+     * any listed value for the same attribute.
+     */
+    value?: AttributeFilterScalarValue | AttributeFilterScalarValue[];
+    gt?: AttributeRangeValue<TKey>;
+    lt?: AttributeRangeValue<TKey>;
+    gte?: AttributeRangeValue<TKey>;
+    lte?: AttributeRangeValue<TKey>;
+};
+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;
+}

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

@@ -111,6 +111,31 @@ export interface SignalOptions<TInput = void> {
 export interface SignalDeliveryOptions {
     readonly signalId?: string;
 }
+/**
+ * The signal half of `startOrSignal` (signal-with-start): a signal `name`, an
+ * optional `payload`, and an optional `signalId`. When `signalId` is omitted it
+ * is derived from `options.idempotencyKey`. The id is load-bearing for
+ * convergence — concurrent callers deliver one signal only when they share it,
+ * and independent webhook retries share only the idempotency key — so a
+ * caller-supplied `signalId` covers the single-caller case while idempotent
+ * convergence relies on the derived-from-key value.
+ *
+ * @example
+ * ```ts
+ * import type { StartOrSignalSignal } from '@lostgradient/weft';
+ *
+ * const signal: StartOrSignalSignal = {
+ *   name: 'webhook',
+ *   payload: { event: 'payment.succeeded' },
+ * };
+ * void signal;
+ * ```
+ */
+export interface StartOrSignalSignal {
+    readonly name: string;
+    readonly payload?: unknown;
+    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

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

@@ -4,24 +4,40 @@ 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 { SearchAttributeValue } from './search-attributes.ts';
 import type { Serializer } from './serializer.ts';
+import type { WorkflowServicesResolution, WorkflowServicesResolverInfo } from './services-resolution.ts';
+import type { WorkflowLogRecord } from './workflow-log.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
+ * `idempotencyKey` enforces at-most-once starts (a repeated key returns the
+ * existing run instead of starting a second, even after it reaches a terminal
+ * state); `executionTimeout` caps wall-clock time; `startAt`/`startAfter` defer
  * execution; `tags` and `searchAttributes` make the workflow discoverable
- * via filters.
+ * via filters. `id` and `idempotencyKey` are mutually exclusive — idempotency
+ * assigns its own generated id and dedups through the key.
  *
- * `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.
+ * This is the shared base accepted by every start-like surface
+ * (`engine.start`, `engine.startOrSignal`, and the clients). `engine.start`
+ * specifically accepts the wider {@link StartWorkflowOptions}, which adds
+ * `onTerminalConflict`; that policy is intentionally absent here so it cannot be
+ * passed to `startOrSignal` (whose at-most-once identity is the permanent
+ * idempotency mapping).
+ *
+ * The `idempotencyKey` mapping is durable and permanent: it survives the run
+ * reaching a terminal state, so repeat calls keep returning the same handle. When
+ * the workflow record is purged or swept by retention the mapping itself survives
+ * (purge does not touch the `start-idem:` keyspace) but now points at a gone run;
+ * a call with that spent key throws {@link IdempotencyKeyPurgedError} (mapped to
+ * HTTP 409 over REST/JSON-RPC) rather than silently starting a new run.
+ *
+ * Both `LocalClient.start` and `HttpClient.start` forward `idempotencyKey` and
+ * `searchAttributes` to the server, so single-execution semantics hold across
+ * transports. Idempotent start requires a storage backend with `conditionalBatch`.
  *
  * @example Start a delayed workflow with tags and search attributes
  * ```ts
@@ -44,7 +60,7 @@ import type { Serializer } from './serializer.ts';
  * void handle;
  * ```
  */
-export interface StartOptions {
+export interface StartOptions<TServices = unknown> {
     id?: string;
     idempotencyKey?: string;
     executionTimeout?: Duration;
@@ -63,54 +79,61 @@ export interface StartOptions {
      * `workflowExecutionMode: 'worker'` throws at `engine.start()`, because a
      * non-serializable value cannot cross to a Worker.
      */
-    services?: unknown;
+    services?: TServices;
+    /**
+     * When `false`, `engine.start()` resolves only after the workflow has begun
+     * executing (its generator has been driven its first turn), not merely after
+     * the initial state is persisted. The default (`true`) returns a handle as
+     * soon as state is written and queues execution onto a macrotask, so a caller
+     * cannot assume the run is live without a round-trip. Use `defer: false` when a
+     * caller — or a test — must rely on the run being live immediately after
+     * `await engine.start(...)`. If the body throws on its first turn, `start()`
+     * still resolves; observe the failure via `handle.result()`. Inline mode only;
+     * throws at `engine.start()` under `workflowExecutionMode: 'worker'` or with a
+     * delayed start (`startAt`/`startAfter`), neither of which has liveness to await.
+     */
+    defer?: boolean;
 }
 /**
- * Result of {@link EngineOptions.resolveWorkflowServices}. An explicit union
- * rather than a nullable return: `'unavailable'` is a deliberate, named outcome
- * (the run's dependencies cannot be rebuilt in this process) that fails just
- * that recovered run — it does not overload the resolved value with a lifecycle
- * signal.
- *
- * @example
- * ```ts
- * import { type WorkflowServicesResolution } from '@lostgradient/weft';
- *
- * const ok: WorkflowServicesResolution = {
- *   status: 'available',
- *   services: { db: { query: () => [] } },
- * };
- * const no: WorkflowServicesResolution = { status: 'unavailable', reason: 'no config' };
- * void ok;
- * void no;
- * ```
- */
-export type WorkflowServicesResolution = {
-    status: 'available';
-    services: unknown;
-} | {
-    status: 'unavailable';
-    reason: string;
-};
-/**
- * Information passed to {@link EngineOptions.resolveWorkflowServices} for each
- * recovered workflow. `input` is the original durable launch input, available
- * at resume time — typically enough to rebuild the run's dependencies (tenant,
- * model, tool registry) without a side table.
- *
- * @example
- * ```ts
- * import { type WorkflowServicesResolverInfo } from '@lostgradient/weft';
+ * Options accepted by `engine.start(type, input, options?)` — the shared
+ * {@link StartOptions} plus the start-only `onTerminalConflict` policy.
  *
- * function describe(info: WorkflowServicesResolverInfo): string {
- *   return `${info.workflowType}/${info.workflowId}`;
- * }
- * ```
+ * `onTerminalConflict` lives here, not on {@link StartOptions}, so it is
+ * structurally rejected on every other start-like surface: `engine.startOrSignal`
+ * (whose identity is the permanent at-most-once idempotency mapping),
+ * `ctx.startChild` (which re-attaches to an existing run by id on replay), and the
+ * REST/JSON-RPC transport (which keeps `weft.workflows.start` honestly
+ * `destructive: false`). It is therefore an in-process `engine.start`-only policy.
  */
-export interface WorkflowServicesResolverInfo {
-    workflowId: string;
-    workflowType: string;
-    input: unknown;
+export interface StartWorkflowOptions<TServices = unknown> extends StartOptions<TServices> {
+    /**
+     * What `engine.start()` does when the supplied `id` already belongs to a run
+     * that has reached a **terminal** state (`completed` | `failed` | `cancelled`
+     * | `timed-out`). This is Weft's equivalent of Temporal's
+     * `WorkflowIdReusePolicy.ALLOW_DUPLICATE`, for the common case of a periodic
+     * job keyed by a stable id (e.g. `reconcile:installation-42`) whose previous
+     * run has already finished.
+     *
+     * - `'error'` (default): preserve the existing contract — a duplicate id always
+     *   throws {@link WorkflowAlreadyExistsError}, terminal or not.
+     * - `'start-new'`: if the prior run under this id is terminal, purge it (while
+     *   holding the in-process start reservation, the same teardown as
+     *   `engine.purge`, sweeping every key the run owns) and start a fresh run in
+     *   its place; if the prior run is still **non-terminal** (running/pending),
+     *   throw {@link WorkflowAlreadyExistsError} unchanged — `'start-new'` never
+     *   displaces a live run.
+     *
+     * Requires an explicit `id` (the policy only makes sense for a caller-chosen,
+     * reusable id) and is mutually exclusive with `idempotencyKey` (whose mapping
+     * is permanent and at-most-once — restarting under it would violate that
+     * contract). The previous run's durable record is gone after a `'start-new'`
+     * restart, so a {@link WorkflowHandle} held against the old id resolves to the
+     * fresh run for every method (`result()`, `snapshot()`, status), because handles
+     * are id-scoped, not run-attempt-scoped. The restart holds the same in-process
+     * start reservation as a normal start, so two concurrent `'start-new'` calls for
+     * one id cannot both win — the loser sees {@link WorkflowAlreadyExistsError}.
+     */
+    onTerminalConflict?: 'error' | 'start-new';
 }
 /**
  * Options for {@link Engine.fork}. Controls which checkpoint step to fork
@@ -155,13 +178,87 @@ export interface ForkOptions {
  * void engine;
  * ```
  */
-export interface EngineOptions {
+export interface EngineOptions<TServices = unknown> {
     storage?: WeftStorage;
     development?: boolean;
     serializer?: Serializer;
     retention?: RetentionPolicy;
     retentionSweepInterval?: Duration;
     retentionSweepBatchSize?: number;
+    /**
+     * Enable a best-effort, warn-only detector for a SECOND engine instance writing
+     * to the same durable store — a smoke alarm for singleton misconfiguration (an
+     * autoscaler above one replica, or overlapping rolling deploys). Default `false`.
+     * This is **liveness, not fencing**: it never blocks boot, gates recovery, or
+     * prevents duplicate execution — enforce one instance at the infrastructure layer
+     * (one replica + a `Recreate` deploy, or a single systemd unit). When enabled,
+     * each engine writes a periodic heartbeat and warns (`process.emitWarning`) when
+     * it sees another instance's heartbeat advancing while it runs. The periodic
+     * writes are an ongoing cost, so leave it off unless you want the backstop.
+     */
+    detectSecondInstance?: boolean;
+    /**
+     * Heartbeat interval for {@link EngineOptions.detectSecondInstance} (default
+     * `15s`). A foreign heartbeat must advance across two intervals before warning,
+     * so this also sets how long a deploy overlap must last before it warns — keep it
+     * well above your deploy drain window. Ignored when detection is disabled.
+     */
+    secondInstanceHeartbeatInterval?: Duration;
+    /**
+     * Single-writer ownership posture over the shared durable store. Default
+     * `'none'` — the engine recovers immediately at boot and relies on
+     * infrastructure (one replica + a `Recreate` deploy) for mutual exclusion.
+     *
+     * `'lease'` opts into a storage-keyed ownership lease: at boot the engine
+     * acquires the lease (waiting, up to {@link EngineOptions.leaseWaitTimeout}, if
+     * another instance still holds it) **before** recovering, renews it on a
+     * heartbeat, and releases it on dispose. This turns a rolling deploy into a
+     * clean handoff — the incoming instance parks until the outgoing one releases
+     * (or its lease expires), so the two never recover concurrently.
+     *
+     * Requires a storage backend with the `conditionalBatch` capability (every
+     * durable recovery backend already provides it).
+     *
+     * **Step-1 acquisition boundary.** The lease is acquired on the standard boot
+     * paths — `Engine.create()` and `Engine.recoverAll()` (so `new Engine({ ownership:
+     * 'lease' })` followed by `recoverAll()` acquires it too). It is **not** yet
+     * acquired on a first durable write, so a `new Engine({ ownership: 'lease' })`
+     * that calls `engine.start(...)` *without* ever calling `recoverAll()` will write
+     * without holding the lease. Use `Engine.create()` (or call `recoverAll()` before
+     * accepting traffic) so acquisition runs before any write.
+     *
+     * **Lease alone is deploy ergonomics, not a correctness guarantee.** It
+     * prevents the *new* instance from recovering early; it does not by itself stop
+     * a stalled *old* instance (e.g. a long GC pause past the lease TTL) from
+     * writing after its lease expired. Epoch fencing of durable writes is what
+     * closes that gap. Keep infrastructure-level single-instance enforcement as the
+     * real control.
+     */
+    ownership?: 'none' | 'lease';
+    /**
+     * Lease time-to-live for `ownership: 'lease'` (default `30s`). A holder renews
+     * well within this window; once it lapses without renewal, a waiting instance
+     * may steal the lease. Must comfortably exceed the renewal interval plus the
+     * worst-case GC pause, clock skew, and storage round-trip. Ignored when
+     * `ownership` is not `'lease'`.
+     */
+    leaseTtl?: Duration;
+    /**
+     * Lease renewal interval for `ownership: 'lease'` (default `5s`). The holder
+     * re-asserts the lease this often; keep it well below {@link EngineOptions.leaseTtl}
+     * so a single slow renewal cannot let the lease lapse. Ignored when `ownership`
+     * is not `'lease'`.
+     */
+    leaseRenewInterval?: Duration;
+    /**
+     * How long a booting `ownership: 'lease'` instance waits to acquire the lease
+     * when another instance still holds it, before throwing
+     * {@link EngineLeaseAcquisitionTimeoutError} (default `60s`). Size this above
+     * both the outgoing instance's drain time and the lease TTL, so a graceful
+     * handoff and a crash (no clean release, lease expires after TTL) both resolve.
+     * Ignored when `ownership` is not `'lease'`.
+     */
+    leaseWaitTimeout?: Duration;
     /**
      * History circuit-breaker thresholds. When `history.maxEvents` is set, a
      * workflow whose event-log record count would exceed it is forced to a
@@ -267,8 +364,9 @@ export interface EngineOptions {
      * Return `{ status: 'available', services }` to supply the rebuilt
      * capabilities, or `{ status: 'unavailable', reason }` to fail just that one
      * recovered run — the engine and every other recovered run are unaffected.
-     * Without a resolver, a recovered inline workflow that reads `ctx.services`
-     * sees `undefined`.
+     * Without a resolver, a recovered run that carries the durable "expects
+     * services" marker fails before the generator advances and emits a diagnostic
+     * warning naming this option.
      *
      * Contract a fresh integrator must know:
      * - Fires only for recovered inline runs that were launched WITH `services`
@@ -285,165 +383,17 @@ export interface EngineOptions {
      * Engine-scoped: each engine instance carries its own resolver, so two engines
      * in one process never collide on per-run dependency reconstruction.
      */
-    resolveWorkflowServices?: (info: WorkflowServicesResolverInfo) => WorkflowServicesResolution | Promise<WorkflowServicesResolution>;
-}
-/**
- * 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[];
+    resolveWorkflowServices?: (info: WorkflowServicesResolverInfo) => WorkflowServicesResolution<TServices> | Promise<WorkflowServicesResolution<TServices>>;
     /**
-     * Match workflows by registered workflow type (e.g. `'order-fulfillment'`).
+     * Optional host sink for `ctx.log` records. When provided, every non-replayed
+     * record from inline workflow execution is routed here (into your pino / winston
+     * / OpenTelemetry stack, etc.) **instead of** the console; when omitted, records
+     * fall back to the matching `console` method, preserving the default behavior.
      *
-     * @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.
+     * Engine-scoped infrastructure: set once at construction, never per run. The sink
+     * is not invoked for records suppressed during replay, so a recovered run does
+     * not re-emit its replayed prefix. Worker-mode records still log to the worker
+     * process's console — routing them back to the host is tracked separately.
      */
-    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;
+    onLog?: (record: WorkflowLogRecord) => void;
 }

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

@@ -54,7 +54,8 @@ export type ReviewStatus = 'pending' | 'completed';
  * Filter accepted by `engine.listReviews(filter?)` and the `/v1/reviews`
  * transport surfaces.
  *
- * Omitting `status` preserves the legacy pending-only behavior.
+ * Omitting `status` lists pending reviews; pass `status: 'completed'` to list
+ * completed reviews instead.
  *
  * @example
  * ```ts