@lostgradient/weft 0.3.0 → 0.5.0

package/dist/core/persisted-data-incompatible-error.d.ts

@@ -1,15 +1,17 @@
 import { WeftError } from './weft-error.ts';
 /**
  * Thrown by {@link Engine.create} (and other storage-opening entry points) when
- * a persisted Weft database carries a schema version older than the engine
- * understands. Pre-MVP Weft does not migrate persisted data — bumping
- * {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION} intentionally invalidates older
- * databases so the failure surfaces deterministically at boot, before any
- * workflow attempts replay.
+ * a persisted Weft database's schema version does not match what the engine
+ * requires — an older version, a newer one, an unparseable sentinel, or user
+ * data present with no sentinel at all. Weft loads persisted data only at the
+ * exact current schema version; it never reshapes a non-matching database in
+ * place. Bumping {@link CURRENT_PERSISTED_DATA_SCHEMA_VERSION} intentionally
+ * invalidates databases stamped with any other version so the failure surfaces
+ * deterministically at boot, before any workflow attempts replay.
  *
  * Inspect `foundVersion` to see what the storage advertised and `expectedVersion`
- * to see what this engine requires. Resolve by deleting the database (acceptable
- * pre-MVP) or by starting from fresh storage.
+ * to see what this engine requires. Resolve by deleting the database or by
+ * starting from fresh storage.
  *
  * @example
  * ```ts

package/dist/core/review/events.d.ts

@@ -6,12 +6,11 @@
  *
  * @example Route review notifications to a webhook
  * ```ts
- * import { ReviewRequestedEvent } from '@lostgradient/weft';
+ * import { ReviewRequestedEvent, type TypedEventTarget, type WeftReviewEventMap } from '@lostgradient/weft';
  *
- * const target = new EventTarget();
+ * declare const target: TypedEventTarget<WeftReviewEventMap>;
  *
- * target.addEventListener(ReviewRequestedEvent.type, (e) => {
- *   const event = e as ReviewRequestedEvent;
+ * target.addEventListener(ReviewRequestedEvent.type, (event) => {
  *   console.log(`Review ${event.reviewId} requested for workflow ${event.workflowId}`);
  *   console.log('Reviewers:', event.reviewers);
  * });
@@ -33,12 +32,11 @@ export declare class ReviewRequestedEvent extends Event {
  *
  * @example Record review decisions in an audit log
  * ```ts
- * import { ReviewCompletedEvent } from '@lostgradient/weft';
+ * import { ReviewCompletedEvent, type TypedEventTarget, type WeftReviewEventMap } from '@lostgradient/weft';
  *
- * const target = new EventTarget();
+ * declare const target: TypedEventTarget<WeftReviewEventMap>;
  *
- * target.addEventListener(ReviewCompletedEvent.type, (e) => {
- *   const event = e as ReviewCompletedEvent;
+ * target.addEventListener(ReviewCompletedEvent.type, (event) => {
  *   console.log(`Review ${event.reviewId}: '${event.decision}' by ${event.reviewer} in ${event.duration}ms`);
  * });
  * ```

package/dist/core/scheduler/scheduler-class.d.ts

@@ -1,10 +1,19 @@
-import type { Storage } from '../../storage/interface.ts';
+import type { BatchOperation, Storage } from '../../storage/interface.ts';
 import type { TimerEntry } from '../types.ts';
 export interface SchedulerOptions {
     storage: Storage;
     onTimerFired: (entry: TimerEntry) => void | Promise<void>;
     pollIntervalMs?: number;
     getNow?: () => number;
+    /**
+     * Commit the batch that deletes a fired timer's keys after its callback
+     * returns. Defaults to an unfenced `storage.batch`. The engine supplies a
+     * lease-fenced commit (#563) so the fired-timer delete and the callback's own
+     * follow-up writes share the same ownership fence — under deposition both are
+     * rejected and the timer survives for the successor to re-drive. With no lease
+     * held this commits exactly as the unfenced default would.
+     */
+    commitTimerCleanup?: (operations: BatchOperation[]) => Promise<void>;
 }
 /**
  * Scheduler manages durable timers and polls for expired deadlines.

package/dist/core/scheduler/scheduler-class.js

@@ -4,16 +4,19 @@ import { buildTimerBatchOperations } from "./timer-batch.js";
 import {
   advanceTimerSource,
   readNextScannedTimerEntry,
+  readNextTeardownTimerEntry,
   readNextTerminalCleanupTimerEntry,
   selectNextTimerSource,
   shouldDeleteTimerIndexWithoutLookup
 } from "./timer-sources.js";
+const EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE = 1000;
 
 export class Scheduler {
   #storage;
   #onTimerFired;
   #pollIntervalMs;
   #getNow;
+  #commitTimerCleanup;
   #intervalHandle = null;
   #stopped = !1;
   constructor(options) {
@@ -21,6 +24,7 @@ export class Scheduler {
     this.#onTimerFired = options.onTimerFired;
     this.#pollIntervalMs = options.pollIntervalMs ?? 1000;
     this.#getNow = options.getNow ?? Date.now;
+    this.#commitTimerCleanup = options.commitTimerCleanup ?? ((operations) => this.#storage.batch(operations));
   }
   start() {
     if (this.#intervalHandle !== null)
@@ -66,7 +70,7 @@ export class Scheduler {
     this.stop();
   }
   async#processExpiredTimers(now, { respectStopped }) {
-    const currentTime = now ?? this.#getNow(), timerSources = this.#createTimerSources(this.#scanExpiredTimers(currentTime));
+    const currentTime = now ?? this.#getNow(), timerSources = this.#createTimerSources(this.#scanExpiredTimers(currentTime)), cleanupOperations = [];
     for (const timerSource of timerSources)
       await advanceTimerSource(timerSource, this.#storage);
     while (this.#hasPendingTimer(timerSources)) {
@@ -74,27 +78,36 @@ export class Scheduler {
       if (!nextEntry || !selectedSource)
         break;
       if (respectStopped && this.#stopped)
-        return;
-      if (await this.#processSelectedTimer(nextEntry) === "retry") {
+        break;
+      if (await this.#processSelectedTimer(nextEntry, cleanupOperations) === "retry") {
         await advanceTimerSource(selectedSource, this.#storage);
         continue;
       }
       await advanceTimerSource(selectedSource, this.#storage);
     }
+    await this.#deleteProcessedTimerKeys(cleanupOperations);
   }
   #scanExpiredTimers(currentTime) {
     return {
       deadline: this.#storage.scan("wf-deadline:", {
-        lt: resolvePrefixRangeEnd(KEYS.deadline(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.deadline(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       delayedStart: this.#storage.scan("wf-delayed:", {
-        lt: resolvePrefixRangeEnd(KEYS.delayedStart(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.delayedStart(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       schedule: this.#storage.scan("schedule-due:", {
-        lt: resolvePrefixRangeEnd(KEYS.scheduleTick(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.scheduleTick(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       }),
       terminalCleanup: this.#storage.scan("wf-cleanup:", {
-        lt: resolvePrefixRangeEnd(KEYS.terminalCleanup(currentTime, ""))
+        lt: resolvePrefixRangeEnd(KEYS.terminalCleanup(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
+      }),
+      teardown: this.#storage.scan("wf-teardown:", {
+        lt: resolvePrefixRangeEnd(KEYS.teardownTimer(currentTime, "")),
+        limit: EXPIRED_TIMER_SCAN_LIMIT_PER_SOURCE
       })
     };
   }
@@ -119,29 +132,43 @@ export class Scheduler {
         iterator: iterators.terminalCleanup[Symbol.asyncIterator](),
         next: null,
         readNext: readNextTerminalCleanupTimerEntry
+      },
+      {
+        iterator: iterators.teardown[Symbol.asyncIterator](),
+        next: null,
+        readNext: readNextTeardownTimerEntry
       }
     ];
   }
   #hasPendingTimer(timerSources) {
     return timerSources.some((timerSource) => timerSource.next !== null);
   }
-  async#processSelectedTimer(nextEntry) {
+  async#processSelectedTimer(nextEntry, cleanupOperations) {
     try {
       await this.#onTimerFired(nextEntry.entry);
     } catch (error) {
       console.error(`Timer callback failed for timer ${nextEntry.entry.id}:`, error);
       return "retry";
     }
-    await this.#deleteTimerKeysAfterCallback(nextEntry);
+    await this.#appendTimerCleanupOperationsAfterCallback(nextEntry, cleanupOperations);
     return "processed";
   }
-  async#deleteTimerKeysAfterCallback(nextEntry) {
+  async#appendTimerCleanupOperationsAfterCallback(nextEntry, cleanupOperations) {
     try {
-      await this.#storage.batch(await this.#buildTimerCleanupOperations(nextEntry));
+      cleanupOperations.push(...await this.#buildTimerCleanupOperations(nextEntry));
     } catch (deleteError) {
       console.error(`Failed to delete timer keys for ${nextEntry.entry.id}:`, deleteError);
     }
   }
+  async#deleteProcessedTimerKeys(cleanupOperations) {
+    if (cleanupOperations.length === 0)
+      return;
+    try {
+      await this.#commitTimerCleanup(cleanupOperations);
+    } catch (deleteError) {
+      console.error("Failed to delete timer keys for processed scheduler tick:", deleteError);
+    }
+  }
   async#buildTimerCleanupOperations(nextEntry) {
     const cleanupOperations = [{ type: "delete", key: nextEntry.key }], indexDeleteOperation = await this.#buildTimerIndexDeleteOperation(nextEntry);
     if (indexDeleteOperation)

package/dist/core/scheduler/timer-batch.js

@@ -2,7 +2,7 @@ import { KEYS } from "../../storage/interface.js";
 import { encode } from "../codec.js";
 import { normalizeStorageTimestamp } from "./duration.js";
 function isTimerEntryKind(value) {
-  return value === "sleep" || value === "visibility-timeout" || value === "execution-deadline" || value === "delayed-start" || value === "schedule" || value === "terminal-cleanup";
+  return value === "sleep" || value === "visibility-timeout" || value === "execution-deadline" || value === "delayed-start" || value === "schedule" || value === "terminal-cleanup" || value === "teardown" || value === "wait-condition";
 }
 function isRecord(value) {
   return typeof value === "object" && value !== null;
@@ -30,6 +30,14 @@ export function buildTimerBatchOperations(entry) {
         value: encode(normalizedEntry.workflowId)
       }
     ];
+  if (normalizedEntry.kind === "teardown")
+    return [
+      {
+        type: "put",
+        key: KEYS.teardownTimer(normalizedEntry.fireAt, normalizedEntry.id),
+        value: encode(normalizedEntry.workflowId)
+      }
+    ];
   const deadlineKey = normalizedEntry.kind === "delayed-start" ? KEYS.delayedStart(normalizedEntry.fireAt, normalizedEntry.workflowId) : normalizedEntry.kind === "schedule" ? KEYS.scheduleTick(normalizedEntry.fireAt, normalizedEntry.workflowId) : KEYS.deadline(normalizedEntry.fireAt, normalizedEntry.id), operations = [
     { type: "put", key: deadlineKey, value: encode(normalizedEntry) }
   ];

package/dist/core/scheduler/timer-sources.d.ts

@@ -12,6 +12,7 @@ export type TimerSource = {
 export declare function compareScannedTimerEntries(left: ScannedTimerEntry, right: ScannedTimerEntry): number;
 export declare function readNextScannedTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
 export declare function readNextTerminalCleanupTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
+export declare function readNextTeardownTimerEntry(iterator: AsyncIterator<[string, Uint8Array]>, storage: Storage): Promise<ScannedTimerEntry | null>;
 export declare function advanceTimerSource(timerSource: TimerSource, storage: Storage): Promise<void>;
 export declare function selectNextTimerSource(timerSources: TimerSource[]): TimerSource | undefined;
 export declare function shouldDeleteTimerIndexWithoutLookup(entry: TimerEntry): boolean;

package/dist/core/scheduler/timer-sources.js

@@ -20,15 +20,15 @@ export async function readNextScannedTimerEntry(iterator, storage) {
     return { key, entry: decoded };
   }
 }
-export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
-  const prefix = "wf-cleanup:";
+async function readNextWorkflowTimerEntry(iterator, storage, kind) {
+  const { diagnosticName, prefix } = kind === "terminal-cleanup" ? { diagnosticName: "terminal cleanup", prefix: "wf-cleanup:" } : { diagnosticName: "teardown timer", prefix: "wf-teardown:" };
   while (!0) {
     const next = await iterator.next();
     if (next.done)
       return null;
     const [key, value] = next.value, separatorIndex = key.indexOf(":", prefix.length), fireAtValue = separatorIndex === -1 ? Number.NaN : Number(key.slice(prefix.length, separatorIndex)), timerId = separatorIndex === -1 ? null : tryDecodeStorageKeyComponent(key.slice(separatorIndex + 1)), decodedWorkflowId = decode(value);
     if (!Number.isSafeInteger(fireAtValue) || fireAtValue < 0 || timerId === null || typeof decodedWorkflowId !== "string") {
-      console.error(`Corrupted terminal cleanup entry at ${key}: removing`);
+      console.error(`Corrupted ${diagnosticName} entry at ${key}: removing`);
       await storage.delete(key);
       continue;
     }
@@ -38,11 +38,17 @@ export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
         id: timerId,
         workflowId: decodedWorkflowId,
         fireAt: fireAtValue,
-        kind: "terminal-cleanup"
+        kind
       }
     };
   }
 }
+export async function readNextTerminalCleanupTimerEntry(iterator, storage) {
+  return readNextWorkflowTimerEntry(iterator, storage, "terminal-cleanup");
+}
+export async function readNextTeardownTimerEntry(iterator, storage) {
+  return readNextWorkflowTimerEntry(iterator, storage, "teardown");
+}
 export async function advanceTimerSource(timerSource, storage) {
   timerSource.next = await timerSource.readNext(timerSource.iterator, storage);
 }
@@ -57,5 +63,5 @@ export function selectNextTimerSource(timerSources) {
   return selectedSource;
 }
 export function shouldDeleteTimerIndexWithoutLookup(entry) {
-  return entry.kind !== "schedule" && entry.kind !== "terminal-cleanup";
+  return entry.kind !== "schedule" && entry.kind !== "terminal-cleanup" && entry.kind !== "teardown";
 }

package/dist/core/session-state.d.ts

@@ -1,6 +1,5 @@
 import { WeftError } from './weft-error.ts';
 export declare const SESSION_STATE_LOCAL_KEY = "stateSession";
-export declare const LEGACY_SESSION_STATE_LOCAL_KEY = "sessionState";
 export declare const MAX_SESSION_STATE_ENTRY_COUNT = 256;
 export declare const MAX_SESSION_STATE_KEY_LENGTH = 256;
 export declare const MAX_SESSION_STATE_SERIALIZED_BYTES: number;

package/dist/core/session-state.js

@@ -1,6 +1,6 @@
 import { encode } from "./codec.js";
 import { WeftError } from "./weft-error.js";
-export const SESSION_STATE_LOCAL_KEY = "stateSession", LEGACY_SESSION_STATE_LOCAL_KEY = "sessionState", MAX_SESSION_STATE_ENTRY_COUNT = 256, MAX_SESSION_STATE_KEY_LENGTH = 256, MAX_SESSION_STATE_SERIALIZED_BYTES = 32768;
+export const SESSION_STATE_LOCAL_KEY = "stateSession", MAX_SESSION_STATE_ENTRY_COUNT = 256, MAX_SESSION_STATE_KEY_LENGTH = 256, MAX_SESSION_STATE_SERIALIZED_BYTES = 32768;
 const RESERVED_SESSION_STATE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 export class SessionStateValidationError extends WeftError {
@@ -55,7 +55,7 @@ export function normalizeSessionStateRecord(value) {
 export function normalizeSessionStateLocals(locals) {
   if (!locals)
     return;
-  return normalizeSessionStateRecord(locals[SESSION_STATE_LOCAL_KEY] ?? locals[LEGACY_SESSION_STATE_LOCAL_KEY]);
+  return normalizeSessionStateRecord(locals[SESSION_STATE_LOCAL_KEY]);
 }
 export function validateSessionStateStore(store) {
   const keys = Object.keys(store);

package/dist/core/start-workflow-validation.d.ts

@@ -29,6 +29,40 @@ export declare const coerceStartWorkflowIdempotencyKey: (value: unknown, fieldNa
  * caller gets the same guarantees as an HTTP caller.
  */
 export declare const assertValidIdempotencyKey: (value: string, fieldName: string) => string;
