@lostgradient/weft 0.3.0 → 0.4.0

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

@@ -1,5 +1,5 @@
 import type { WorkflowId, WorkflowStatus } from './identity.ts';
-import type { SearchAttributeValue } from './search-attributes.ts';
+import type { AttributeFilterScalarValue } from './list-options.ts';
 export declare const MAX_BULK_OPERATION_REQUEST_ID_LENGTH = 200;
 export declare const MAX_BULK_CONFIRMATION_TOKEN_LENGTH = 256;
 /**
@@ -14,7 +14,7 @@ export declare const MAX_BULK_CONFIRMATION_TOKEN_LENGTH = 256;
  * void action;
  * ```
  */
-export type BulkOperationAction = 'cancel' | 'signal' | 'delete' | 'tag:add' | 'tag:remove' | 'recover';
+export type BulkOperationAction = 'cancel' | 'signal' | 'delete' | 'tag:add' | 'tag:remove' | 'retry-failed';
 /**
  * Credential-safe caller summary recorded on bulk audit events. Claims,
  * bearer tokens, API keys, and other credentials are intentionally absent.
@@ -55,11 +55,11 @@ export type BulkOperationFilterSummary = {
     tags?: string[];
     attributes?: Array<{
         key: string;
-        value?: SearchAttributeValue;
-        gt?: SearchAttributeValue;
-        lt?: SearchAttributeValue;
-        gte?: SearchAttributeValue;
-        lte?: SearchAttributeValue;
+        value?: AttributeFilterScalarValue | AttributeFilterScalarValue[];
+        gt?: AttributeFilterScalarValue;
+        lt?: AttributeFilterScalarValue;
+        gte?: AttributeFilterScalarValue;
+        lte?: AttributeFilterScalarValue;
     }>;
     limit?: number;
     offset?: number;
@@ -126,6 +126,16 @@ export type BulkOperationDryRunResult = {
     sampleWorkflowIds: WorkflowId[];
     confirmationToken: string;
     confirmationTokenVersion: 1;
+    /**
+     * Delete-only, point-in-time advisory: ids in the matched scope that currently owe an
+     * engine-driven finalizer (#446) and so would be SKIPPED by the commit (mirrors
+     * {@link BulkDeleteResult.skippedTeardownPending}). Present only on a `delete` preview
+     * and only when non-empty. `matched`, `scope`, and `confirmationToken` still describe
+     * the full filter scope — they are stable and derive the commit token — so this field
+     * surfaces the skip without recomputing them (teardown-owed is transient and is
+     * re-evaluated at commit time, where the authoritative skip list is reported).
+     */
+    skippedTeardownPending?: WorkflowId[];
 };
 /**
  * Options for a dry-run bulk operation preview.
@@ -145,6 +155,7 @@ export type BulkOperationDryRunOptions = {
     dryRun: true;
     requestId?: string;
     principal?: BulkOperationPrincipal;
+    bulkConcurrency?: number;
 };
 /**
  * Options for a committed bulk operation.
@@ -165,6 +176,7 @@ export type BulkOperationCommitOptions = {
     confirmationToken?: string;
     requestId?: string;
     principal?: BulkOperationPrincipal;
+    bulkConcurrency?: number;
 };
 /**
  * Options accepted by bulk workflow operations.
@@ -173,7 +185,7 @@ export type BulkOperationCommitOptions = {
  * ```ts
  * import type { BulkOperationOptions } from '@lostgradient/weft';
  *
- * const options: BulkOperationOptions = { dryRun: true };
+ * const options: BulkOperationOptions = { dryRun: true, bulkConcurrency: 4 };
  * void options;
  * ```
  */
@@ -278,6 +290,29 @@ export type BulkCancelResult = {
     errors: BulkOperationError[];
     auditEvent?: BulkOperationAuditEvent;
 };
