@workflow/core 5.0.0-beta.5 → 5.0.0-beta.50

package/dist/runtime/replay-budget.d.ts

@@ -0,0 +1,97 @@
+import { type SlotSnapshotParams } from './helpers.js';
+/**
+ * Per-invocation accounting of the *non-step* portion of a workflow
+ * handler run: deterministic event-log replay, workflow-VM execution
+ * between step boundaries, suspension handling, queue round-trips, etc.
+ * Inline step bodies (`"use step"` functions invoked via `executeStep`)
+ * are intentionally excluded since they are bounded by the platform's
+ * function `maxDuration` and the `NO_INLINE_REPLAY_AFTER_MS` early-return
+ * guard.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const budget = new ReplayBudget();
+ * // …non-step work happens here, accumulates against the budget…
+ * budget.pause();
+ * try {
+ *   await executeStep(...); // not charged
+ * } finally {
+ *   budget.resume();
+ * }
+ * // back to charging
+ * if (budget.isExhausted()) { ... }
+ * ```
+ *
+ * Implementation notes:
+ *
+ * - `pause()` and `resume()` are idempotent: calling `pause()` while
+ *   already paused (or `resume()` while already resumed) is a no-op.
+ *   This protects against double-counting in future refactors that nest
+ *   step execution or take an early-return path between a `pause()` and
+ *   the matching `resume()`.
+ * - `isExhausted()` is checked at loop boundaries by the caller; the
+ *   budget itself does not arm any timers. This means an in-flight
+ *   pathological `runWorkflow` call (e.g. a huge event-log replay) can
+ *   overshoot the budget by up to one iteration's worth of work before
+ *   the next check fires. In practice the 20s headroom built into
+ *   `MAX_REPLAY_TIMEOUT_MS` (and the function `maxDuration` ceiling)
+ *   gives us slack; the old `setTimeout`-based approach also ultimately
+ *   relied on the platform SIGTERM as the hard backstop.
+ */
+export declare class ReplayBudget {
+    private readonly limitMs;
+    private elapsedMs;
+    private intervalStart;
+    constructor(limitMs?: number);
+    /**
+     * The configured replay-timeout limit, in ms. Useful for log messages.
+     */
+    get configuredLimitMs(): number;
+    /**
+     * Total non-step time accumulated so far, in ms. Includes the
+     * currently-active interval if the budget is not paused.
+     */
+    elapsed(): number;
+    /**
+     * Stop counting elapsed time toward the budget. Idempotent: safe to
+     * call multiple times in a row; subsequent calls are no-ops until
+     * `resume()` reopens an interval.
+     */
+    pause(): void;
+    /**
+     * Resume counting elapsed time toward the budget. Idempotent: safe to
+     * call multiple times in a row; subsequent calls re-anchor the
+     * interval start to `now()`, which is fine because no time accrues
+     * between back-to-back `resume()` calls.
+     */
+    resume(): void;
+    /**
+     * True if the budget has been exhausted (`elapsed() >= limitMs`).
+     * Callers should invoke `handleExhausted(...)` afterward and return
+     * from the handler.
+     */
+    isExhausted(): boolean;
+}
+export declare class ReplayTimeoutRetryError extends Error {
+    readonly name = "ReplayTimeoutRetryError";
+}
+/**
+ * Reject the current delivery while replay-timeout retries remain. Once
+ * exhausted, fail the run and let the queue acknowledge the delivery.
+ */
+export declare function handleReplayBudgetExhausted(args: {
+    runId: string;
+    workflowName: string;
+    requestId: string | undefined;
+    attempt: number;
+    limitMs: number;
+    /**
+     * How much of the log the replay that ran out of budget had loaded. Carried
+     * onto the terminal write for the same reason every other write from that
+     * replay carries it: the run is being failed on a view of the log, and the
+     * World should be told which view.
+     */
+    slotSnapshot?: SlotSnapshotParams;
+}): Promise<void>;
+//# sourceMappingURL=replay-budget.d.ts.map

package/dist/runtime/replay-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-budget.d.ts","sourceRoot":"","sources":["../../src/runtime/replay-budget.ts"],"names":[],"mappings":"AAMA,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAgB;gBAEzB,OAAO,GAAE,MAA6B;IAKlD;;OAEG;IACH,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED;;;OAGG;IACH,OAAO,IAAI,MAAM;IAMjB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAId;;;;OAIG;IACH,WAAW,IAAI,OAAO;CAGvB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA6B;CACpD;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,IAAI,EAAE;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDhB"}

package/dist/runtime/replay-budget.js