+/**
+ * Validate the `onTerminalConflict` start policy against the rest of the start
+ * options. `'error'` (the default) and `'start-new'` are the only accepted
+ * values. `'start-new'` (Temporal's `ALLOW_DUPLICATE` for terminal runs) requires
+ * an explicit, caller-chosen `id` and is mutually exclusive with `idempotencyKey`:
+ * idempotency is a permanent at-most-once mapping that survives terminal state, so
+ * restarting under it would contradict that contract. A generated UUID is never a
+ * meaningful restart target, hence the explicit-`id` requirement.
+ */
+export declare function assertValidOnTerminalConflict(options: {
+    onTerminalConflict?: unknown;
+    id?: unknown;
+    idempotencyKey?: unknown;
+} | undefined): void;
+/**
+ * `options.id` and `options.idempotencyKey` are mutually exclusive: idempotency
+ * assigns its own generated workflow id and dedups through the key, so pinning a
+ * caller id alongside it conflates "id already taken" with "lost the idempotency
+ * race". Reject the combination so each concern stays separable. Shared by the
+ * plain idempotent-start path and `startOrSignal` convergence validation.
+ */
+export declare function assertIdAndIdempotencyKeyExclusive(options: {
+    id?: unknown;
+    idempotencyKey?: unknown;
+}): void;
+/**
+ * Reject `onTerminalConflict` on a start surface that does not support it
+ * (`engine.startOrSignal`). The option is type-absent from those surfaces, but a
+ * transport or untyped JS caller could still smuggle the field into the options
+ * object — this is the runtime backstop. `engine.startOrSignal`'s identity is the
+ * permanent at-most-once idempotency mapping, which `'start-new'` would violate,
+ * so the policy is `engine.start`-only (see follow-up issue #489).
+ */
+export declare function assertOnTerminalConflictUnsupported(options: object | undefined, surface: string): void;
 export declare function coerceStartWorkflowTimestamp(value: unknown, fieldName: string): number;
 export declare function parseStartWorkflowDuration(duration: Duration, fieldName: string): number;
 export declare function coerceStartWorkflowDuration(value: unknown, fieldName: string): Duration;