+/**
+ * Result of a bulk failed-workflow retry operation (`engine.retryFailedAll`).
+ * Reports the number of workflows accepted for retry, the number that failed
+ * to restart or resume, and per-workflow error details in `errors`.
+ *
+ * @example
+ * ```ts
+ * import type { BulkRetryFailedResult } from '@lostgradient/weft';
+ *
+ * const result: BulkRetryFailedResult = {
+ *   retried: 2,
+ *   failed: 1,
+ *   errors: [{ id: 'wf-3', error: 'Checkpoint no longer exists' }],
+ * };
+ * void result;
+ * ```
+ */
+export type BulkRetryFailedResult = {
+    retried: number;
+    failed: number;
+    errors: BulkOperationError[];
+    auditEvent?: BulkOperationAuditEvent;
+};
 /**
  * Result of a bulk signal operation (`engine.signalAll`). Reports the number
  * of workflows that received the signal and the number for which delivery failed.
@@ -289,10 +324,16 @@ export type BulkSignalResult = {
 };
 /**
  * Result of a bulk delete operation (`engine.deleteAll`). Reports how many
- * terminal workflows were deleted from storage.
+ * terminal workflows were deleted from storage. Workflows that still owe an
+ * engine-driven finalizer (#446) are NOT deleted — deleting them would drop the
+ * finalizer payload before the resource is torn down — and are reported, by id, in
+ * `skippedTeardownPending` so the skip is visible rather than silent. The skip is
+ * transient: once the finalizer settles, a later `deleteAll` removes the record.
  */
 export type BulkDeleteResult = {
     deleted: number;
+    /** Ids of terminal workflows skipped because they still owe a finalizer run. */
+    skippedTeardownPending?: WorkflowId[];
     auditEvent?: BulkOperationAuditEvent;
 };
 /**

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

@@ -3,6 +3,7 @@ import { WeftError } from '../weft-error.ts';
 import type { FailureCategory, OperationId, WorkflowId } from './identity.ts';
 import type { Duration, RetryPolicy } from './retry-retention.ts';
 import type { SearchAttributeValue } from './search-attributes.ts';
+import type { WorkflowLogRecord } from './workflow-log.ts';
 /** Version tag for Worker-mode operation replay signatures stored in checkpoints. */
 export declare const WORKER_REPLAY_SIGNATURE_FORMAT = "weft-worker-operation-signature-v1";
 /**
@@ -69,7 +70,7 @@ export interface WorkerReplayOperationFailure {
 /**
  * Durable snapshot of a workflow's execution state persisted at each
  * `yield` boundary. Contains the accumulated operation results, local
- * variables, pending signals, search attributes, and the step counter.
+ * variables, search attributes, and the step counter.
  * Users don't construct checkpoints directly; the engine manages them.
  * Available via time-travel APIs and {@link WorkflowReplay}.
  *
@@ -91,6 +92,12 @@ export interface Checkpoint {
     step: number;
     locals: Record<string, unknown>;
     accumulatedResults: Array<[number, unknown]>;
+    /**
+     * Highest accumulated-result step whose replay data has been emitted to the
+     * workflow event log. Missing means no consumed results have been emitted yet,
+     * which is how old unpruned checkpoints are read.
+     */
+    accumulatedResultReplayWatermark?: number;
     /**
      * Worker-mode replay guards for cached operation results. Inline execution
      * ignores this optional field; Worker recovery uses it to prove a cached
@@ -103,15 +110,13 @@ export interface Checkpoint {
      * can throw them back into the generator without trusting user result shape.
      */
     workerReplayFailures?: Array<[number, WorkerReplayOperationFailure]>;
-    pendingSignals: string[];
     searchAttributes: Record<string, SearchAttributeValue>;
-    /** User-defined workflow code version. Used for code migrations. */
+    /** User-defined workflow code version. Checked during recovery. */
     version: string;
     /**
      * Checkpoint schema version. Distinct from `version` (which is the
      * user's workflow code version). Bumped whenever the engine changes
-     * the on-disk checkpoint format. Pre-1.0: refuse to load older
-     * versions; post-1.0: every bump must ship a migration.
+     * the on-disk checkpoint format. Pre-1.0: refuse to load older versions.
      */
     schemaVersion: number;
     createdAt: number;
