@lostgradient/weft 0.2.0

package/dist/core/timeouts.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Workflow-level execution timeouts with durable deadline storage.
+ *
+ * Deadlines are stored as lexicographically sortable keys so that
+ * a single prefix scan can discover all expired workflows.
+ *
+ * @module timeouts
+ */
+import type { BatchOperation, Storage } from '../storage/interface';
+import type { Duration, WorkflowId } from './types';
+import { WeftError } from './weft-error';
+export interface ExpiredDeadline {
+    workflowId: string;
+    deadline: number;
+}
+/**
+ * Create batch operations for storing an execution deadline.
+ *
+ * @example
+ * ```ts
+ * import { createDeadlineOperations } from '@lostgradient/weft';
+ *
+ * const ops = createDeadlineOperations('wf-123', Date.now(), '30m');
+ * // Returns a BatchOperation array to put the deadline key in storage.
+ * console.log(ops.length);      // 1
+ * console.log(ops[0]?.type);    // 'put'
+ * ```
+ */
+export declare function createDeadlineOperations(workflowId: WorkflowId, startedAt: number, executionTimeout: Duration): BatchOperation[];
+/** Create batch operations to clean up deadline entries for a workflow. */
+export declare function cleanupDeadlineOperations(workflowId: WorkflowId, deadline: number): BatchOperation[];
+/**
+ * Scan storage for expired deadlines. Returns workflow IDs that have timed out.
+ *
+ * @example
+ * ```ts
+ * import { checkExpiredDeadlines, createDeadlineOperations } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const ops = createDeadlineOperations('wf-abc', Date.now() - 60_000, '30s');
+ * await storage.batch(ops);
+ *
+ * const expired = await checkExpiredDeadlines(storage, Date.now());
+ * console.log(expired[0]?.workflowId); // 'wf-abc'
+ * ```
+ */
+export declare function checkExpiredDeadlines(storage: Storage, now: number): Promise<ExpiredDeadline[]>;
+/**
+ * Calculate remaining time before deadline. Returns Infinity if no deadline.
+ *
+ * @example
+ * ```ts
+ * import { timeRemaining } from '@lostgradient/weft';
+ *
+ * const now = Date.now();
+ * const deadline = now + 5000;
+ *
+ * console.log(timeRemaining(deadline, now));       // ~5000
+ * console.log(timeRemaining(undefined, now));      // Infinity
+ * console.log(timeRemaining(now - 1000, now) < 0); // true (expired)
+ * ```
+ */
+export declare function timeRemaining(deadline: number | undefined, now: number): number;
+/**
+ * Thrown inside a workflow generator when it exceeds its configured execution
+ * or run timeout. Also available as an event via {@link WorkflowTimedOutEvent}.
+ * The `timeoutType` distinguishes `'execution'` (wall-clock cap set via
+ * {@link StartOptions.executionTimeout}) from `'run'` (per-step run timeout).
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, WorkflowTimeoutError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(
+ *   workflow({ name: 'slow' }).execute(async function* () {
+ *     await new Promise(resolve => setTimeout(resolve, 60_000));
+ *     return 'done';
+ *   }),
+ * );
+ *
+ * try {
+ *   const handle = await engine.start('slow', null, { executionTimeout: '1s' });
+ *   await handle.result();
+ * } catch (err) {
+ *   if (err instanceof WorkflowTimeoutError) {
+ *     console.error('timed out after', err.elapsed, 'ms, type:', err.timeoutType);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowTimeoutError extends WeftError<'WorkflowTimeoutError'> {
+    readonly workflowId: string;
+    readonly timeoutType: 'execution' | 'run';
+    readonly elapsed: number;
+    constructor(workflowId: string, timeoutType: 'execution' | 'run', elapsed: number);
+}

package/dist/core/timeouts.js

@@ -0,0 +1,38 @@
+import { KEYS, resolvePrefixRangeEnd } from "../storage/interface.js";
+import { decode, encode } from "./codec.js";
+import { normalizeStorageTimestamp, parseDuration } from "./scheduler.js";
+import { WeftError } from "./weft-error.js";
+export function createDeadlineOperations(workflowId, startedAt, executionTimeout) {
+  const timeoutMilliseconds = parseDuration(executionTimeout), deadline = normalizeStorageTimestamp(startedAt + timeoutMilliseconds, "Workflow execution deadline");
+  return [{ type: "put", key: KEYS.deadline(deadline, workflowId), value: encode({ workflowId, deadline }) }];
+}
+export function cleanupDeadlineOperations(workflowId, deadline) {
+  return [{ type: "delete", key: KEYS.deadline(deadline, workflowId) }];
+}
+export async function checkExpiredDeadlines(storage, now) {
+  const expired = [];
+  for await (const [, value] of storage.scan("wf-deadline:", {
+    lt: resolvePrefixRangeEnd(KEYS.deadline(now, ""))
+  })) {
+    const entry = decode(value);
+    expired.push({ workflowId: entry.workflowId, deadline: entry.deadline });
+  }
+  return expired;
+}
+export function timeRemaining(deadline, now) {
+  if (deadline === void 0)
+    return 1 / 0;
+  return deadline - now;
+}
+
+export class WorkflowTimeoutError extends WeftError {
+  workflowId;
+  timeoutType;
+  elapsed;
+  constructor(workflowId, timeoutType, elapsed) {
+    super("WorkflowTimeoutError", `Workflow "${workflowId}" exceeded ${timeoutType} timeout after ${elapsed}ms`);
+    this.workflowId = workflowId;
+    this.timeoutType = timeoutType;
+    this.elapsed = elapsed;
+  }
+}

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

@@ -0,0 +1,316 @@
+import type { DefinitionSchema, InferSchemaOutput } from './definition-schema.ts';
+import type { Duration, RetryPolicy } from './retry-retention.ts';
+/**
+ * Type signature for an activity execute function. Receives the activity
+ * input and an optional {@link ActivityContext} (for heartbeating and
+ * cancellation signals), and returns a value or a promise. Use this type
+ * when defining the `execute` field of an {@link ActivityDefinition}.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityFunction } from '@lostgradient/weft';
+ *
+ * const fetchUserFn: ActivityFunction<string, { id: string; name: string }> =
+ *   async (input, ctx) => {
+ *     ctx?.signal.throwIfAborted();
+ *     const response = await fetch(`https://api.example.com/users/${input}`);
+ *     return (await response.json()) as { id: string; name: string };
+ *   };
+ * void fetchUserFn;
+ * ```
+ */
+export type ActivityFunction<TInput = unknown, TOutput = unknown> = (input: TInput, context?: ActivityContext) => Promise<TOutput> | TOutput;
+/**
+ * Runtime context injected as the second argument of every activity execute
+ * function. Use `signal` to honour cancellation, and call `heartbeat` to
+ * report progress and extend the activity's visibility timeout on long-running
+ * work.
+ *
+ * @example
+ * ```ts
+ * import { activity, type ActivityContext } from '@lostgradient/weft';
+ *
+ * const processChunks = activity({
+ *   name: 'processChunks',
+ *   execute: async (input: unknown, ctx?: ActivityContext) => {
+ *     const items = input as string[];
+ *     for (const item of items) {
+ *       ctx?.signal.throwIfAborted();
+ *       ctx?.heartbeat({ processed: item });
+ *     }
+ *     return items.length;
+ *   },
+ * });
+ * void processChunks;
+ * ```
+ */
+export interface ActivityContext {
+    signal: AbortSignal;
+    heartbeat(details?: unknown): void;
+    /**
+     * Defer this activity to out-of-band completion. Calling `completeAsync()`
+     * hands the work off to an external system — a webhook, a human callback, a
+     * third-party async job — and suspends the workflow at this step until
+     * something outside the engine resolves the activity by its task token via
+     * `engine.completeAsyncActivity(token, result)` /
+     * `engine.failAsyncActivity(token, error)` (or the matching
+     * `client.activity.*` methods).
+     *
+     * The durable task token is announced on the engine as an
+     * `activity:async-pending` event (listen for it to receive the token).
+     * The token is deterministic and survives engine restart: it is re-minted
+     * identically when the activity replays after recovery.
+     *
+     * Security: the token is a deterministic identifier, NOT a secret. When the
+     * completion endpoint is reachable by untrusted callers, anyone who can infer
+     * a workflow id can forge this activity's result or error. Treat the completed
+     * value as hostile external input (validate it as you would a signal payload),
+     * and gate the mutating surface with `serve({ auth })` if completions must not
+     * be anonymous.
+     *
+     * `completeAsync()` never returns normally — it throws an internal sentinel
+     * that the engine recognizes to park the activity. Call it as the last
+     * statement of (or `return` it from) the activity, and do not catch the
+     * thrown sentinel.
+     *
+     * @example
+     * ```ts
+     * import { activity, type ActivityContext } from '@lostgradient/weft';
+     *
+     * const awaitWebhook = activity({
+     *   name: 'awaitWebhook',
+     *   execute: async (input: { callbackUrl: string }, ctx?: ActivityContext) => {
+     *     await fetch(input.callbackUrl, { method: 'POST' });
+     *     return ctx!.completeAsync();
+     *   },
+     * });
+     * void awaitWebhook;
+     * ```
+     */
+    completeAsync(): never;
+}
+/**
+ * Per-invocation overrides when calling an activity from a workflow via
+ * `ctx.run(activity, input, options)`. Any field overrides the
+ * activity's own defaults for that single call. Useful for increasing the
+ * timeout on a retried call or routing to a specific queue.
+ *
+ * @example
+ * ```ts
+ * import { workflow, activity, Engine, type ActivityCallOptions, type WorkflowContext } from '@lostgradient/weft';
+ *
+ * const slowTask = activity({ name: 'slowTask', execute: async (i: unknown) => i });
+ * const engine = new Engine();
+ *
+ * engine.register(
+ *   workflow({ name: 'example' }).execute(async function* (ctx: WorkflowContext, input: unknown) {
+ *     const options: ActivityCallOptions = { timeout: '5m', queue: 'heavy' };
+ *     const result = yield* ctx.run(slowTask, input, options);
+ *     return result;
+ *   }),
+ * );
+ * void engine;
+ * ```
+ */
+export interface ActivityCallOptions {
+    timeout?: Duration;
+    queue?: string;
+    retry?: Partial<RetryPolicy>;
+    idempotencyKey?: string;
+    sticky?: boolean;
+    /** Override the default visibility timeout for this invocation. */
+    visibilityTimeout?: Duration;
+}
+/**
+ * Identifies whether an activity verifier is checking a fresh result or
+ * reconciling a prior keyed dispatch before redispatch.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationPhase } from '@lostgradient/weft';
+ *
+ * const phase: ActivityVerificationPhase = 'pre-dispatch-reconciliation';
+ * console.log(phase);
+ * ```
+ */
+export type ActivityVerificationPhase = 'post-execution-validation' | 'pre-dispatch-reconciliation';
+/**
+ * Metadata passed to a Tier-0 activity verifier.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationContext } from '@lostgradient/weft';
+ *
+ * function shouldQueryExternalSystem(context: ActivityVerificationContext): boolean {
+ *   return context.phase === 'pre-dispatch-reconciliation';
+ * }
+ * ```
+ */
+export interface ActivityVerificationContext<TInput = unknown> {
+    phase: ActivityVerificationPhase;
+    workflowId: string;
+    activityName: string;
+    operationId: string;
+    input: TInput;
+    idempotencyKey?: string;
+    attempt: number;
+}
+/**
+ * Return value for activity verification. Post-execution validation uses a
+ * boolean; pre-dispatch reconciliation can report whether a prior keyed side
+ * effect completed, did not complete, or is indeterminate.
+ *
+ * @example
+ * ```ts
+ * import type { ActivityVerificationResult } from '@lostgradient/weft';
+ *
+ * const result: ActivityVerificationResult<string> = {
+ *   status: 'completed-with-result',
+ *   result: 'already-finished',
+ * };
+ * console.log(result.status);
+ * ```
+ */
+export type ActivityVerificationResult<TOutput = unknown> = boolean | 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
+    status: 'completed-with-result';
+    result: TOutput;
+};
+export type ActivityPostExecutionVerifier<TOutput = unknown> = {
+    bivarianceHack(result: TOutput): Promise<boolean> | boolean;
+}['bivarianceHack'];
+export type ActivityTier0Verifier<TInput = unknown, TOutput = unknown> = {
+    bivarianceHack(result: TOutput | undefined, context: ActivityVerificationContext<TInput>): Promise<ActivityVerificationResult<TOutput>> | ActivityVerificationResult<TOutput>;
+}['bivarianceHack'];
+export type ActivityVerifier<TInput = unknown, TOutput = unknown> = ActivityPostExecutionVerifier<TOutput> | ActivityTier0Verifier<TInput, TOutput>;
+/**
+ * Full metadata for an activity, combining the execute function with optional
+ * retry policy, timeout, queue routing, compensation, and idempotency. Built
+ * by the {@link activity} helper which returns a value that satisfies both
+ * `ActivityDefinition` and the callable function interface.
+ *
+ * @example
+ * ```ts
+ * import { activity, type ActivityDefinition } from '@lostgradient/weft';
+ *
+ * const sendEmail: ActivityDefinition<{ to: string; body: string }, void> = activity({
+ *   name: 'sendEmail',
+ *   timeout: '30s',
+ *   retry: { maxAttempts: 3, initialBackoff: '1s', backoffMultiplier: 2, maxBackoff: '10s' },
+ *   execute: async (input: { to: string; body: string }) => {
+ *     const { to, body } = input;
+ *     console.log(`Sending to ${to}: ${body}`);
+ *   },
+ * });
+ * void sendEmail;
+ * ```
+ */
+export interface ActivityDefinition<TInput = unknown, TOutput = unknown, TName extends string = string> {
+    /** Stable activity name used for registration, dispatch, and introspection. */
+    name: TName;
+    /** User-facing description for catalog, code generation, and tool surfaces. */
+    description?: string;
+    /** User-facing grouping tags for catalog and documentation surfaces. */
+    tags?: ReadonlyArray<string>;
+    /** Optional input schema metadata for introspection; registration validates metadata shape only. */
+    inputSchema?: DefinitionSchema<unknown, TInput>;
+    /** Optional output schema metadata for introspection; registration validates metadata shape only. */
+    outputSchema?: DefinitionSchema<unknown, TOutput>;
+    /** Activity implementation called by the engine or worker. */
+    execute: ActivityFunction<TInput, TOutput>;
+    /**
+     * Optional post-execution verifier.
+     *
+     * During normal post-execution validation, return `true` to confirm the
+     * activity result or `false` to reject it. During pre-dispatch crash recovery
+     * for keyed activities, return an explicit reconciliation state; legacy boolean
+     * answers are not treated as proof of external completion.
+     */
+    verify?: ActivityVerifier<TInput, TOutput>;
+    retry?: RetryPolicy;
+    timeout?: Duration;
+    queue?: string;
+    idempotent?: boolean;
+    /** Visibility timeout for this activity. Defaults to 30 seconds. */
+    visibilityTimeout?: Duration;
+    /**
+     * Optional compensation function. When defined and a saga step that ran this
+     * activity needs to be rolled back, the engine calls `compensate(input, output)`
+     * in reverse order for every step that completed before the failure.
+     * Inline cancellation-triggered compensation is best-effort and runs outside
+     * the durable activity pipeline; it is not replayed after an engine restart.
+     *
+     * `input` is the original input passed to `execute`.
+     * `output` is the value returned by `execute` for that invocation.
+     */
+    compensate?: (input: TInput, output: TOutput) => Promise<void> | void;
+    /**
+     * Optional function that returns a resource scope string for this activity.
+     * Used for resource-level locking or throttling; the returned string is
+     * treated as an opaque identifier by the engine.
+     */
+    resourceScope?: (input: TInput) => string;
+    /**
+     * Optional function that returns an idempotency key specific to an
+     * invocation. Takes precedence over `ActivityCallOptions.idempotencyKey`.
+     */
+    idempotencyKey?: (input: TInput) => string;
+}
+/**
+ * Callable activity value returned by {@link activity}. It carries the activity
+ * metadata used for registration and can also be invoked directly in tests or
+ * helper code with the same single input value passed to `ctx.run`.
+ *
+ * @example
+ * ```ts
+ * import { activity, type ActivityCallable } from '@lostgradient/weft';
+ *
+ * const normalizeEmail: ActivityCallable<string, string> = activity(async function normalizeEmail(
+ *   input: string,
+ * ) {
+ *   return input.trim().toLowerCase();
+ * });
+ *
+ * const normalized = await normalizeEmail(' Ada@example.com ');
+ * void normalized;
+ * ```
+ */
+export type ActivityCallable<TInput, TOutput, TName extends string = string> = ActivityDefinition<TInput, TOutput, TName> & {
+    readonly _types?: {
+        readonly input: TInput;
+        readonly output: TOutput;
+    };
+} & ([TInput] extends [void] ? (input?: TInput, context?: ActivityContext) => Promise<TOutput> : (input: TInput, context?: ActivityContext) => Promise<TOutput>);
+/**
+ * Create an activity with colocated configuration.
+ * The returned value is both an ActivityDefinition and a callable function.
+ *
+ * @example
+ * ```ts
+ * import { activity } from '@lostgradient/weft';
+ *
+ * const fetchUser = activity({
+ *   name: 'fetchUser',
+ *   execute: async (input: unknown) => {
+ *     const id = input as string;
+ *     return { id, name: 'Alice' };
+ *   },
+ * });
+ *
+ * // Use in a workflow via ctx.run:
+ * // const user = yield* ctx.run(fetchUser, userId);
+ * void fetchUser;
+ * ```
+ */
+export declare function activity<TOutput>(execute: () => Promise<TOutput> | TOutput): ActivityCallable<void, TOutput>;
+export declare function activity<TInput, TOutput>(execute: ActivityFunction<TInput, TOutput>): ActivityCallable<TInput, TOutput>;
+export declare function activity<const TName extends string, TOutput>(options: Omit<ActivityDefinition<void, TOutput, TName>, 'execute'> & {
+    execute: () => Promise<TOutput> | TOutput;
+}): ActivityCallable<void, TOutput, TName>;
+export declare function activity<const TName extends string, TInputSchema extends DefinitionSchema<unknown, unknown>, TOutputSchema extends DefinitionSchema<unknown, unknown>>(options: Omit<ActivityDefinition<InferSchemaOutput<TInputSchema>, InferSchemaOutput<TOutputSchema>, TName>, 'inputSchema' | 'outputSchema'> & {
+    inputSchema: TInputSchema;
+    outputSchema: TOutputSchema;
+}): ActivityCallable<InferSchemaOutput<TInputSchema>, InferSchemaOutput<TOutputSchema>, TName>;
+export declare function activity<const TName extends string, TInputSchema extends DefinitionSchema<unknown, unknown>, TOutput>(options: Omit<ActivityDefinition<InferSchemaOutput<TInputSchema>, TOutput, TName>, 'inputSchema'> & {
+    inputSchema: TInputSchema;
+}): ActivityCallable<InferSchemaOutput<TInputSchema>, TOutput, TName>;
+export declare function activity<const TName extends string, TInput, TOutput>(options: ActivityDefinition<TInput, TOutput, TName>): ActivityCallable<TInput, TOutput, TName>;