package/dist/core/start-workflow-validation.js

@@ -33,6 +33,25 @@ export const assertExclusiveStartWorkflowOptions = (startAt, startAfter) => {
     throw new StartWorkflowValidationError(`${fieldName} must be at most ${MAX_IDEMPOTENCY_KEY_BYTES} UTF-8 bytes`);
   return value;
 };
+export function assertValidOnTerminalConflict(options) {
+  const onTerminalConflict = options?.onTerminalConflict;
+  if (onTerminalConflict === void 0 || onTerminalConflict === "error")
+    return;
+  if (onTerminalConflict !== "start-new")
+    throw new StartWorkflowValidationError("options.onTerminalConflict must be 'error' or 'start-new'");
+  if (options?.idempotencyKey !== void 0)
+    throw new StartWorkflowValidationError("options.onTerminalConflict: 'start-new' is mutually exclusive with options.idempotencyKey: idempotency is a permanent at-most-once mapping and cannot restart a terminal run");
+  if (options?.id === void 0)
+    throw new StartWorkflowValidationError("options.onTerminalConflict: 'start-new' requires an explicit options.id; a generated id is never a meaningful restart target");
+}
+export function assertIdAndIdempotencyKeyExclusive(options) {
+  if (options.id !== void 0 && options.idempotencyKey !== void 0)
+    throw new StartWorkflowValidationError("options.id and options.idempotencyKey are mutually exclusive: idempotency assigns its own workflow id and dedups through the idempotency key. Provide one or the other.");
+}
+export function assertOnTerminalConflictUnsupported(options, surface) {
+  if (options !== void 0 && "onTerminalConflict" in options && options.onTerminalConflict !== void 0)
+    throw new StartWorkflowValidationError(`${surface} does not support options.onTerminalConflict; it is available on engine.start only`);
+}
 export function coerceStartWorkflowTimestamp(value, fieldName) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
     throw new StartWorkflowValidationError(`${fieldName} must be a non-negative integer millisecond timestamp`);

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