@@ -126,8 +131,9 @@ export interface Checkpoint {
 export declare const CURRENT_CHECKPOINT_SCHEMA_VERSION = 2;
 /**
  * Thrown by `validateCheckpointShape` when a checkpoint's
- * `schemaVersion` does not match the engine's current version. Pre-1.0
- * we refuse to load mismatched checkpoints rather than migrating.
+ * `schemaVersion` does not match the engine's current version. A mismatched
+ * checkpoint is rejected, never upgraded in place: the engine loads only
+ * checkpoints stamped with the exact current schema version.
  */
 export declare class CheckpointSchemaVersionError extends WeftError<'CheckpointSchemaVersionError'> {
     readonly found: number | 'pre-versioned';
@@ -183,7 +189,7 @@ export interface TimerEntry {
     id: string;
     workflowId: WorkflowId;
     fireAt: number;
-    kind: 'sleep' | 'visibility-timeout' | 'execution-deadline' | 'delayed-start' | 'schedule' | 'terminal-cleanup';
+    kind: 'sleep' | 'visibility-timeout' | 'execution-deadline' | 'delayed-start' | 'schedule' | 'terminal-cleanup' | 'teardown' | 'wait-condition';
     executionTimeoutMs?: number;
 }
 export type WorkerInboundMessage = {
@@ -198,6 +204,14 @@ export type WorkerInboundMessage = {
     executionStateOwnerId?: string;
     deadline?: number;
     headers?: [string, string][];
+    /**
+     * Whether the engine host has an `EngineOptions.onLog` sink installed. The
+     * worker routes `ctx.log` records back to the host (as a `log` outbound
+     * message) only when this is `true`; otherwise it logs to the worker's own
+     * console, preserving the default. Omitted (treated as `false`) when no host
+     * sink exists, so a worker can never lose logs to a no-op host callback.
+     */
+    hostHasLogSink?: boolean;
 } | {
     type: 'resume';
     protocolVersion?: number;
@@ -206,6 +220,8 @@ export type WorkerInboundMessage = {
     workflowId: WorkflowId;
     checkpoint: ArrayBuffer;
     operationResult: OperationOutcome;
+    /** See {@link WorkerInboundMessage} `run.hostHasLogSink`; carried on every turn so a rebuilt or resumed worker keeps the capability. */
+    hostHasLogSink?: boolean;
 } | {
     type: 'cancel';
     protocolVersion?: number;
@@ -234,4 +250,24 @@ export type WorkerOutboundMessage = {
     errorStack?: string;
     /** Populated when the execution strategy can classify the failure cause. */
     failureCategory?: FailureCategory;
+} | {
+    /**
+     * A `ctx.log` record forwarded from a worker to the engine host's
+     * `EngineOptions.onLog` sink (#529). Unlike the other variants, `log` is a
+     * NON-TERMINAL, best-effort observability message: it carries no turn-protocol
+     * state, never settles or clears the worker turn, and never reaches the strict
+     * accept-or-discard gate. The host delivers a record to the sink IFF the sending
+     * worker owns `workflowId` (active or parked) AND `record.workflowId` matches the
+     * envelope AND the record is a structurally valid `WorkflowLogRecord` within the
+     * size cap; otherwise the record is dropped — a wrong-owner, malformed, oversize,
+     * or out-of-turn `log` is never a protocol violation and never discards the
+     * worker. A between-turns self-log (a fire-and-forget log resolving while the
+     * worker is parked) IS delivered, because the worker still owns its parked
+     * workflow. The worker emits these only when the inbound message reported
+     * `hostHasLogSink: true`.
+     */
+    type: 'log';
+    protocolVersion?: number;
+    workflowId: WorkflowId;
+    record: WorkflowLogRecord;
 };

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;
+}