package/dist/core/types/activity.js

@@ -0,0 +1,15 @@
+import { validateWorkflowOrActivityName } from "./name-grammar.js";
+export function activity(input) {
+  const options = typeof input === "function" ? {
+    name: input.name,
+    execute: input
+  } : input;
+  if (!options.name)
+    throw Error("activity() requires a named function or an options object with name.");
+  validateWorkflowOrActivityName(options.name, "activity");
+  const fn = (inputValue, activityContext) => options.execute(inputValue, activityContext), { name, execute, ...rest } = options;
+  Object.assign(fn, rest);
+  Object.defineProperty(fn, "name", { value: name, configurable: !0 });
+  Object.defineProperty(fn, "execute", { value: execute, enumerable: !0, configurable: !0 });
+  return fn;
+}

package/dist/core/types/archive-adapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Operator-supplied hook for archiving event-log records that event-log
+ * compaction is about to discard.
+ *
+ * @module core/types/archive-adapter
+ */
+/**
+ * An operator-supplied object-store sink for compacted event-log ranges.
+ *
+ * When an {@link ArchiveAdapter} is configured (via `EngineOptions.archive`),
+ * event-log compaction serializes each deleted range and calls {@link store}
+ * **after** the truncation has committed durably.
+ *
+ * > [!WARNING]
+ * > This is a best-effort **export notification, not a durability guarantee.**
+ * > The deleted records are removed from primary storage regardless of whether
+ * > `store` resolves, rejects, or throws — compaction never rolls back on an
+ * > archive failure. Operators who need guaranteed archival must implement
+ * > their own durability before the records are compacted (the engine does not
+ * > provide a pre-deletion durability barrier).
+ *
+ * @example
+ * ```ts
+ * import type { ArchiveAdapter } from '@lostgradient/weft';
+ *
+ * const adapter: ArchiveAdapter = {
+ *   async store(workflowId, key, bytes) {
+ *     // e.g. write `bytes` to object storage under `${workflowId}/${key}`
+ *     void workflowId;
+ *     void key;
+ *     void bytes;
+ *   },
+ * };
+ * void adapter;
+ * ```
+ */
+export type ArchiveAdapter = {
+    /**
+     * Persist a serialized, compacted event-log range.
+     *
+     * @param workflowId  The workflow whose history was compacted.
+     * @param key         A range identifier of the form `events:{from}-{to}`
+     *   (inclusive sequence bounds of the deleted records). The adapter owns its
+     *   own storage namespace; this key is not a `weft` storage key.
+     * @param bytes       The serialized deleted records (see
+     *   `serializeDeletedEntries`).
+     */
+    store(workflowId: string, key: string, bytes: Uint8Array): Promise<void>;
+};