@@ -0,0 +1,67 @@
+/**
+ * Activity verification types: the two-phase verifier contract an activity can
+ * declare via {@link ActivityDefinition.verify}. Split out of `activity.ts` to
+ * keep that module under the per-file line ceiling; these types are re-exported
+ * through `../types.ts` so the public surface is unchanged.
+ */
+/**
+ * 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>;

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

@@ -1,3 +1,4 @@
+import type { ActivityVerifier } from './activity-verification.ts';
 import type { DefinitionSchema, InferSchemaOutput } from './definition-schema.ts';
 import type { Duration, RetryPolicy } from './retry-retention.ts';
 /**
@@ -47,6 +48,53 @@ export type ActivityFunction<TInput = unknown, TOutput = unknown> = (input: TInp
 export interface ActivityContext {
     signal: AbortSignal;
     heartbeat(details?: unknown): void;
+    /**
+     * The heartbeat payload recorded by the PREVIOUS attempt of this activity, or
+     * `undefined` if there is none. This is the resumable-batch pattern: a
+     * long-running activity that calls `ctx.heartbeat({ done: n })` to record its
+     * progress can read `ctx.lastHeartbeatDetails` on a retry and skip the work it
+     * already finished, instead of re-running from the start and producing
+     * duplicate side effects.
+     *
+     * It is `undefined` on the first attempt, after an engine restart (the value is
+     * held in engine memory, never checkpointed), and for worker-executed
+     * activities (which run their function out of process and never observe this).
+     * Because it is non-durable, treat it as a best-effort optimization: a correct
+     * activity must still produce the right result when `lastHeartbeatDetails` is
+     * `undefined`. For a durability guarantee, persist progress in workflow state
+     * (e.g. one `ctx.run` per batch with an `idempotencyKey`) instead.
+     *
+     * Only top-level `ctx.run` activities retry, so this is only ever populated
+     * there. An activity called inside `ctx.all` / `ctx.race` does not retry, so its
+     * `lastHeartbeatDetails` is always `undefined`.
+     *
+     * @example
+     * ```ts
+     * import { activity, type ActivityContext } from '@lostgradient/weft';
+     *
+     * function resumeFrom(details: unknown): number {
+     *   return typeof details === 'object' && details !== null && 'done' in details &&
+     *     typeof (details as { done: unknown }).done === 'number'
+     *     ? (details as { done: number }).done
+     *     : 0;
+     * }
+     *
+     * const postBatches = activity({
+     *   name: 'postBatches',
+     *   execute: async (batches: string[][], ctx?: ActivityContext) => {
+     *     let done = resumeFrom(ctx?.lastHeartbeatDetails);
+     *     for (; done < batches.length; done += 1) {
+     *       await postBatch(batches[done]!);
+     *       ctx?.heartbeat({ done: done + 1 });
+     *     }
+     *     return { posted: done };
+     *   },
+     * });
+     * declare function postBatch(batch: string[]): Promise<void>;
+     * void postBatches;
+     * ```
+     */
+    lastHeartbeatDetails?: unknown;
     /**
      * Defer this activity to out-of-band completion. Calling `completeAsync()`
      * hands the work off to an external system — a webhook, a human callback, a
@@ -120,68 +168,30 @@ export interface ActivityCallOptions {
     sticky?: boolean;
     /** Override the default visibility timeout for this invocation. */
     visibilityTimeout?: Duration;