@@ -0,0 +1,139 @@
+import { FatalError, RUN_ERROR_CODES } from '@workflow/errors';
+import { SPEC_VERSION_CURRENT } from '@workflow/world';
+import { describeError } from '../describe-error.js';
+import { runtimeLogger } from '../logger.js';
+import { dehydrateRunError } from '../serialization.js';
+import { getReplayTimeoutMaxRetries, getReplayTimeoutMs } from './constants.js';
+import { memoizeEncryptionKey } from './helpers.js';
+import { getWorld } from './world.js';
+/**
+ * Per-invocation accounting of the *non-step* portion of a workflow
+ * handler run: deterministic event-log replay, workflow-VM execution
+ * between step boundaries, suspension handling, queue round-trips, etc.
+ * Inline step bodies (`"use step"` functions invoked via `executeStep`)
+ * are intentionally excluded since they are bounded by the platform's
+ * function `maxDuration` and the `NO_INLINE_REPLAY_AFTER_MS` early-return
+ * guard.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const budget = new ReplayBudget();
+ * // …non-step work happens here, accumulates against the budget…
+ * budget.pause();
+ * try {
+ *   await executeStep(...); // not charged
+ * } finally {
+ *   budget.resume();
+ * }
+ * // back to charging
+ * if (budget.isExhausted()) { ... }
+ * ```
+ *
+ * Implementation notes:
+ *
+ * - `pause()` and `resume()` are idempotent: calling `pause()` while
+ *   already paused (or `resume()` while already resumed) is a no-op.
+ *   This protects against double-counting in future refactors that nest
+ *   step execution or take an early-return path between a `pause()` and
+ *   the matching `resume()`.
+ * - `isExhausted()` is checked at loop boundaries by the caller; the
+ *   budget itself does not arm any timers. This means an in-flight
+ *   pathological `runWorkflow` call (e.g. a huge event-log replay) can
+ *   overshoot the budget by up to one iteration's worth of work before
+ *   the next check fires. In practice the 20s headroom built into
+ *   `MAX_REPLAY_TIMEOUT_MS` (and the function `maxDuration` ceiling)
+ *   gives us slack; the old `setTimeout`-based approach also ultimately
+ *   relied on the platform SIGTERM as the hard backstop.
+ */
+export class ReplayBudget {
+    limitMs;
+    elapsedMs = 0;
+    intervalStart;
+    constructor(limitMs = getReplayTimeoutMs()) {
+        this.limitMs = limitMs;
+        this.intervalStart = Date.now();
+    }
+    /**
+     * The configured replay-timeout limit, in ms. Useful for log messages.
+     */
+    get configuredLimitMs() {
+        return this.limitMs;
+    }
+    /**
+     * Total non-step time accumulated so far, in ms. Includes the
+     * currently-active interval if the budget is not paused.
+     */
+    elapsed() {
+        const open = this.intervalStart === null ? 0 : Date.now() - this.intervalStart;
+        return this.elapsedMs + open;
+    }
+    /**
+     * Stop counting elapsed time toward the budget. Idempotent: safe to
+     * call multiple times in a row; subsequent calls are no-ops until
+     * `resume()` reopens an interval.
+     */
+    pause() {
+        if (this.intervalStart === null)
+            return;
+        this.elapsedMs += Date.now() - this.intervalStart;
+        this.intervalStart = null;
+    }
+    /**
+     * Resume counting elapsed time toward the budget. Idempotent: safe to
+     * call multiple times in a row; subsequent calls re-anchor the
+     * interval start to `now()`, which is fine because no time accrues
+     * between back-to-back `resume()` calls.
+     */
+    resume() {
+        this.intervalStart = Date.now();
+    }
+    /**
+     * True if the budget has been exhausted (`elapsed() >= limitMs`).
+     * Callers should invoke `handleExhausted(...)` afterward and return
+     * from the handler.
+     */
+    isExhausted() {
+        return this.elapsed() >= this.limitMs;
+    }
+}
+export class ReplayTimeoutRetryError extends Error {
+    name = 'ReplayTimeoutRetryError';
+}
+/**
+ * Reject the current delivery while replay-timeout retries remain. Once
+ * exhausted, fail the run and let the queue acknowledge the delivery.
+ */
+export async function handleReplayBudgetExhausted(args) {
+    const { runId, workflowName, requestId, attempt, limitMs, slotSnapshot } = args;
+    const runLogger = runtimeLogger.forRun(runId, workflowName);
+    const maxRetries = getReplayTimeoutMaxRetries();
+    if (attempt <= maxRetries) {
+        runLogger.warn('Workflow replay exceeded timeout; retrying delivery', {
+            timeoutMs: limitMs,
+            attempt,
+            maxRetries,
+        });
+        throw new ReplayTimeoutRetryError(`Workflow replay exceeded maximum duration (${limitMs / 1000}s)`);
+    }
+    const world = await getWorld();
+    const replayTimeoutDescription = describeError(undefined, RUN_ERROR_CODES.REPLAY_TIMEOUT);
+    runLogger.error('Workflow replay exceeded timeout and max retries exceeded. Failing the run', {
+        timeoutMs: limitMs,
+        attempt,
+        maxRetries,
+        errorCode: replayTimeoutDescription.errorCode,
+        errorAttribution: replayTimeoutDescription.attribution,
+    });
+    const getEncryptionKey = memoizeEncryptionKey(world, runId);
+    const timeoutErr = new FatalError(`Workflow replay exceeded maximum duration (${limitMs / 1000}s) after ${attempt} attempts`);
+    await world.events.create(runId, {
+        eventType: 'run_failed',
+        specVersion: SPEC_VERSION_CURRENT,
+        eventData: {
+            error: await dehydrateRunError(timeoutErr, runId, await getEncryptionKey()),
+            errorCode: RUN_ERROR_CODES.REPLAY_TIMEOUT,
+        },
+    }, { requestId, ...slotSnapshot });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVwbGF5LWJ1ZGdldC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9ydW50aW1lL3JlcGxheS1idWRnZXQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFVBQVUsRUFBRSxlQUFlLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUMvRCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUN2RCxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDckQsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUM3QyxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUN4RCxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUNoRixPQUFPLEVBQUUsb0JBQW9CLEVBQTJCLE1BQU0sY0FBYyxDQUFDO0FBQzdFLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSxZQUFZLENBQUM7QUFFdEM7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7OztHQXVDRztBQUNILE1BQU0sT0FBTyxZQUFZO0lBQ04sT0FBTyxDQUFTO0lBQ3pCLFNBQVMsR0FBRyxDQUFDLENBQUM7SUFDZCxhQUFhLENBQWdCO0lBRXJDLFlBQVksVUFBa0Isa0JBQWtCLEVBQUU7UUFDaEQsSUFBSSxDQUFDLE9BQU8sR0FBRyxPQUFPLENBQUM7UUFDdkIsSUFBSSxDQUFDLGFBQWEsR0FBRyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUM7SUFDbEMsQ0FBQztJQUVEOztPQUVHO0lBQ0gsSUFBSSxpQkFBaUI7UUFDbkIsT0FBTyxJQUFJLENBQUMsT0FBTyxDQUFDO0lBQ3RCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxPQUFPO1FBQ0wsTUFBTSxJQUFJLEdBQ1IsSUFBSSxDQUFDLGFBQWEsS0FBSyxJQUFJLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxHQUFHLElBQUksQ0FBQyxhQUFhLENBQUM7UUFDcEUsT0FBTyxJQUFJLENBQUMsU0FBUyxHQUFHLElBQUksQ0FBQztJQUMvQixDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILEtBQUs7UUFDSCxJQUFJLElBQUksQ0FBQyxhQUFhLEtBQUssSUFBSTtZQUFFLE9BQU87UUFDeEMsSUFBSSxDQUFDLFNBQVMsSUFBSSxJQUFJLENBQUMsR0FBRyxFQUFFLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQztRQUNsRCxJQUFJLENBQUMsYUFBYSxHQUFHLElBQUksQ0FBQztJQUM1QixDQUFDO0lBRUQ7Ozs7O09BS0c7SUFDSCxNQUFNO1FBQ0osSUFBSSxDQUFDLGFBQWEsR0FBRyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUM7SUFDbEMsQ0FBQztJQUVEOzs7O09BSUc7SUFDSCxXQUFXO1FBQ1QsT0FBTyxJQUFJLENBQUMsT0FBTyxFQUFFLElBQUksSUFBSSxDQUFDLE9BQU8sQ0FBQztJQUN4QyxDQUFDO0NBQ0Y7QUFFRCxNQUFNLE9BQU8sdUJBQXdCLFNBQVEsS0FBSztJQUM5QixJQUFJLEdBQUcseUJBQXlCLENBQUM7Q0FDcEQ7QUFFRDs7O0dBR0c7QUFDSCxNQUFNLENBQUMsS0FBSyxVQUFVLDJCQUEyQixDQUFDLElBYWpEO0lBQ0MsTUFBTSxFQUFFLEtBQUssRUFBRSxZQUFZLEVBQUUsU0FBUyxFQUFFLE9BQU8sRUFBRSxPQUFPLEVBQUUsWUFBWSxFQUFFLEdBQ3RFLElBQUksQ0FBQztJQUNQLE1BQU0sU0FBUyxHQUFHLGFBQWEsQ0FBQyxNQUFNLENBQUMsS0FBSyxFQUFFLFlBQVksQ0FBQyxDQUFDO0lBRTVELE1BQU0sVUFBVSxHQUFHLDBCQUEwQixFQUFFLENBQUM7SUFDaEQsSUFBSSxPQUFPLElBQUksVUFBVSxFQUFFLENBQUM7UUFDMUIsU0FBUyxDQUFDLElBQUksQ0FBQyxxREFBcUQsRUFBRTtZQUNwRSxTQUFTLEVBQUUsT0FBTztZQUNsQixPQUFPO1lBQ1AsVUFBVTtTQUNYLENBQUMsQ0FBQztRQUNILE1BQU0sSUFBSSx1QkFBdUIsQ0FDL0IsOENBQThDLE9BQU8sR0FBRyxJQUFJLElBQUksQ0FDakUsQ0FBQztJQUNKLENBQUM7SUFFRCxNQUFNLEtBQUssR0FBRyxNQUFNLFFBQVEsRUFBRSxDQUFDO0lBRS9CLE1BQU0sd0JBQXdCLEdBQUcsYUFBYSxDQUM1QyxTQUFTLEVBQ1QsZUFBZSxDQUFDLGNBQWMsQ0FDL0IsQ0FBQztJQUNGLFNBQVMsQ0FBQyxLQUFLLENBQ2IsNEVBQTRFLEVBQzVFO1FBQ0UsU0FBUyxFQUFFLE9BQU87UUFDbEIsT0FBTztRQUNQLFVBQVU7UUFDVixTQUFTLEVBQUUsd0JBQXdCLENBQUMsU0FBUztRQUM3QyxnQkFBZ0IsRUFBRSx3QkFBd0IsQ0FBQyxXQUFXO0tBQ3ZELENBQ0YsQ0FBQztJQUVGLE1BQU0sZ0JBQWdCLEdBQUcsb0JBQW9CLENBQUMsS0FBSyxFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQzVELE1BQU0sVUFBVSxHQUFHLElBQUksVUFBVSxDQUMvQiw4Q0FBOEMsT0FBTyxHQUFHLElBQUksWUFBWSxPQUFPLFdBQVcsQ0FDM0YsQ0FBQztJQUNGLE1BQU0sS0FBSyxDQUFDLE1BQU0sQ0FBQyxNQUFNLENBQ3ZCLEtBQUssRUFDTDtRQUNFLFNBQVMsRUFBRSxZQUFZO1FBQ3ZCLFdBQVcsRUFBRSxvQkFBb0I7UUFDakMsU0FBUyxFQUFFO1lBQ1QsS0FBSyxFQUFFLE1BQU0saUJBQWlCLENBQzVCLFVBQVUsRUFDVixLQUFLLEVBQ0wsTUFBTSxnQkFBZ0IsRUFBRSxDQUN6QjtZQUNELFNBQVMsRUFBRSxlQUFlLENBQUMsY0FBYztTQUMxQztLQUNGLEVBQ0QsRUFBRSxTQUFTLEVBQUUsR0FBRyxZQUFZLEVBQUUsQ0FDL0IsQ0FBQztBQUNKLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBGYXRhbEVycm9yLCBSVU5fRVJST1JfQ09ERVMgfSBmcm9tICdAd29ya2Zsb3cvZXJyb3JzJztcbmltcG9ydCB7IFNQRUNfVkVSU0lPTl9DVVJSRU5UIH0gZnJvbSAnQHdvcmtmbG93L3dvcmxkJztcbmltcG9ydCB7IGRlc2NyaWJlRXJyb3IgfSBmcm9tICcuLi9kZXNjcmliZS1lcnJvci5qcyc7XG5pbXBvcnQgeyBydW50aW1lTG9nZ2VyIH0gZnJvbSAnLi4vbG9nZ2VyLmpzJztcbmltcG9ydCB7IGRlaHlkcmF0ZVJ1bkVycm9yIH0gZnJvbSAnLi4vc2VyaWFsaXphdGlvbi5qcyc7XG5pbXBvcnQgeyBnZXRSZXBsYXlUaW1lb3V0TWF4UmV0cmllcywgZ2V0UmVwbGF5VGltZW91dE1zIH0gZnJvbSAnLi9jb25zdGFudHMuanMnO1xuaW1wb3J0IHsgbWVtb2l6ZUVuY3J5cHRpb25LZXksIHR5cGUgU2xvdFNuYXBzaG90UGFyYW1zIH0gZnJvbSAnLi9oZWxwZXJzLmpzJztcbmltcG9ydCB7IGdldFdvcmxkIH0gZnJvbSAnLi93b3JsZC5qcyc7XG5cbi8qKlxuICogUGVyLWludm9jYXRpb24gYWNjb3VudGluZyBvZiB0aGUgKm5vbi1zdGVwKiBwb3J0aW9uIG9mIGEgd29ya2Zsb3dcbiAqIGhhbmRsZXIgcnVuOiBkZXRlcm1pbmlzdGljIGV2ZW50LWxvZyByZXBsYXksIHdvcmtmbG93LVZNIGV4ZWN1dGlvblxuICogYmV0d2VlbiBzdGVwIGJvdW5kYXJpZXMsIHN1c3BlbnNpb24gaGFuZGxpbmcsIHF1ZXVlIHJvdW5kLXRyaXBzLCBldGMuXG4gKiBJbmxpbmUgc3RlcCBib2RpZXMgKGBcInVzZSBzdGVwXCJgIGZ1bmN0aW9ucyBpbnZva2VkIHZpYSBgZXhlY3V0ZVN0ZXBgKVxuICogYXJlIGludGVudGlvbmFsbHkgZXhjbHVkZWQgc2luY2UgdGhleSBhcmUgYm91bmRlZCBieSB0aGUgcGxhdGZvcm0nc1xuICogZnVuY3Rpb24gYG1heER1cmF0aW9uYCBhbmQgdGhlIGBOT19JTkxJTkVfUkVQTEFZX0FGVEVSX01TYCBlYXJseS1yZXR1cm5cbiAqIGd1YXJkLlxuICpcbiAqIFVzYWdlOlxuICpcbiAqIGBgYHRzXG4gKiBjb25zdCBidWRnZXQgPSBuZXcgUmVwbGF5QnVkZ2V0KCk7XG4gKiAvLyDigKZub24tc3RlcCB3b3JrIGhhcHBlbnMgaGVyZSwgYWNjdW11bGF0ZXMgYWdhaW5zdCB0aGUgYnVkZ2V04oCmXG4gKiBidWRnZXQucGF1c2UoKTtcbiAqIHRyeSB7XG4gKiAgIGF3YWl0IGV4ZWN1dGVTdGVwKC4uLik7IC8vIG5vdCBjaGFyZ2VkXG4gKiB9IGZpbmFsbHkge1xuICogICBidWRnZXQucmVzdW1lKCk7XG4gKiB9XG4gKiAvLyBiYWNrIHRvIGNoYXJnaW5nXG4gKiBpZiAoYnVkZ2V0LmlzRXhoYXVzdGVkKCkpIHsgLi4uIH1cbiAqIGBgYFxuICpcbiAqIEltcGxlbWVudGF0aW9uIG5vdGVzOlxuICpcbiAqIC0gYHBhdXNlKClgIGFuZCBgcmVzdW1lKClgIGFyZSBpZGVtcG90ZW50OiBjYWxsaW5nIGBwYXVzZSgpYCB3aGlsZVxuICogICBhbHJlYWR5IHBhdXNlZCAob3IgYHJlc3VtZSgpYCB3aGlsZSBhbHJlYWR5IHJlc3VtZWQpIGlzIGEgbm8tb3AuXG4gKiAgIFRoaXMgcHJvdGVjdHMgYWdhaW5zdCBkb3VibGUtY291bnRpbmcgaW4gZnV0dXJlIHJlZmFjdG9ycyB0aGF0IG5lc3RcbiAqICAgc3RlcCBleGVjdXRpb24gb3IgdGFrZSBhbiBlYXJseS1yZXR1cm4gcGF0aCBiZXR3ZWVuIGEgYHBhdXNlKClgIGFuZFxuICogICB0aGUgbWF0Y2hpbmcgYHJlc3VtZSgpYC5cbiAqIC0gYGlzRXhoYXVzdGVkKClgIGlzIGNoZWNrZWQgYXQgbG9vcCBib3VuZGFyaWVzIGJ5IHRoZSBjYWxsZXI7IHRoZVxuICogICBidWRnZXQgaXRzZWxmIGRvZXMgbm90IGFybSBhbnkgdGltZXJzLiBUaGlzIG1lYW5zIGFuIGluLWZsaWdodFxuICogICBwYXRob2xvZ2ljYWwgYHJ1bldvcmtmbG93YCBjYWxsIChlLmcuIGEgaHVnZSBldmVudC1sb2cgcmVwbGF5KSBjYW5cbiAqICAgb3ZlcnNob290IHRoZSBidWRnZXQgYnkgdXAgdG8gb25lIGl0ZXJhdGlvbidzIHdvcnRoIG9mIHdvcmsgYmVmb3JlXG4gKiAgIHRoZSBuZXh0IGNoZWNrIGZpcmVzLiBJbiBwcmFjdGljZSB0aGUgMjBzIGhlYWRyb29tIGJ1aWx0IGludG9cbiAqICAgYE1BWF9SRVBMQVlfVElNRU9VVF9NU2AgKGFuZCB0aGUgZnVuY3Rpb24gYG1heER1cmF0aW9uYCBjZWlsaW5nKVxuICogICBnaXZlcyB1cyBzbGFjazsgdGhlIG9sZCBgc2V0VGltZW91dGAtYmFzZWQgYXBwcm9hY2ggYWxzbyB1bHRpbWF0ZWx5XG4gKiAgIHJlbGllZCBvbiB0aGUgcGxhdGZvcm0gU0lHVEVSTSBhcyB0aGUgaGFyZCBiYWNrc3RvcC5cbiAqL1xuZXhwb3J0IGNsYXNzIFJlcGxheUJ1ZGdldCB7XG4gIHByaXZhdGUgcmVhZG9ubHkgbGltaXRNczogbnVtYmVyO1xuICBwcml2YXRlIGVsYXBzZWRNcyA9IDA7XG4gIHByaXZhdGUgaW50ZXJ2YWxTdGFydDogbnVtYmVyIHwgbnVsbDtcblxuICBjb25zdHJ1Y3RvcihsaW1pdE1zOiBudW1iZXIgPSBnZXRSZXBsYXlUaW1lb3V0TXMoKSkge1xuICAgIHRoaXMubGltaXRNcyA9IGxpbWl0TXM7XG4gICAgdGhpcy5pbnRlcnZhbFN0YXJ0ID0gRGF0ZS5ub3coKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBUaGUgY29uZmlndXJlZCByZXBsYXktdGltZW91dCBsaW1pdCwgaW4gbXMuIFVzZWZ1bCBmb3IgbG9nIG1lc3NhZ2VzLlxuICAgKi9cbiAgZ2V0IGNvbmZpZ3VyZWRMaW1pdE1zKCk6IG51bWJlciB7XG4gICAgcmV0dXJuIHRoaXMubGltaXRNcztcbiAgfVxuXG4gIC8qKlxuICAgKiBUb3RhbCBub24tc3RlcCB0aW1lIGFjY3VtdWxhdGVkIHNvIGZhciwgaW4gbXMuIEluY2x1ZGVzIHRoZVxuICAgKiBjdXJyZW50bHktYWN0aXZlIGludGVydmFsIGlmIHRoZSBidWRnZXQgaXMgbm90IHBhdXNlZC5cbiAgICovXG4gIGVsYXBzZWQoKTogbnVtYmVyIHtcbiAgICBjb25zdCBvcGVuID1cbiAgICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9PT0gbnVsbCA/IDAgOiBEYXRlLm5vdygpIC0gdGhpcy5pbnRlcnZhbFN0YXJ0O1xuICAgIHJldHVybiB0aGlzLmVsYXBzZWRNcyArIG9wZW47XG4gIH1cblxuICAvKipcbiAgICogU3RvcCBjb3VudGluZyBlbGFwc2VkIHRpbWUgdG93YXJkIHRoZSBidWRnZXQuIElkZW1wb3RlbnQ6IHNhZmUgdG9cbiAgICogY2FsbCBtdWx0aXBsZSB0aW1lcyBpbiBhIHJvdzsgc3Vic2VxdWVudCBjYWxscyBhcmUgbm8tb3BzIHVudGlsXG4gICAqIGByZXN1bWUoKWAgcmVvcGVucyBhbiBpbnRlcnZhbC5cbiAgICovXG4gIHBhdXNlKCk6IHZvaWQge1xuICAgIGlmICh0aGlzLmludGVydmFsU3RhcnQgPT09IG51bGwpIHJldHVybjtcbiAgICB0aGlzLmVsYXBzZWRNcyArPSBEYXRlLm5vdygpIC0gdGhpcy5pbnRlcnZhbFN0YXJ0O1xuICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9IG51bGw7XG4gIH1cblxuICAvKipcbiAgICogUmVzdW1lIGNvdW50aW5nIGVsYXBzZWQgdGltZSB0b3dhcmQgdGhlIGJ1ZGdldC4gSWRlbXBvdGVudDogc2FmZSB0b1xuICAgKiBjYWxsIG11bHRpcGxlIHRpbWVzIGluIGEgcm93OyBzdWJzZXF1ZW50IGNhbGxzIHJlLWFuY2hvciB0aGVcbiAgICogaW50ZXJ2YWwgc3RhcnQgdG8gYG5vdygpYCwgd2hpY2ggaXMgZmluZSBiZWNhdXNlIG5vIHRpbWUgYWNjcnVlc1xuICAgKiBiZXR3ZWVuIGJhY2stdG8tYmFjayBgcmVzdW1lKClgIGNhbGxzLlxuICAgKi9cbiAgcmVzdW1lKCk6IHZvaWQge1xuICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9IERhdGUubm93KCk7XG4gIH1cblxuICAvKipcbiAgICogVHJ1ZSBpZiB0aGUgYnVkZ2V0IGhhcyBiZWVuIGV4aGF1c3RlZCAoYGVsYXBzZWQoKSA+PSBsaW1pdE1zYCkuXG4gICAqIENhbGxlcnMgc2hvdWxkIGludm9rZSBgaGFuZGxlRXhoYXVzdGVkKC4uLilgIGFmdGVyd2FyZCBhbmQgcmV0dXJuXG4gICAqIGZyb20gdGhlIGhhbmRsZXIuXG4gICAqL1xuICBpc0V4aGF1c3RlZCgpOiBib29sZWFuIHtcbiAgICByZXR1cm4gdGhpcy5lbGFwc2VkKCkgPj0gdGhpcy5saW1pdE1zO1xuICB9XG59XG5cbmV4cG9ydCBjbGFzcyBSZXBsYXlUaW1lb3V0UmV0cnlFcnJvciBleHRlbmRzIEVycm9yIHtcbiAgb3ZlcnJpZGUgcmVhZG9ubHkgbmFtZSA9ICdSZXBsYXlUaW1lb3V0UmV0cnlFcnJvcic7XG59XG5cbi8qKlxuICogUmVqZWN0IHRoZSBjdXJyZW50IGRlbGl2ZXJ5IHdoaWxlIHJlcGxheS10aW1lb3V0IHJldHJpZXMgcmVtYWluLiBPbmNlXG4gKiBleGhhdXN0ZWQsIGZhaWwgdGhlIHJ1biBhbmQgbGV0IHRoZSBxdWV1ZSBhY2tub3dsZWRnZSB0aGUgZGVsaXZlcnkuXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBoYW5kbGVSZXBsYXlCdWRnZXRFeGhhdXN0ZWQoYXJnczoge1xuICBydW5JZDogc3RyaW5nO1xuICB3b3JrZmxvd05hbWU6IHN0cmluZztcbiAgcmVxdWVzdElkOiBzdHJpbmcgfCB1bmRlZmluZWQ7XG4gIGF0dGVtcHQ6IG51bWJlcjtcbiAgbGltaXRNczogbnVtYmVyO1xuICAvKipcbiAgICogSG93IG11Y2ggb2YgdGhlIGxvZyB0aGUgcmVwbGF5IHRoYXQgcmFuIG91dCBvZiBidWRnZXQgaGFkIGxvYWRlZC4gQ2FycmllZFxuICAgKiBvbnRvIHRoZSB0ZXJtaW5hbCB3cml0ZSBmb3IgdGhlIHNhbWUgcmVhc29uIGV2ZXJ5IG90aGVyIHdyaXRlIGZyb20gdGhhdFxuICAgKiByZXBsYXkgY2FycmllcyBpdDogdGhlIHJ1biBpcyBiZWluZyBmYWlsZWQgb24gYSB2aWV3IG9mIHRoZSBsb2csIGFuZCB0aGVcbiAgICogV29ybGQgc2hvdWxkIGJlIHRvbGQgd2hpY2ggdmlldy5cbiAgICovXG4gIHNsb3RTbmFwc2hvdD86IFNsb3RTbmFwc2hvdFBhcmFtcztcbn0pOiBQcm9taXNlPHZvaWQ+IHtcbiAgY29uc3QgeyBydW5JZCwgd29ya2Zsb3dOYW1lLCByZXF1ZXN0SWQsIGF0dGVtcHQsIGxpbWl0TXMsIHNsb3RTbmFwc2hvdCB9ID1cbiAgICBhcmdzO1xuICBjb25zdCBydW5Mb2dnZXIgPSBydW50aW1lTG9nZ2VyLmZvclJ1bihydW5JZCwgd29ya2Zsb3dOYW1lKTtcblxuICBjb25zdCBtYXhSZXRyaWVzID0gZ2V0UmVwbGF5VGltZW91dE1heFJldHJpZXMoKTtcbiAgaWYgKGF0dGVtcHQgPD0gbWF4UmV0cmllcykge1xuICAgIHJ1bkxvZ2dlci53YXJuKCdXb3JrZmxvdyByZXBsYXkgZXhjZWVkZWQgdGltZW91dDsgcmV0cnlpbmcgZGVsaXZlcnknLCB7XG4gICAgICB0aW1lb3V0TXM6IGxpbWl0TXMsXG4gICAgICBhdHRlbXB0LFxuICAgICAgbWF4UmV0cmllcyxcbiAgICB9KTtcbiAgICB0aHJvdyBuZXcgUmVwbGF5VGltZW91dFJldHJ5RXJyb3IoXG4gICAgICBgV29ya2Zsb3cgcmVwbGF5IGV4Y2VlZGVkIG1heGltdW0gZHVyYXRpb24gKCR7bGltaXRNcyAvIDEwMDB9cylgXG4gICAgKTtcbiAgfVxuXG4gIGNvbnN0IHdvcmxkID0gYXdhaXQgZ2V0V29ybGQoKTtcblxuICBjb25zdCByZXBsYXlUaW1lb3V0RGVzY3JpcHRpb24gPSBkZXNjcmliZUVycm9yKFxuICAgIHVuZGVmaW5lZCxcbiAgICBSVU5fRVJST1JfQ09ERVMuUkVQTEFZX1RJTUVPVVRcbiAgKTtcbiAgcnVuTG9nZ2VyLmVycm9yKFxuICAgICdXb3JrZmxvdyByZXBsYXkgZXhjZWVkZWQgdGltZW91dCBhbmQgbWF4IHJldHJpZXMgZXhjZWVkZWQuIEZhaWxpbmcgdGhlIHJ1bicsXG4gICAge1xuICAgICAgdGltZW91dE1zOiBsaW1pdE1zLFxuICAgICAgYXR0ZW1wdCxcbiAgICAgIG1heFJldHJpZXMsXG4gICAgICBlcnJvckNvZGU6IHJlcGxheVRpbWVvdXREZXNjcmlwdGlvbi5lcnJvckNvZGUsXG4gICAgICBlcnJvckF0dHJpYnV0aW9uOiByZXBsYXlUaW1lb3V0RGVzY3JpcHRpb24uYXR0cmlidXRpb24sXG4gICAgfVxuICApO1xuXG4gIGNvbnN0IGdldEVuY3J5cHRpb25LZXkgPSBtZW1vaXplRW5jcnlwdGlvbktleSh3b3JsZCwgcnVuSWQpO1xuICBjb25zdCB0aW1lb3V0RXJyID0gbmV3IEZhdGFsRXJyb3IoXG4gICAgYFdvcmtmbG93IHJlcGxheSBleGNlZWRlZCBtYXhpbXVtIGR1cmF0aW9uICgke2xpbWl0TXMgLyAxMDAwfXMpIGFmdGVyICR7YXR0ZW1wdH0gYXR0ZW1wdHNgXG4gICk7XG4gIGF3YWl0IHdvcmxkLmV2ZW50cy5jcmVhdGUoXG4gICAgcnVuSWQsXG4gICAge1xuICAgICAgZXZlbnRUeXBlOiAncnVuX2ZhaWxlZCcsXG4gICAgICBzcGVjVmVyc2lvbjogU1BFQ19WRVJTSU9OX0NVUlJFTlQsXG4gICAgICBldmVudERhdGE6IHtcbiAgICAgICAgZXJyb3I6IGF3YWl0IGRlaHlkcmF0ZVJ1bkVycm9yKFxuICAgICAgICAgIHRpbWVvdXRFcnIsXG4gICAgICAgICAgcnVuSWQsXG4gICAgICAgICAgYXdhaXQgZ2V0RW5jcnlwdGlvbktleSgpXG4gICAgICAgICksXG4gICAgICAgIGVycm9yQ29kZTogUlVOX0VSUk9SX0NPREVTLlJFUExBWV9USU1FT1VULFxuICAgICAgfSxcbiAgICB9LFxuICAgIHsgcmVxdWVzdElkLCAuLi5zbG90U25hcHNob3QgfVxuICApO1xufVxuIl19

package/dist/runtime/replay-recovery-reporter.d.ts

@@ -0,0 +1,36 @@
+import type { CreateEventParams } from '@workflow/world';
+/**
+ * Invocation-scoped, one-shot reporter for a replay-divergence recovery.
+ *
+ * The reporter stays dormant until replay reaches a valid deterministic
+ * boundary. The first subsequent event write carries the telemetry for free.
+ * A recovered invocation with no natural event write intentionally reports
+ * nothing.
+ */
+export declare class ReplayRecoveryReporter {
+    private readonly divergenceCount;
+    private active;
+    private reported;
+    constructor(divergenceCount: number);
+    /**
+     * A reporter for an invocation that never diverged: `activate()` cannot arm
+     * it, so `withEventCreate` always passes writes through untouched. Lets every
+     * call site hold a non-optional reporter instead of branching on one.
+     *
+     * Structurally inert rather than a zero-count reporter on purpose: the
+     * server rejects a count below 1 as out-of-range and emits a
+     * `telemetry_rejected` metric, so a reporter that *can* report zero is a
+     * live footgun.
+     */
+    static inert(): ReplayRecoveryReporter;
+    activate(): void;
+    /**
+     * Decorate one natural event write with recovery telemetry.
+     *
+     * The claim is taken synchronously, so concurrent suspension writes cannot
+     * all carry the same count. A failed request releases it for a later natural
+     * write in the same invocation.
+     */
+    withEventCreate<T>(params: CreateEventParams | undefined, create: (params: CreateEventParams | undefined) => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=replay-recovery-reporter.d.ts.map

package/dist/runtime/replay-recovery-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-recovery-reporter.d.ts","sourceRoot":"","sources":["../../src/runtime/replay-recovery-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;GAOG;AACH,qBAAa,sBAAsB;IAIrB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAH5C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;gBAEI,eAAe,EAAE,MAAM;IAEpD;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,IAAI,sBAAsB;IAItC,QAAQ,IAAI,IAAI;IAIhB;;;;;;OAMG;IACG,eAAe,CAAC,CAAC,EACrB,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,MAAM,EAAE,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5D,OAAO,CAAC,CAAC,CAAC;CAcd"}

package/dist/runtime/replay-recovery-reporter.js

@@ -0,0 +1,64 @@
+/**
+ * Invocation-scoped, one-shot reporter for a replay-divergence recovery.
+ *
+ * The reporter stays dormant until replay reaches a valid deterministic
+ * boundary. The first subsequent event write carries the telemetry for free.
+ * A recovered invocation with no natural event write intentionally reports
+ * nothing.
+ */
+export class ReplayRecoveryReporter {
+    divergenceCount;
+    active = false;
+    reported = false;
+    constructor(divergenceCount) {
+        this.divergenceCount = divergenceCount;
+    }
+    /**
+     * A reporter for an invocation that never diverged: `activate()` cannot arm
+     * it, so `withEventCreate` always passes writes through untouched. Lets every
+     * call site hold a non-optional reporter instead of branching on one.
+     *
+     * Structurally inert rather than a zero-count reporter on purpose: the
+     * server rejects a count below 1 as out-of-range and emits a
+     * `telemetry_rejected` metric, so a reporter that *can* report zero is a
+     * live footgun.
+     */
+    static inert() {
+        return new InertReplayRecoveryReporter();
+    }
+    activate() {
+        this.active = true;
+    }
+    /**
+     * Decorate one natural event write with recovery telemetry.
+     *
+     * The claim is taken synchronously, so concurrent suspension writes cannot
+     * all carry the same count. A failed request releases it for a later natural
+     * write in the same invocation.
+     */
+    async withEventCreate(params, create) {
+        if (!this.active || this.reported)
+            return create(params);
+        this.reported = true;
+        try {
+            return await create({
+                ...params,
+                replayDivergenceCount: this.divergenceCount,
+            });
+        }
+        catch (error) {
+            this.reported = false;
+            throw error;
+        }
+    }
+}
+/** See {@link ReplayRecoveryReporter.inert}. */
+class InertReplayRecoveryReporter extends ReplayRecoveryReporter {
+    constructor() {
+        super(0);
+    }
+    activate() {
+        // Deliberately empty: nothing to report, so nothing can arm.
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVwbGF5LXJlY292ZXJ5LXJlcG9ydGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3J1bnRpbWUvcmVwbGF5LXJlY292ZXJ5LXJlcG9ydGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLE9BQU8sc0JBQXNCO0lBSUo7SUFIckIsTUFBTSxHQUFHLEtBQUssQ0FBQztJQUNmLFFBQVEsR0FBRyxLQUFLLENBQUM7SUFFekIsWUFBNkIsZUFBdUI7UUFBdkIsb0JBQWUsR0FBZixlQUFlLENBQVE7SUFBRyxDQUFDO0lBRXhEOzs7Ozs7Ozs7T0FTRztJQUNILE1BQU0sQ0FBQyxLQUFLO1FBQ1YsT0FBTyxJQUFJLDJCQUEyQixFQUFFLENBQUM7SUFDM0MsQ0FBQztJQUVELFFBQVE7UUFDTixJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQztJQUNyQixDQUFDO0lBRUQ7Ozs7OztPQU1HO0lBQ0gsS0FBSyxDQUFDLGVBQWUsQ0FDbkIsTUFBcUMsRUFDckMsTUFBNkQ7UUFFN0QsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLElBQUksSUFBSSxDQUFDLFFBQVE7WUFBRSxPQUFPLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUV6RCxJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksQ0FBQztRQUNyQixJQUFJLENBQUM7WUFDSCxPQUFPLE1BQU0sTUFBTSxDQUFDO2dCQUNsQixHQUFHLE1BQU07Z0JBQ1QscUJBQXFCLEVBQUUsSUFBSSxDQUFDLGVBQWU7YUFDNUMsQ0FBQyxDQUFDO1FBQ0wsQ0FBQztRQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7WUFDZixJQUFJLENBQUMsUUFBUSxHQUFHLEtBQUssQ0FBQztZQUN0QixNQUFNLEtBQUssQ0FBQztRQUNkLENBQUM7SUFDSCxDQUFDO0NBQ0Y7QUFFRCxnREFBZ0Q7QUFDaEQsTUFBTSwyQkFBNEIsU0FBUSxzQkFBc0I7SUFDOUQ7UUFDRSxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDWCxDQUFDO0lBRVEsUUFBUTtRQUNmLDZEQUE2RDtJQUMvRCxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgdHlwZSB7IENyZWF0ZUV2ZW50UGFyYW1zIH0gZnJvbSAnQHdvcmtmbG93L3dvcmxkJztcblxuLyoqXG4gKiBJbnZvY2F0aW9uLXNjb3BlZCwgb25lLXNob3QgcmVwb3J0ZXIgZm9yIGEgcmVwbGF5LWRpdmVyZ2VuY2UgcmVjb3ZlcnkuXG4gKlxuICogVGhlIHJlcG9ydGVyIHN0YXlzIGRvcm1hbnQgdW50aWwgcmVwbGF5IHJlYWNoZXMgYSB2YWxpZCBkZXRlcm1pbmlzdGljXG4gKiBib3VuZGFyeS4gVGhlIGZpcnN0IHN1YnNlcXVlbnQgZXZlbnQgd3JpdGUgY2FycmllcyB0aGUgdGVsZW1ldHJ5IGZvciBmcmVlLlxuICogQSByZWNvdmVyZWQgaW52b2NhdGlvbiB3aXRoIG5vIG5hdHVyYWwgZXZlbnQgd3JpdGUgaW50ZW50aW9uYWxseSByZXBvcnRzXG4gKiBub3RoaW5nLlxuICovXG5leHBvcnQgY2xhc3MgUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gIHByaXZhdGUgYWN0aXZlID0gZmFsc2U7XG4gIHByaXZhdGUgcmVwb3J0ZWQgPSBmYWxzZTtcblxuICBjb25zdHJ1Y3Rvcihwcml2YXRlIHJlYWRvbmx5IGRpdmVyZ2VuY2VDb3VudDogbnVtYmVyKSB7fVxuXG4gIC8qKlxuICAgKiBBIHJlcG9ydGVyIGZvciBhbiBpbnZvY2F0aW9uIHRoYXQgbmV2ZXIgZGl2ZXJnZWQ6IGBhY3RpdmF0ZSgpYCBjYW5ub3QgYXJtXG4gICAqIGl0LCBzbyBgd2l0aEV2ZW50Q3JlYXRlYCBhbHdheXMgcGFzc2VzIHdyaXRlcyB0aHJvdWdoIHVudG91Y2hlZC4gTGV0cyBldmVyeVxuICAgKiBjYWxsIHNpdGUgaG9sZCBhIG5vbi1vcHRpb25hbCByZXBvcnRlciBpbnN0ZWFkIG9mIGJyYW5jaGluZyBvbiBvbmUuXG4gICAqXG4gICAqIFN0cnVjdHVyYWxseSBpbmVydCByYXRoZXIgdGhhbiBhIHplcm8tY291bnQgcmVwb3J0ZXIgb24gcHVycG9zZTogdGhlXG4gICAqIHNlcnZlciByZWplY3RzIGEgY291bnQgYmVsb3cgMSBhcyBvdXQtb2YtcmFuZ2UgYW5kIGVtaXRzIGFcbiAgICogYHRlbGVtZXRyeV9yZWplY3RlZGAgbWV0cmljLCBzbyBhIHJlcG9ydGVyIHRoYXQgKmNhbiogcmVwb3J0IHplcm8gaXMgYVxuICAgKiBsaXZlIGZvb3RndW4uXG4gICAqL1xuICBzdGF0aWMgaW5lcnQoKTogUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gICAgcmV0dXJuIG5ldyBJbmVydFJlcGxheVJlY292ZXJ5UmVwb3J0ZXIoKTtcbiAgfVxuXG4gIGFjdGl2YXRlKCk6IHZvaWQge1xuICAgIHRoaXMuYWN0aXZlID0gdHJ1ZTtcbiAgfVxuXG4gIC8qKlxuICAgKiBEZWNvcmF0ZSBvbmUgbmF0dXJhbCBldmVudCB3cml0ZSB3aXRoIHJlY292ZXJ5IHRlbGVtZXRyeS5cbiAgICpcbiAgICogVGhlIGNsYWltIGlzIHRha2VuIHN5bmNocm9ub3VzbHksIHNvIGNvbmN1cnJlbnQgc3VzcGVuc2lvbiB3cml0ZXMgY2Fubm90XG4gICAqIGFsbCBjYXJyeSB0aGUgc2FtZSBjb3VudC4gQSBmYWlsZWQgcmVxdWVzdCByZWxlYXNlcyBpdCBmb3IgYSBsYXRlciBuYXR1cmFsXG4gICAqIHdyaXRlIGluIHRoZSBzYW1lIGludm9jYXRpb24uXG4gICAqL1xuICBhc3luYyB3aXRoRXZlbnRDcmVhdGU8VD4oXG4gICAgcGFyYW1zOiBDcmVhdGVFdmVudFBhcmFtcyB8IHVuZGVmaW5lZCxcbiAgICBjcmVhdGU6IChwYXJhbXM6IENyZWF0ZUV2ZW50UGFyYW1zIHwgdW5kZWZpbmVkKSA9PiBQcm9taXNlPFQ+XG4gICk6IFByb21pc2U8VD4ge1xuICAgIGlmICghdGhpcy5hY3RpdmUgfHwgdGhpcy5yZXBvcnRlZCkgcmV0dXJuIGNyZWF0ZShwYXJhbXMpO1xuXG4gICAgdGhpcy5yZXBvcnRlZCA9IHRydWU7XG4gICAgdHJ5IHtcbiAgICAgIHJldHVybiBhd2FpdCBjcmVhdGUoe1xuICAgICAgICAuLi5wYXJhbXMsXG4gICAgICAgIHJlcGxheURpdmVyZ2VuY2VDb3VudDogdGhpcy5kaXZlcmdlbmNlQ291bnQsXG4gICAgICB9KTtcbiAgICB9IGNhdGNoIChlcnJvcikge1xuICAgICAgdGhpcy5yZXBvcnRlZCA9IGZhbHNlO1xuICAgICAgdGhyb3cgZXJyb3I7XG4gICAgfVxuICB9XG59XG5cbi8qKiBTZWUge0BsaW5rIFJlcGxheVJlY292ZXJ5UmVwb3J0ZXIuaW5lcnR9LiAqL1xuY2xhc3MgSW5lcnRSZXBsYXlSZWNvdmVyeVJlcG9ydGVyIGV4dGVuZHMgUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gIGNvbnN0cnVjdG9yKCkge1xuICAgIHN1cGVyKDApO1xuICB9XG5cbiAgb3ZlcnJpZGUgYWN0aXZhdGUoKTogdm9pZCB7XG4gICAgLy8gRGVsaWJlcmF0ZWx5IGVtcHR5OiBub3RoaW5nIHRvIHJlcG9ydCwgc28gbm90aGluZyBjYW4gYXJtLlxuICB9XG59XG4iXX0=

package/dist/runtime/resume-hook.d.ts

@@ -1,23 +1,105 @@
-import { type Hook } from '@workflow/world';
-import { type CryptoKey } from '../encryption.js';
+import { type Hook as WorldHook } from '@workflow/world';
+import { type PayloadKey } from '../serialization.js';
 /**
- * Get the hook by token to find the associated workflow run,
- * and hydrate the `metadata` property if it was set from within
- * the workflow run.
+ * A hook record with its serialized `metadata` omitted: everything a resume
+ * actually reads. Resuming never looks at metadata, so the resume path accepts
+ * both a raw {@link WorldHook} straight out of a World and a {@link Hook}
+ * whose `metadata` is a Promise.
+ */
+type ResumableHook = Omit<WorldHook, 'metadata'>;
+/**
+ * A hook as returned by {@link getHookByToken} and {@link resumeHook}: the
+ * World's {@link WorldHook} record with its user-defined `metadata` hydrated
+ * lazily.
+ *
+ * `metadata` is a getter that returns a Promise — the same shape as
+ * `Run.returnValue` — so looking a hook up by token costs exactly one read.
+ * Hydrating metadata is a decrypting READ that needs the owning run's payload
+ * keys, and resolving those can cost a run fetch plus a `run-key` API round
+ * trip (~350ms). Deferring that to first access keeps the lookup fast for the
+ * many callers that only need `runId`/`token` — most importantly hook
+ * resumption, which never reads metadata at all.
+ *
+ * The promise is memoized: hydration (and the key resolution behind it) runs at
+ * most once per hook object. Awaiting it on a hook that stored no metadata
+ * resolves `undefined` and performs no I/O.
+ *
+ * Like `Run.returnValue`, the accessor is non-enumerable, so it is absent from
+ * `{ ...hook }` and `JSON.stringify(hook)` — read it explicitly and include the
+ * awaited value if you need to forward it.
+ *
+ * @example
+ *
+ * ```ts
+ * const hook = await getHookByToken(token);
+ * console.log(hook.runId); // no metadata work
+ * const metadata = (await hook.metadata) as { allowedUserId?: string } | undefined;
+ * ```
+ */
+export interface Hook extends ResumableHook {
+    /**
+     * The hook's user-defined metadata, hydrated on first access and memoized.
+     * Resolves `undefined` when the hook carries no metadata.
+     */
+    readonly metadata: Promise<unknown>;
+}
+/**
+ * Get the hook by token to find the associated workflow run.
+ *
+ * This is a single read. The returned hook's `metadata` is a getter that
+ * resolves a Promise (see {@link Hook}), so the run fetch and
+ * `run-key` round trip that hydrating it can require are only paid by callers
+ * that actually await it:
+ *
+ * ```ts
+ * const hook = await getHookByToken(token);
+ * const metadata = await hook.metadata;
+ * ```
+ *
+ * A Hook kept by minimum retention remains available here after its run ends,
+ * but cannot be resumed.
  *
  * @param token - The unique token identifying the hook
  */
 export declare function getHookByToken(token: string): Promise<Hook>;
+/**
+ * The result of {@link resumeHook}: a {@link Hook} augmented
+ * with an optional resilience signal.
+ *
+ * `resilientResume` is retained for source compatibility and is never set.
+ * `resumeHook()` now requires the durable `hook_received` write and workflow
+ * wake to both succeed before it resolves. Treat the result as a plain
+ * {@link Hook}.
+ */
+export type ResumedHook = Hook & {
+    resilientResume?: boolean;
+};
 /**
  * Resumes a workflow run by sending a payload to a hook identified by its token.
  *
  * This function is called externally (e.g., from an API route or server action)
  * to send data to a hook and resume the associated workflow run.
  *
+ * Resolving means BOTH that the `hook_received` event is durably recorded in
+ * the run's event log and that the workflow wake was accepted by the queue, in
+ * that order. A {@link HookNotFoundError} means this invocation committed no
+ * event. Any other error after the write is ambiguous only in dispatch, never
+ * in durability: the event may already be committed, and a later wake of the
+ * run (from any source) will deliver it.
+ *
+ * Prefer passing the token string over a cached {@link Hook} object. A token
+ * is looked up fresh, so the live backend can attest its atomic resume claim
+ * and the durable write becomes idempotent-on-retry (transport retries of the
+ * same write converge on one event). A supplied Hook object may carry a stale
+ * attestation, so it is deliberately ignored and the write is claim-less —
+ * meaning a lost response cannot be retried safely: retrying at the
+ * application level mints a fresh claim and can commit a second
+ * `hook_received`.
+ *
  * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
  * @param payload - The data payload to send to the hook
- * @returns Promise resolving to the hook
- * @throws Error if the hook is not found or if there's an error during the process
+ * @returns Promise resolving to the {@link ResumedHook}
+ * @throws {HookNotFoundError} If the Hook does not exist or its run has ended
  *
  * @example
  *
@@ -37,7 +119,7 @@ export declare function getHookByToken(token: string): Promise<Hook>;
  * }
  * ```
  */
-export declare function resumeHook<T = any>(tokenOrHook: string | Hook, payload: T, encryptionKeyOverride?: CryptoKey): Promise<Hook>;
+export declare function resumeHook<T = any>(tokenOrHook: string | ResumableHook, payload: T, encryptionKeyOverride?: PayloadKey): Promise<ResumedHook>;
 /**
  * Resumes a webhook by sending a {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
  * object to a hook identified by its token.
@@ -74,4 +156,5 @@ export declare function resumeHook<T = any>(tokenOrHook: string | Hook, payload:
  * ```
  */
 export declare function resumeWebhook(token: string, request: Request): Promise<Response>;
+export {};
 //# sourceMappingURL=resume-hook.d.ts.map

package/dist/runtime/resume-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resume-hook.d.ts","sourceRoot":"","sources":["../../src/runtime/resume-hook.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,IAAI,EAMV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,KAAK,SAAS,EAAa,MAAM,kBAAkB,CAAC;AAqC7D;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,GAAG,EACtC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,OAAO,EAAE,CAAC,EACV,qBAAqB,CAAC,EAAE,SAAS,GAChC,OAAO,CAAC,IAAI,CAAC,CAoHf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CA0DnB"}
+{"version":3,"file":"resume-hook.d.ts","sourceRoot":"","sources":["../../src/runtime/resume-hook.ts"],"names":[],"mappings":"AAMA,OAAO,EAUL,KAAK,IAAI,IAAI,SAAS,EACvB,MAAM,iBAAiB,CAAC;AAOzB,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,qBAAqB,CAAC;AAkG7B;;;;;GAKG;AACH,KAAK,aAAa,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,IAAK,SAAQ,aAAa;IACzC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAiLD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG;IAC/B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,GAAG,EACtC,WAAW,EAAE,MAAM,GAAG,aAAa,EACnC,OAAO,EAAE,CAAC,EACV,qBAAqB,CAAC,EAAE,UAAU,GACjC,OAAO,CAAC,WAAW,CAAC,CAoBtB;AAsUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CAsFnB"}