@workflow/core 5.0.0-beta.4 → 5.0.0-beta.41

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

@@ -0,0 +1,89 @@
+/**
+ * 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 — 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;
+}): 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":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDhB"}

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 — 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 } = 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 });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVwbGF5LWJ1ZGdldC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9ydW50aW1lL3JlcGxheS1idWRnZXQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFVBQVUsRUFBRSxlQUFlLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUMvRCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUN2RCxPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFDckQsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUM3QyxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSxxQkFBcUIsQ0FBQztBQUN4RCxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsa0JBQWtCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUNoRixPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxjQUFjLENBQUM7QUFDcEQsT0FBTyxFQUFFLFFBQVEsRUFBRSxNQUFNLFlBQVksQ0FBQztBQUV0Qzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBdUNHO0FBQ0gsTUFBTSxPQUFPLFlBQVk7SUFDTixPQUFPLENBQVM7SUFDekIsU0FBUyxHQUFHLENBQUMsQ0FBQztJQUNkLGFBQWEsQ0FBZ0I7SUFFckMsWUFBWSxVQUFrQixrQkFBa0IsRUFBRTtRQUNoRCxJQUFJLENBQUMsT0FBTyxHQUFHLE9BQU8sQ0FBQztRQUN2QixJQUFJLENBQUMsYUFBYSxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztJQUNsQyxDQUFDO0lBRUQ7O09BRUc7SUFDSCxJQUFJLGlCQUFpQjtRQUNuQixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUM7SUFDdEIsQ0FBQztJQUVEOzs7T0FHRztJQUNILE9BQU87UUFDTCxNQUFNLElBQUksR0FDUixJQUFJLENBQUMsYUFBYSxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUMsR0FBRyxFQUFFLEdBQUcsSUFBSSxDQUFDLGFBQWEsQ0FBQztRQUNwRSxPQUFPLElBQUksQ0FBQyxTQUFTLEdBQUcsSUFBSSxDQUFDO0lBQy9CLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsS0FBSztRQUNILElBQUksSUFBSSxDQUFDLGFBQWEsS0FBSyxJQUFJO1lBQUUsT0FBTztRQUN4QyxJQUFJLENBQUMsU0FBUyxJQUFJLElBQUksQ0FBQyxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUMsYUFBYSxDQUFDO1FBQ2xELElBQUksQ0FBQyxhQUFhLEdBQUcsSUFBSSxDQUFDO0lBQzVCLENBQUM7SUFFRDs7Ozs7T0FLRztJQUNILE1BQU07UUFDSixJQUFJLENBQUMsYUFBYSxHQUFHLElBQUksQ0FBQyxHQUFHLEVBQUUsQ0FBQztJQUNsQyxDQUFDO0lBRUQ7Ozs7T0FJRztJQUNILFdBQVc7UUFDVCxPQUFPLElBQUksQ0FBQyxPQUFPLEVBQUUsSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDO0lBQ3hDLENBQUM7Q0FDRjtBQUVELE1BQU0sT0FBTyx1QkFBd0IsU0FBUSxLQUFLO0lBQzlCLElBQUksR0FBRyx5QkFBeUIsQ0FBQztDQUNwRDtBQUVEOzs7R0FHRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsMkJBQTJCLENBQUMsSUFNakQ7SUFDQyxNQUFNLEVBQUUsS0FBSyxFQUFFLFlBQVksRUFBRSxTQUFTLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBRSxHQUFHLElBQUksQ0FBQztJQUNsRSxNQUFNLFNBQVMsR0FBRyxhQUFhLENBQUMsTUFBTSxDQUFDLEtBQUssRUFBRSxZQUFZLENBQUMsQ0FBQztJQUU1RCxNQUFNLFVBQVUsR0FBRywwQkFBMEIsRUFBRSxDQUFDO0lBQ2hELElBQUksT0FBTyxJQUFJLFVBQVUsRUFBRSxDQUFDO1FBQzFCLFNBQVMsQ0FBQyxJQUFJLENBQUMscURBQXFELEVBQUU7WUFDcEUsU0FBUyxFQUFFLE9BQU87WUFDbEIsT0FBTztZQUNQLFVBQVU7U0FDWCxDQUFDLENBQUM7UUFDSCxNQUFNLElBQUksdUJBQXVCLENBQy9CLDhDQUE4QyxPQUFPLEdBQUcsSUFBSSxJQUFJLENBQ2pFLENBQUM7SUFDSixDQUFDO0lBRUQsTUFBTSxLQUFLLEdBQUcsTUFBTSxRQUFRLEVBQUUsQ0FBQztJQUUvQixNQUFNLHdCQUF3QixHQUFHLGFBQWEsQ0FDNUMsU0FBUyxFQUNULGVBQWUsQ0FBQyxjQUFjLENBQy9CLENBQUM7SUFDRixTQUFTLENBQUMsS0FBSyxDQUNiLDRFQUE0RSxFQUM1RTtRQUNFLFNBQVMsRUFBRSxPQUFPO1FBQ2xCLE9BQU87UUFDUCxVQUFVO1FBQ1YsU0FBUyxFQUFFLHdCQUF3QixDQUFDLFNBQVM7UUFDN0MsZ0JBQWdCLEVBQUUsd0JBQXdCLENBQUMsV0FBVztLQUN2RCxDQUNGLENBQUM7SUFFRixNQUFNLGdCQUFnQixHQUFHLG9CQUFvQixDQUFDLEtBQUssRUFBRSxLQUFLLENBQUMsQ0FBQztJQUM1RCxNQUFNLFVBQVUsR0FBRyxJQUFJLFVBQVUsQ0FDL0IsOENBQThDLE9BQU8sR0FBRyxJQUFJLFlBQVksT0FBTyxXQUFXLENBQzNGLENBQUM7SUFDRixNQUFNLEtBQUssQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUN2QixLQUFLLEVBQ0w7UUFDRSxTQUFTLEVBQUUsWUFBWTtRQUN2QixXQUFXLEVBQUUsb0JBQW9CO1FBQ2pDLFNBQVMsRUFBRTtZQUNULEtBQUssRUFBRSxNQUFNLGlCQUFpQixDQUM1QixVQUFVLEVBQ1YsS0FBSyxFQUNMLE1BQU0sZ0JBQWdCLEVBQUUsQ0FDekI7WUFDRCxTQUFTLEVBQUUsZUFBZSxDQUFDLGNBQWM7U0FDMUM7S0FDRixFQUNELEVBQUUsU0FBUyxFQUFFLENBQ2QsQ0FBQztBQUNKLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBGYXRhbEVycm9yLCBSVU5fRVJST1JfQ09ERVMgfSBmcm9tICdAd29ya2Zsb3cvZXJyb3JzJztcbmltcG9ydCB7IFNQRUNfVkVSU0lPTl9DVVJSRU5UIH0gZnJvbSAnQHdvcmtmbG93L3dvcmxkJztcbmltcG9ydCB7IGRlc2NyaWJlRXJyb3IgfSBmcm9tICcuLi9kZXNjcmliZS1lcnJvci5qcyc7XG5pbXBvcnQgeyBydW50aW1lTG9nZ2VyIH0gZnJvbSAnLi4vbG9nZ2VyLmpzJztcbmltcG9ydCB7IGRlaHlkcmF0ZVJ1bkVycm9yIH0gZnJvbSAnLi4vc2VyaWFsaXphdGlvbi5qcyc7XG5pbXBvcnQgeyBnZXRSZXBsYXlUaW1lb3V0TWF4UmV0cmllcywgZ2V0UmVwbGF5VGltZW91dE1zIH0gZnJvbSAnLi9jb25zdGFudHMuanMnO1xuaW1wb3J0IHsgbWVtb2l6ZUVuY3J5cHRpb25LZXkgfSBmcm9tICcuL2hlbHBlcnMuanMnO1xuaW1wb3J0IHsgZ2V0V29ybGQgfSBmcm9tICcuL3dvcmxkLmpzJztcblxuLyoqXG4gKiBQZXItaW52b2NhdGlvbiBhY2NvdW50aW5nIG9mIHRoZSAqbm9uLXN0ZXAqIHBvcnRpb24gb2YgYSB3b3JrZmxvd1xuICogaGFuZGxlciBydW46IGRldGVybWluaXN0aWMgZXZlbnQtbG9nIHJlcGxheSwgd29ya2Zsb3ctVk0gZXhlY3V0aW9uXG4gKiBiZXR3ZWVuIHN0ZXAgYm91bmRhcmllcywgc3VzcGVuc2lvbiBoYW5kbGluZywgcXVldWUgcm91bmQtdHJpcHMsIGV0Yy5cbiAqIElubGluZSBzdGVwIGJvZGllcyAoYFwidXNlIHN0ZXBcImAgZnVuY3Rpb25zIGludm9rZWQgdmlhIGBleGVjdXRlU3RlcGApXG4gKiBhcmUgaW50ZW50aW9uYWxseSBleGNsdWRlZCDigJQgdGhleSBhcmUgYm91bmRlZCBieSB0aGUgcGxhdGZvcm0nc1xuICogZnVuY3Rpb24gYG1heER1cmF0aW9uYCBhbmQgdGhlIGBOT19JTkxJTkVfUkVQTEFZX0FGVEVSX01TYCBlYXJseS1yZXR1cm5cbiAqIGd1YXJkLlxuICpcbiAqIFVzYWdlOlxuICpcbiAqIGBgYHRzXG4gKiBjb25zdCBidWRnZXQgPSBuZXcgUmVwbGF5QnVkZ2V0KCk7XG4gKiAvLyDigKZub24tc3RlcCB3b3JrIGhhcHBlbnMgaGVyZSwgYWNjdW11bGF0ZXMgYWdhaW5zdCB0aGUgYnVkZ2V04oCmXG4gKiBidWRnZXQucGF1c2UoKTtcbiAqIHRyeSB7XG4gKiAgIGF3YWl0IGV4ZWN1dGVTdGVwKC4uLik7IC8vIG5vdCBjaGFyZ2VkXG4gKiB9IGZpbmFsbHkge1xuICogICBidWRnZXQucmVzdW1lKCk7XG4gKiB9XG4gKiAvLyBiYWNrIHRvIGNoYXJnaW5nXG4gKiBpZiAoYnVkZ2V0LmlzRXhoYXVzdGVkKCkpIHsgLi4uIH1cbiAqIGBgYFxuICpcbiAqIEltcGxlbWVudGF0aW9uIG5vdGVzOlxuICpcbiAqIC0gYHBhdXNlKClgIGFuZCBgcmVzdW1lKClgIGFyZSBpZGVtcG90ZW50OiBjYWxsaW5nIGBwYXVzZSgpYCB3aGlsZVxuICogICBhbHJlYWR5IHBhdXNlZCAob3IgYHJlc3VtZSgpYCB3aGlsZSBhbHJlYWR5IHJlc3VtZWQpIGlzIGEgbm8tb3AuXG4gKiAgIFRoaXMgcHJvdGVjdHMgYWdhaW5zdCBkb3VibGUtY291bnRpbmcgaW4gZnV0dXJlIHJlZmFjdG9ycyB0aGF0IG5lc3RcbiAqICAgc3RlcCBleGVjdXRpb24gb3IgdGFrZSBhbiBlYXJseS1yZXR1cm4gcGF0aCBiZXR3ZWVuIGEgYHBhdXNlKClgIGFuZFxuICogICB0aGUgbWF0Y2hpbmcgYHJlc3VtZSgpYC5cbiAqIC0gYGlzRXhoYXVzdGVkKClgIGlzIGNoZWNrZWQgYXQgbG9vcCBib3VuZGFyaWVzIGJ5IHRoZSBjYWxsZXIg4oCUIHRoZVxuICogICBidWRnZXQgaXRzZWxmIGRvZXMgbm90IGFybSBhbnkgdGltZXJzLiBUaGlzIG1lYW5zIGFuIGluLWZsaWdodFxuICogICBwYXRob2xvZ2ljYWwgYHJ1bldvcmtmbG93YCBjYWxsIChlLmcuIGEgaHVnZSBldmVudC1sb2cgcmVwbGF5KSBjYW5cbiAqICAgb3ZlcnNob290IHRoZSBidWRnZXQgYnkgdXAgdG8gb25lIGl0ZXJhdGlvbidzIHdvcnRoIG9mIHdvcmsgYmVmb3JlXG4gKiAgIHRoZSBuZXh0IGNoZWNrIGZpcmVzLiBJbiBwcmFjdGljZSB0aGUgMjBzIGhlYWRyb29tIGJ1aWx0IGludG9cbiAqICAgYE1BWF9SRVBMQVlfVElNRU9VVF9NU2AgKGFuZCB0aGUgZnVuY3Rpb24gYG1heER1cmF0aW9uYCBjZWlsaW5nKVxuICogICBnaXZlcyB1cyBzbGFjazsgdGhlIG9sZCBgc2V0VGltZW91dGAtYmFzZWQgYXBwcm9hY2ggYWxzbyB1bHRpbWF0ZWx5XG4gKiAgIHJlbGllZCBvbiB0aGUgcGxhdGZvcm0gU0lHVEVSTSBhcyB0aGUgaGFyZCBiYWNrc3RvcC5cbiAqL1xuZXhwb3J0IGNsYXNzIFJlcGxheUJ1ZGdldCB7XG4gIHByaXZhdGUgcmVhZG9ubHkgbGltaXRNczogbnVtYmVyO1xuICBwcml2YXRlIGVsYXBzZWRNcyA9IDA7XG4gIHByaXZhdGUgaW50ZXJ2YWxTdGFydDogbnVtYmVyIHwgbnVsbDtcblxuICBjb25zdHJ1Y3RvcihsaW1pdE1zOiBudW1iZXIgPSBnZXRSZXBsYXlUaW1lb3V0TXMoKSkge1xuICAgIHRoaXMubGltaXRNcyA9IGxpbWl0TXM7XG4gICAgdGhpcy5pbnRlcnZhbFN0YXJ0ID0gRGF0ZS5ub3coKTtcbiAgfVxuXG4gIC8qKlxuICAgKiBUaGUgY29uZmlndXJlZCByZXBsYXktdGltZW91dCBsaW1pdCwgaW4gbXMuIFVzZWZ1bCBmb3IgbG9nIG1lc3NhZ2VzLlxuICAgKi9cbiAgZ2V0IGNvbmZpZ3VyZWRMaW1pdE1zKCk6IG51bWJlciB7XG4gICAgcmV0dXJuIHRoaXMubGltaXRNcztcbiAgfVxuXG4gIC8qKlxuICAgKiBUb3RhbCBub24tc3RlcCB0aW1lIGFjY3VtdWxhdGVkIHNvIGZhciwgaW4gbXMuIEluY2x1ZGVzIHRoZVxuICAgKiBjdXJyZW50bHktYWN0aXZlIGludGVydmFsIGlmIHRoZSBidWRnZXQgaXMgbm90IHBhdXNlZC5cbiAgICovXG4gIGVsYXBzZWQoKTogbnVtYmVyIHtcbiAgICBjb25zdCBvcGVuID1cbiAgICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9PT0gbnVsbCA/IDAgOiBEYXRlLm5vdygpIC0gdGhpcy5pbnRlcnZhbFN0YXJ0O1xuICAgIHJldHVybiB0aGlzLmVsYXBzZWRNcyArIG9wZW47XG4gIH1cblxuICAvKipcbiAgICogU3RvcCBjb3VudGluZyBlbGFwc2VkIHRpbWUgdG93YXJkIHRoZSBidWRnZXQuIElkZW1wb3RlbnQg4oCUIHNhZmUgdG9cbiAgICogY2FsbCBtdWx0aXBsZSB0aW1lcyBpbiBhIHJvdzsgc3Vic2VxdWVudCBjYWxscyBhcmUgbm8tb3BzIHVudGlsXG4gICAqIGByZXN1bWUoKWAgcmVvcGVucyBhbiBpbnRlcnZhbC5cbiAgICovXG4gIHBhdXNlKCk6IHZvaWQge1xuICAgIGlmICh0aGlzLmludGVydmFsU3RhcnQgPT09IG51bGwpIHJldHVybjtcbiAgICB0aGlzLmVsYXBzZWRNcyArPSBEYXRlLm5vdygpIC0gdGhpcy5pbnRlcnZhbFN0YXJ0O1xuICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9IG51bGw7XG4gIH1cblxuICAvKipcbiAgICogUmVzdW1lIGNvdW50aW5nIGVsYXBzZWQgdGltZSB0b3dhcmQgdGhlIGJ1ZGdldC4gSWRlbXBvdGVudCDigJQgc2FmZSB0b1xuICAgKiBjYWxsIG11bHRpcGxlIHRpbWVzIGluIGEgcm93OyBzdWJzZXF1ZW50IGNhbGxzIHJlLWFuY2hvciB0aGVcbiAgICogaW50ZXJ2YWwgc3RhcnQgdG8gYG5vdygpYCwgd2hpY2ggaXMgZmluZSBiZWNhdXNlIG5vIHRpbWUgYWNjcnVlc1xuICAgKiBiZXR3ZWVuIGJhY2stdG8tYmFjayBgcmVzdW1lKClgIGNhbGxzLlxuICAgKi9cbiAgcmVzdW1lKCk6IHZvaWQge1xuICAgIHRoaXMuaW50ZXJ2YWxTdGFydCA9IERhdGUubm93KCk7XG4gIH1cblxuICAvKipcbiAgICogVHJ1ZSBpZiB0aGUgYnVkZ2V0IGhhcyBiZWVuIGV4aGF1c3RlZCAoYGVsYXBzZWQoKSA+PSBsaW1pdE1zYCkuXG4gICAqIENhbGxlcnMgc2hvdWxkIGludm9rZSBgaGFuZGxlRXhoYXVzdGVkKC4uLilgIGFmdGVyd2FyZCBhbmQgcmV0dXJuXG4gICAqIGZyb20gdGhlIGhhbmRsZXIuXG4gICAqL1xuICBpc0V4aGF1c3RlZCgpOiBib29sZWFuIHtcbiAgICByZXR1cm4gdGhpcy5lbGFwc2VkKCkgPj0gdGhpcy5saW1pdE1zO1xuICB9XG59XG5cbmV4cG9ydCBjbGFzcyBSZXBsYXlUaW1lb3V0UmV0cnlFcnJvciBleHRlbmRzIEVycm9yIHtcbiAgb3ZlcnJpZGUgcmVhZG9ubHkgbmFtZSA9ICdSZXBsYXlUaW1lb3V0UmV0cnlFcnJvcic7XG59XG5cbi8qKlxuICogUmVqZWN0IHRoZSBjdXJyZW50IGRlbGl2ZXJ5IHdoaWxlIHJlcGxheS10aW1lb3V0IHJldHJpZXMgcmVtYWluLiBPbmNlXG4gKiBleGhhdXN0ZWQsIGZhaWwgdGhlIHJ1biBhbmQgbGV0IHRoZSBxdWV1ZSBhY2tub3dsZWRnZSB0aGUgZGVsaXZlcnkuXG4gKi9cbmV4cG9ydCBhc3luYyBmdW5jdGlvbiBoYW5kbGVSZXBsYXlCdWRnZXRFeGhhdXN0ZWQoYXJnczoge1xuICBydW5JZDogc3RyaW5nO1xuICB3b3JrZmxvd05hbWU6IHN0cmluZztcbiAgcmVxdWVzdElkOiBzdHJpbmcgfCB1bmRlZmluZWQ7XG4gIGF0dGVtcHQ6IG51bWJlcjtcbiAgbGltaXRNczogbnVtYmVyO1xufSk6IFByb21pc2U8dm9pZD4ge1xuICBjb25zdCB7IHJ1bklkLCB3b3JrZmxvd05hbWUsIHJlcXVlc3RJZCwgYXR0ZW1wdCwgbGltaXRNcyB9ID0gYXJncztcbiAgY29uc3QgcnVuTG9nZ2VyID0gcnVudGltZUxvZ2dlci5mb3JSdW4ocnVuSWQsIHdvcmtmbG93TmFtZSk7XG5cbiAgY29uc3QgbWF4UmV0cmllcyA9IGdldFJlcGxheVRpbWVvdXRNYXhSZXRyaWVzKCk7XG4gIGlmIChhdHRlbXB0IDw9IG1heFJldHJpZXMpIHtcbiAgICBydW5Mb2dnZXIud2FybignV29ya2Zsb3cgcmVwbGF5IGV4Y2VlZGVkIHRpbWVvdXQ7IHJldHJ5aW5nIGRlbGl2ZXJ5Jywge1xuICAgICAgdGltZW91dE1zOiBsaW1pdE1zLFxuICAgICAgYXR0ZW1wdCxcbiAgICAgIG1heFJldHJpZXMsXG4gICAgfSk7XG4gICAgdGhyb3cgbmV3IFJlcGxheVRpbWVvdXRSZXRyeUVycm9yKFxuICAgICAgYFdvcmtmbG93IHJlcGxheSBleGNlZWRlZCBtYXhpbXVtIGR1cmF0aW9uICgke2xpbWl0TXMgLyAxMDAwfXMpYFxuICAgICk7XG4gIH1cblxuICBjb25zdCB3b3JsZCA9IGF3YWl0IGdldFdvcmxkKCk7XG5cbiAgY29uc3QgcmVwbGF5VGltZW91dERlc2NyaXB0aW9uID0gZGVzY3JpYmVFcnJvcihcbiAgICB1bmRlZmluZWQsXG4gICAgUlVOX0VSUk9SX0NPREVTLlJFUExBWV9USU1FT1VUXG4gICk7XG4gIHJ1bkxvZ2dlci5lcnJvcihcbiAgICAnV29ya2Zsb3cgcmVwbGF5IGV4Y2VlZGVkIHRpbWVvdXQgYW5kIG1heCByZXRyaWVzIGV4Y2VlZGVkLiBGYWlsaW5nIHRoZSBydW4nLFxuICAgIHtcbiAgICAgIHRpbWVvdXRNczogbGltaXRNcyxcbiAgICAgIGF0dGVtcHQsXG4gICAgICBtYXhSZXRyaWVzLFxuICAgICAgZXJyb3JDb2RlOiByZXBsYXlUaW1lb3V0RGVzY3JpcHRpb24uZXJyb3JDb2RlLFxuICAgICAgZXJyb3JBdHRyaWJ1dGlvbjogcmVwbGF5VGltZW91dERlc2NyaXB0aW9uLmF0dHJpYnV0aW9uLFxuICAgIH1cbiAgKTtcblxuICBjb25zdCBnZXRFbmNyeXB0aW9uS2V5ID0gbWVtb2l6ZUVuY3J5cHRpb25LZXkod29ybGQsIHJ1bklkKTtcbiAgY29uc3QgdGltZW91dEVyciA9IG5ldyBGYXRhbEVycm9yKFxuICAgIGBXb3JrZmxvdyByZXBsYXkgZXhjZWVkZWQgbWF4aW11bSBkdXJhdGlvbiAoJHtsaW1pdE1zIC8gMTAwMH1zKSBhZnRlciAke2F0dGVtcHR9IGF0dGVtcHRzYFxuICApO1xuICBhd2FpdCB3b3JsZC5ldmVudHMuY3JlYXRlKFxuICAgIHJ1bklkLFxuICAgIHtcbiAgICAgIGV2ZW50VHlwZTogJ3J1bl9mYWlsZWQnLFxuICAgICAgc3BlY1ZlcnNpb246IFNQRUNfVkVSU0lPTl9DVVJSRU5ULFxuICAgICAgZXZlbnREYXRhOiB7XG4gICAgICAgIGVycm9yOiBhd2FpdCBkZWh5ZHJhdGVSdW5FcnJvcihcbiAgICAgICAgICB0aW1lb3V0RXJyLFxuICAgICAgICAgIHJ1bklkLFxuICAgICAgICAgIGF3YWl0IGdldEVuY3J5cHRpb25LZXkoKVxuICAgICAgICApLFxuICAgICAgICBlcnJvckNvZGU6IFJVTl9FUlJPUl9DT0RFUy5SRVBMQVlfVElNRU9VVCxcbiAgICAgIH0sXG4gICAgfSxcbiAgICB7IHJlcXVlc3RJZCB9XG4gICk7XG59XG4iXX0=

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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVwbGF5LXJlY292ZXJ5LXJlcG9ydGVyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3J1bnRpbWUvcmVwbGF5LXJlY292ZXJ5LXJlcG9ydGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUVBOzs7Ozs7O0dBT0c7QUFDSCxNQUFNLE9BQU8sc0JBQXNCO0lBSUo7SUFIckIsTUFBTSxHQUFHLEtBQUssQ0FBQztJQUNmLFFBQVEsR0FBRyxLQUFLLENBQUM7SUFFekIsWUFBNkIsZUFBdUI7UUFBdkIsb0JBQWUsR0FBZixlQUFlLENBQVE7SUFBRyxDQUFDO0lBRXhEOzs7Ozs7Ozs7T0FTRztJQUNILE1BQU0sQ0FBQyxLQUFLO1FBQ1YsT0FBTyxJQUFJLDJCQUEyQixFQUFFLENBQUM7SUFDM0MsQ0FBQztJQUVELFFBQVE7UUFDTixJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQztJQUNyQixDQUFDO0lBRUQ7Ozs7OztPQU1HO0lBQ0gsS0FBSyxDQUFDLGVBQWUsQ0FDbkIsTUFBcUMsRUFDckMsTUFBNkQ7UUFFN0QsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLElBQUksSUFBSSxDQUFDLFFBQVE7WUFBRSxPQUFPLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQztRQUV6RCxJQUFJLENBQUMsUUFBUSxHQUFHLElBQUksQ0FBQztRQUNyQixJQUFJLENBQUM7WUFDSCxPQUFPLE1BQU0sTUFBTSxDQUFDO2dCQUNsQixHQUFHLE1BQU07Z0JBQ1QscUJBQXFCLEVBQUUsSUFBSSxDQUFDLGVBQWU7YUFDNUMsQ0FBQyxDQUFDO1FBQ0wsQ0FBQztRQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7WUFDZixJQUFJLENBQUMsUUFBUSxHQUFHLEtBQUssQ0FBQztZQUN0QixNQUFNLEtBQUssQ0FBQztRQUNkLENBQUM7SUFDSCxDQUFDO0NBQ0Y7QUFFRCxnREFBZ0Q7QUFDaEQsTUFBTSwyQkFBNEIsU0FBUSxzQkFBc0I7SUFDOUQ7UUFDRSxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUM7SUFDWCxDQUFDO0lBRVEsUUFBUTtRQUNmLDZEQUE2RDtJQUMvRCxDQUFDO0NBQ0YiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgdHlwZSB7IENyZWF0ZUV2ZW50UGFyYW1zIH0gZnJvbSAnQHdvcmtmbG93L3dvcmxkJztcblxuLyoqXG4gKiBJbnZvY2F0aW9uLXNjb3BlZCwgb25lLXNob3QgcmVwb3J0ZXIgZm9yIGEgcmVwbGF5LWRpdmVyZ2VuY2UgcmVjb3ZlcnkuXG4gKlxuICogVGhlIHJlcG9ydGVyIHN0YXlzIGRvcm1hbnQgdW50aWwgcmVwbGF5IHJlYWNoZXMgYSB2YWxpZCBkZXRlcm1pbmlzdGljXG4gKiBib3VuZGFyeS4gVGhlIGZpcnN0IHN1YnNlcXVlbnQgZXZlbnQgd3JpdGUgY2FycmllcyB0aGUgdGVsZW1ldHJ5IGZvciBmcmVlLlxuICogQSByZWNvdmVyZWQgaW52b2NhdGlvbiB3aXRoIG5vIG5hdHVyYWwgZXZlbnQgd3JpdGUgaW50ZW50aW9uYWxseSByZXBvcnRzXG4gKiBub3RoaW5nLlxuICovXG5leHBvcnQgY2xhc3MgUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gIHByaXZhdGUgYWN0aXZlID0gZmFsc2U7XG4gIHByaXZhdGUgcmVwb3J0ZWQgPSBmYWxzZTtcblxuICBjb25zdHJ1Y3Rvcihwcml2YXRlIHJlYWRvbmx5IGRpdmVyZ2VuY2VDb3VudDogbnVtYmVyKSB7fVxuXG4gIC8qKlxuICAgKiBBIHJlcG9ydGVyIGZvciBhbiBpbnZvY2F0aW9uIHRoYXQgbmV2ZXIgZGl2ZXJnZWQ6IGBhY3RpdmF0ZSgpYCBjYW5ub3QgYXJtXG4gICAqIGl0LCBzbyBgd2l0aEV2ZW50Q3JlYXRlYCBhbHdheXMgcGFzc2VzIHdyaXRlcyB0aHJvdWdoIHVudG91Y2hlZC4gTGV0cyBldmVyeVxuICAgKiBjYWxsIHNpdGUgaG9sZCBhIG5vbi1vcHRpb25hbCByZXBvcnRlciBpbnN0ZWFkIG9mIGJyYW5jaGluZyBvbiBvbmUuXG4gICAqXG4gICAqIFN0cnVjdHVyYWxseSBpbmVydCByYXRoZXIgdGhhbiBhIHplcm8tY291bnQgcmVwb3J0ZXIgb24gcHVycG9zZSDigJQgdGhlXG4gICAqIHNlcnZlciByZWplY3RzIGEgY291bnQgYmVsb3cgMSBhcyBvdXQtb2YtcmFuZ2UgYW5kIGVtaXRzIGFcbiAgICogYHRlbGVtZXRyeV9yZWplY3RlZGAgbWV0cmljLCBzbyBhIHJlcG9ydGVyIHRoYXQgKmNhbiogcmVwb3J0IHplcm8gaXMgYVxuICAgKiBsaXZlIGZvb3RndW4uXG4gICAqL1xuICBzdGF0aWMgaW5lcnQoKTogUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gICAgcmV0dXJuIG5ldyBJbmVydFJlcGxheVJlY292ZXJ5UmVwb3J0ZXIoKTtcbiAgfVxuXG4gIGFjdGl2YXRlKCk6IHZvaWQge1xuICAgIHRoaXMuYWN0aXZlID0gdHJ1ZTtcbiAgfVxuXG4gIC8qKlxuICAgKiBEZWNvcmF0ZSBvbmUgbmF0dXJhbCBldmVudCB3cml0ZSB3aXRoIHJlY292ZXJ5IHRlbGVtZXRyeS5cbiAgICpcbiAgICogVGhlIGNsYWltIGlzIHRha2VuIHN5bmNocm9ub3VzbHksIHNvIGNvbmN1cnJlbnQgc3VzcGVuc2lvbiB3cml0ZXMgY2Fubm90XG4gICAqIGFsbCBjYXJyeSB0aGUgc2FtZSBjb3VudC4gQSBmYWlsZWQgcmVxdWVzdCByZWxlYXNlcyBpdCBmb3IgYSBsYXRlciBuYXR1cmFsXG4gICAqIHdyaXRlIGluIHRoZSBzYW1lIGludm9jYXRpb24uXG4gICAqL1xuICBhc3luYyB3aXRoRXZlbnRDcmVhdGU8VD4oXG4gICAgcGFyYW1zOiBDcmVhdGVFdmVudFBhcmFtcyB8IHVuZGVmaW5lZCxcbiAgICBjcmVhdGU6IChwYXJhbXM6IENyZWF0ZUV2ZW50UGFyYW1zIHwgdW5kZWZpbmVkKSA9PiBQcm9taXNlPFQ+XG4gICk6IFByb21pc2U8VD4ge1xuICAgIGlmICghdGhpcy5hY3RpdmUgfHwgdGhpcy5yZXBvcnRlZCkgcmV0dXJuIGNyZWF0ZShwYXJhbXMpO1xuXG4gICAgdGhpcy5yZXBvcnRlZCA9IHRydWU7XG4gICAgdHJ5IHtcbiAgICAgIHJldHVybiBhd2FpdCBjcmVhdGUoe1xuICAgICAgICAuLi5wYXJhbXMsXG4gICAgICAgIHJlcGxheURpdmVyZ2VuY2VDb3VudDogdGhpcy5kaXZlcmdlbmNlQ291bnQsXG4gICAgICB9KTtcbiAgICB9IGNhdGNoIChlcnJvcikge1xuICAgICAgdGhpcy5yZXBvcnRlZCA9IGZhbHNlO1xuICAgICAgdGhyb3cgZXJyb3I7XG4gICAgfVxuICB9XG59XG5cbi8qKiBTZWUge0BsaW5rIFJlcGxheVJlY292ZXJ5UmVwb3J0ZXIuaW5lcnR9LiAqL1xuY2xhc3MgSW5lcnRSZXBsYXlSZWNvdmVyeVJlcG9ydGVyIGV4dGVuZHMgUmVwbGF5UmVjb3ZlcnlSZXBvcnRlciB7XG4gIGNvbnN0cnVjdG9yKCkge1xuICAgIHN1cGVyKDApO1xuICB9XG5cbiAgb3ZlcnJpZGUgYWN0aXZhdGUoKTogdm9pZCB7XG4gICAgLy8gRGVsaWJlcmF0ZWx5IGVtcHR5OiBub3RoaW5nIHRvIHJlcG9ydCwgc28gbm90aGluZyBjYW4gYXJtLlxuICB9XG59XG4iXX0=

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

@@ -1,13 +1,36 @@
 import { type Hook } from '@workflow/world';
-import { type CryptoKey } from '../encryption.js';
+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 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.
+ *
+ * On the parallel fast path, `resumeHook()` writes the `hook_received` event and
+ * dispatches the workflow queue message concurrently. When the direct event
+ * write fails *transiently* — a 429/5xx, a transport error, or an expected
+ * `(runId, resumeId)` conflict with its own re-ensuring consumer — but the queue
+ * dispatch succeeds, the resume is still guaranteed: the queue consumer
+ * idempotently materializes the `hook_received` event from the payload carried
+ * on the message before replay. In that recovered case the returned hook carries
+ * `resilientResume: true`.
+ *
+ * On the happy path (the direct write landed) and on the sequential fallback
+ * path, the flag is absent (`undefined`). Callers that don't care about the
+ * distinction can 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.
  *
@@ -16,8 +39,8 @@ export declare function getHookByToken(token: string): Promise<Hook>;
  *
  * @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 +60,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 | Hook, 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.

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":"AAOA,OAAO,EAGL,KAAK,IAAI,EAUV,MAAM,iBAAiB,CAAC;AAQzB,OAAO,EAGL,KAAK,UAAU,EAGhB,MAAM,qBAAqB,CAAC;AAwJ7B;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,CAAC,GAAG,GAAG,EACtC,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,OAAO,EAAE,CAAC,EACV,qBAAqB,CAAC,EAAE,UAAU,GACjC,OAAO,CAAC,WAAW,CAAC,CAUtB;AAkaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,QAAQ,CAAC,CA+DnB"}