+    /**
+     * Total wall-clock budget for this activity across ALL retry attempts and the
+     * backoff waits between them — close to Temporal's `scheduleToCloseTimeout`.
+     * Unlike `timeout` (a per-attempt cap, reset on every attempt), this budget is
+     * measured from the first dispatch and is not reset between attempts. When the
+     * budget bars the next attempt, the activity fails with an
+     * {@link ActivityScheduleToCloseTimeoutError} (a `timeout` failure category).
+     *
+     * Enforcement is at the **retry decision point**, not by waiting out the clock:
+     * the activity fails when the next retry's backoff would start it at or after the
+     * deadline (or when an attempt has already overrun the budget), rather than
+     * parking for a backoff that is already doomed. So a retry whose backoff would
+     * overshoot the budget is skipped immediately even though the actual elapsed time
+     * is still under the budget — the error reports the actual elapsed time and the
+     * projected next-dispatch that triggered the decision.
+     *
+     * It has **no effect unless a retry policy is configured** — a non-retried
+     * activity fails on its first error before the budget is ever consulted. Use
+     * `timeout` to bound a single attempt. It also applies to top-level `ctx.run`
+     * activities only; an activity inside `ctx.all` / `ctx.race` does not retry, so
+     * this budget never engages there.
+     */
+    scheduleToCloseTimeout?: 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
@@ -235,6 +245,15 @@ export interface ActivityDefinition<TInput = unknown, TOutput = unknown, TName e
     idempotent?: boolean;
     /** Visibility timeout for this activity. Defaults to 30 seconds. */
     visibilityTimeout?: Duration;
+    /**
+     * Total wall-clock budget across all retry attempts and their backoff waits,
+     * measured from the first dispatch. The per-call {@link ActivityCallOptions.scheduleToCloseTimeout}
+     * overrides this default. Enforced at the retry decision point (the activity
+     * fails when the next retry would start at or after the deadline, not by waiting
+     * out the clock), so it only engages for a retried, top-level `ctx.run` activity.
+     * See the per-call option for the full contract.
+     */
+    scheduleToCloseTimeout?: 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)`