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

package/dist/logger.js

@@ -1,41 +1,91 @@
-import debug from 'debug';
+import { composeLogLine } from './log-format.js';
 import { getActiveSpan } from './telemetry.js';
-function createLogger(namespace) {
-    const baseDebug = debug(`workflow:${namespace}`);
-    const logger = (level) => {
-        const levelDebug = baseDebug.extend(level);
-        return (message, metadata) => {
-            // Always output error/warn to console so users see critical issues
-            // debug/info only output when DEBUG env var is set
-            if (level === 'error') {
-                console.error(`[Workflow] ${message}`, metadata ?? '');
-            }
-            else if (level === 'warn') {
-                console.warn(`[Workflow] ${message}`, metadata ?? '');
-            }
-            // Also log to debug library for verbose output when DEBUG is enabled
-            levelDebug(message, metadata);
-            if (levelDebug.enabled) {
-                getActiveSpan()
-                    .then((span) => {
-                    span?.addEvent(`${level}.${namespace}`, { message, ...metadata });
-                })
-                    .catch(() => {
-                    // Silently ignore telemetry errors
-                });
-            }
+/**
+ * Lightweight `DEBUG=` pattern matcher. Replaces the `debug` package, which
+ * was previously a static dependency of this module — that import path
+ * pulled `debug/src/node` and its dynamic `require('tty')` into the
+ * generated Next.js webpack flow route, breaking the V2 combined-bundle
+ * build with `Dynamic require of "tty" is not supported`. Keeping this
+ * module free of `debug` is a prerequisite for V2 webpack builds.
+ */
+function matchesDebugNamespace(namespace, patternList) {
+    if (!patternList) {
+        return false;
+    }
+    let enabled = false;
+    for (const rawPattern of patternList.split(',')) {
+        const pattern = rawPattern.trim();
+        if (!pattern) {
+            continue;
+        }
+        const isNegated = pattern.startsWith('-');
+        const candidate = isNegated ? pattern.slice(1) : pattern;
+        const regex = new RegExp(`^${candidate.replace(/[|\\{}()[\]^$+?.]/g, '\\$&').replace(/\*/g, '.*')}$`);
+        if (regex.test(namespace)) {
+            enabled = !isNegated;
+        }
+    }
+    return enabled;
+}
+function createLogger(namespace, options = {}) {
+    const build = (parentMetadata) => {
+        const getDebugNamespace = (level) => options.debugNamespace ?? `workflow:${namespace}:${level}`;
+        const logger = (level) => {
+            const debugNamespace = getDebugNamespace(level);
+            return (message, metadata) => {
+                const hasParent = Object.keys(parentMetadata).length > 0;
+                const hasCallSite = metadata && Object.keys(metadata).length > 0;
+                const merged = hasParent || hasCallSite
+                    ? { ...parentMetadata, ...(metadata ?? {}) }
+                    : undefined;
+                // Always output error/warn to console so users see critical issues.
+                // debug/info only output when DEBUG env var matches the namespace.
+                //
+                // Compose the framing + structured fields + (trimmed) stack into a
+                // single string so the runtime's `console.error` / `util.inspect`
+                // doesn't quote-escape multi-line stacks or paragraph hints inside
+                // a JSON-y object dump. The framing line stays at the top with the
+                // structured fields right under it; the stack body — with framework
+                // internal frames collapsed — sits at the bottom. See log-format.ts.
+                if (level === 'error' || level === 'warn') {
+                    const out = level === 'error' ? console.error : console.warn;
+                    out(composeLogLine('[workflow-sdk]', message, merged));
+                }
+                const debugEnabled = matchesDebugNamespace(debugNamespace, process.env.DEBUG);
+                if (debugEnabled) {
+                    console.debug(`[${debugNamespace}] ${message}`, merged ?? '');
+                    getActiveSpan()
+                        .then((span) => {
+                        span?.addEvent(`${level}.${namespace}`, { message, ...merged });
+                    })
+                        .catch(() => {
+                        // Silently ignore telemetry errors
+                    });
+                }
+            };
+        };
+        return {
+            debug: logger('debug'),
+            info: logger('info'),
+            warn: logger('warn'),
+            error: logger('error'),
+            child: (metadata) => build({ ...parentMetadata, ...metadata }),
+            forRun: (workflowRunId, workflowName, extra) => build({
+                ...parentMetadata,
+                workflowRunId,
+                ...(workflowName !== undefined ? { workflowName } : {}),
+                ...(extra ?? {}),
+            }),
         };
     };
-    return {
-        debug: logger('debug'),
-        info: logger('info'),
-        warn: logger('warn'),
-        error: logger('error'),
-    };
+    return build({});
 }
 export const stepLogger = createLogger('step');
 export const runtimeLogger = createLogger('runtime');
 export const webhookLogger = createLogger('webhook');
 export const eventsLogger = createLogger('events');
 export const adapterLogger = createLogger('adapter');
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nZ2VyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2xvZ2dlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssTUFBTSxPQUFPLENBQUM7QUFDMUIsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBRS9DLFNBQVMsWUFBWSxDQUFDLFNBQWlCO0lBQ3JDLE1BQU0sU0FBUyxHQUFHLEtBQUssQ0FBQyxZQUFZLFNBQVMsRUFBRSxDQUFDLENBQUM7SUFFakQsTUFBTSxNQUFNLEdBQUcsQ0FBQyxLQUFhLEVBQUUsRUFBRTtRQUMvQixNQUFNLFVBQVUsR0FBRyxTQUFTLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBRTNDLE9BQU8sQ0FBQyxPQUFlLEVBQUUsUUFBOEIsRUFBRSxFQUFFO1lBQ3pELG1FQUFtRTtZQUNuRSxtREFBbUQ7WUFDbkQsSUFBSSxLQUFLLEtBQUssT0FBTyxFQUFFLENBQUM7Z0JBQ3RCLE9BQU8sQ0FBQyxLQUFLLENBQUMsY0FBYyxPQUFPLEVBQUUsRUFBRSxRQUFRLElBQUksRUFBRSxDQUFDLENBQUM7WUFDekQsQ0FBQztpQkFBTSxJQUFJLEtBQUssS0FBSyxNQUFNLEVBQUUsQ0FBQztnQkFDNUIsT0FBTyxDQUFDLElBQUksQ0FBQyxjQUFjLE9BQU8sRUFBRSxFQUFFLFFBQVEsSUFBSSxFQUFFLENBQUMsQ0FBQztZQUN4RCxDQUFDO1lBRUQscUVBQXFFO1lBQ3JFLFVBQVUsQ0FBQyxPQUFPLEVBQUUsUUFBUSxDQUFDLENBQUM7WUFFOUIsSUFBSSxVQUFVLENBQUMsT0FBTyxFQUFFLENBQUM7Z0JBQ3ZCLGFBQWEsRUFBRTtxQkFDWixJQUFJLENBQUMsQ0FBQyxJQUFJLEVBQUUsRUFBRTtvQkFDYixJQUFJLEVBQUUsUUFBUSxDQUFDLEdBQUcsS0FBSyxJQUFJLFNBQVMsRUFBRSxFQUFFLEVBQUUsT0FBTyxFQUFFLEdBQUcsUUFBUSxFQUFFLENBQUMsQ0FBQztnQkFDcEUsQ0FBQyxDQUFDO3FCQUNELEtBQUssQ0FBQyxHQUFHLEVBQUU7b0JBQ1YsbUNBQW1DO2dCQUNyQyxDQUFDLENBQUMsQ0FBQztZQUNQLENBQUM7UUFDSCxDQUFDLENBQUM7SUFDSixDQUFDLENBQUM7SUFFRixPQUFPO1FBQ0wsS0FBSyxFQUFFLE1BQU0sQ0FBQyxPQUFPLENBQUM7UUFDdEIsSUFBSSxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUM7UUFDcEIsSUFBSSxFQUFFLE1BQU0sQ0FBQyxNQUFNLENBQUM7UUFDcEIsS0FBSyxFQUFFLE1BQU0sQ0FBQyxPQUFPLENBQUM7S0FDdkIsQ0FBQztBQUNKLENBQUM7QUFFRCxNQUFNLENBQUMsTUFBTSxVQUFVLEdBQUcsWUFBWSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0FBQy9DLE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxZQUFZLENBQUMsU0FBUyxDQUFDLENBQUM7QUFDckQsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLFlBQVksQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUNyRCxNQUFNLENBQUMsTUFBTSxZQUFZLEdBQUcsWUFBWSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0FBQ25ELE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxZQUFZLENBQUMsU0FBUyxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgZGVidWcgZnJvbSAnZGVidWcnO1xuaW1wb3J0IHsgZ2V0QWN0aXZlU3BhbiB9IGZyb20gJy4vdGVsZW1ldHJ5LmpzJztcblxuZnVuY3Rpb24gY3JlYXRlTG9nZ2VyKG5hbWVzcGFjZTogc3RyaW5nKSB7XG4gIGNvbnN0IGJhc2VEZWJ1ZyA9IGRlYnVnKGB3b3JrZmxvdzoke25hbWVzcGFjZX1gKTtcblxuICBjb25zdCBsb2dnZXIgPSAobGV2ZWw6IHN0cmluZykgPT4ge1xuICAgIGNvbnN0IGxldmVsRGVidWcgPSBiYXNlRGVidWcuZXh0ZW5kKGxldmVsKTtcblxuICAgIHJldHVybiAobWVzc2FnZTogc3RyaW5nLCBtZXRhZGF0YT86IFJlY29yZDxzdHJpbmcsIGFueT4pID0+IHtcbiAgICAgIC8vIEFsd2F5cyBvdXRwdXQgZXJyb3Ivd2FybiB0byBjb25zb2xlIHNvIHVzZXJzIHNlZSBjcml0aWNhbCBpc3N1ZXNcbiAgICAgIC8vIGRlYnVnL2luZm8gb25seSBvdXRwdXQgd2hlbiBERUJVRyBlbnYgdmFyIGlzIHNldFxuICAgICAgaWYgKGxldmVsID09PSAnZXJyb3InKSB7XG4gICAgICAgIGNvbnNvbGUuZXJyb3IoYFtXb3JrZmxvd10gJHttZXNzYWdlfWAsIG1ldGFkYXRhID8/ICcnKTtcbiAgICAgIH0gZWxzZSBpZiAobGV2ZWwgPT09ICd3YXJuJykge1xuICAgICAgICBjb25zb2xlLndhcm4oYFtXb3JrZmxvd10gJHttZXNzYWdlfWAsIG1ldGFkYXRhID8/ICcnKTtcbiAgICAgIH1cblxuICAgICAgLy8gQWxzbyBsb2cgdG8gZGVidWcgbGlicmFyeSBmb3IgdmVyYm9zZSBvdXRwdXQgd2hlbiBERUJVRyBpcyBlbmFibGVkXG4gICAgICBsZXZlbERlYnVnKG1lc3NhZ2UsIG1ldGFkYXRhKTtcblxuICAgICAgaWYgKGxldmVsRGVidWcuZW5hYmxlZCkge1xuICAgICAgICBnZXRBY3RpdmVTcGFuKClcbiAgICAgICAgICAudGhlbigoc3BhbikgPT4ge1xuICAgICAgICAgICAgc3Bhbj8uYWRkRXZlbnQoYCR7bGV2ZWx9LiR7bmFtZXNwYWNlfWAsIHsgbWVzc2FnZSwgLi4ubWV0YWRhdGEgfSk7XG4gICAgICAgICAgfSlcbiAgICAgICAgICAuY2F0Y2goKCkgPT4ge1xuICAgICAgICAgICAgLy8gU2lsZW50bHkgaWdub3JlIHRlbGVtZXRyeSBlcnJvcnNcbiAgICAgICAgICB9KTtcbiAgICAgIH1cbiAgICB9O1xuICB9O1xuXG4gIHJldHVybiB7XG4gICAgZGVidWc6IGxvZ2dlcignZGVidWcnKSxcbiAgICBpbmZvOiBsb2dnZXIoJ2luZm8nKSxcbiAgICB3YXJuOiBsb2dnZXIoJ3dhcm4nKSxcbiAgICBlcnJvcjogbG9nZ2VyKCdlcnJvcicpLFxuICB9O1xufVxuXG5leHBvcnQgY29uc3Qgc3RlcExvZ2dlciA9IGNyZWF0ZUxvZ2dlcignc3RlcCcpO1xuZXhwb3J0IGNvbnN0IHJ1bnRpbWVMb2dnZXIgPSBjcmVhdGVMb2dnZXIoJ3J1bnRpbWUnKTtcbmV4cG9ydCBjb25zdCB3ZWJob29rTG9nZ2VyID0gY3JlYXRlTG9nZ2VyKCd3ZWJob29rJyk7XG5leHBvcnQgY29uc3QgZXZlbnRzTG9nZ2VyID0gY3JlYXRlTG9nZ2VyKCdldmVudHMnKTtcbmV4cG9ydCBjb25zdCBhZGFwdGVyTG9nZ2VyID0gY3JlYXRlTG9nZ2VyKCdhZGFwdGVyJyk7XG4iXX0=
+export const buildLogger = createLogger('build', {
+    debugNamespace: 'workflow:build',
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibG9nZ2VyLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2xvZ2dlci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDakQsT0FBTyxFQUFFLGFBQWEsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBbUMvQzs7Ozs7OztHQU9HO0FBQ0gsU0FBUyxxQkFBcUIsQ0FDNUIsU0FBaUIsRUFDakIsV0FBK0I7SUFFL0IsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO1FBQ2pCLE9BQU8sS0FBSyxDQUFDO0lBQ2YsQ0FBQztJQUVELElBQUksT0FBTyxHQUFHLEtBQUssQ0FBQztJQUNwQixLQUFLLE1BQU0sVUFBVSxJQUFJLFdBQVcsQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUNoRCxNQUFNLE9BQU8sR0FBRyxVQUFVLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDbEMsSUFBSSxDQUFDLE9BQU8sRUFBRSxDQUFDO1lBQ2IsU0FBUztRQUNYLENBQUM7UUFFRCxNQUFNLFNBQVMsR0FBRyxPQUFPLENBQUMsVUFBVSxDQUFDLEdBQUcsQ0FBQyxDQUFDO1FBQzFDLE1BQU0sU0FBUyxHQUFHLFNBQVMsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsT0FBTyxDQUFDO1FBQ3pELE1BQU0sS0FBSyxHQUFHLElBQUksTUFBTSxDQUN0QixJQUFJLFNBQVMsQ0FBQyxPQUFPLENBQUMsb0JBQW9CLEVBQUUsTUFBTSxDQUFDLENBQUMsT0FBTyxDQUFDLEtBQUssRUFBRSxJQUFJLENBQUMsR0FBRyxDQUM1RSxDQUFDO1FBRUYsSUFBSSxLQUFLLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxFQUFFLENBQUM7WUFDMUIsT0FBTyxHQUFHLENBQUMsU0FBUyxDQUFDO1FBQ3ZCLENBQUM7SUFDSCxDQUFDO0lBRUQsT0FBTyxP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YixHQUFHLENBQUMsWUFBWSxLQUFLLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxZQUFZLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO2dCQUN2RCxHQUFHLENBQUMsS0FBSyxJQUFJLEVBQUUsQ0FBQzthQUNqQixDQUFDO1NBQ0wsQ0FBQztJQUNKLENBQUMsQ0FBQztJQUVGLE9BQU8sS0FBSyxDQUFDLEVBQUUsQ0FBQyxDQUFDO0FBQ25CLENBQUM7QUFFRCxNQUFNLENBQUMsTUFBTSxVQUFVLEdBQUcsWUFBWSxDQUFDLE1BQU0sQ0FBQyxDQUFDO0FBQy9DLE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxZQUFZLENBQUMsU0FBUyxDQUFDLENBQUM7QUFDckQsTUFBTSxDQUFDLE1BQU0sYUFBYSxHQUFHLFlBQVksQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUNyRCxNQUFNLENBQUMsTUFBTSxZQUFZLEdBQUcsWUFBWSxDQUFDLFFBQVEsQ0FBQyxDQUFDO0FBQ25ELE1BQU0sQ0FBQyxNQUFNLGFBQWEsR0FBRyxZQUFZLENBQUMsU0FBUyxDQUFDLENBQUM7QUFDckQsTUFBTSxDQUFDLE1BQU0sV0FBVyxHQUFHLFlBQVksQ0FBQyxPQUFPLEVBQUU7SUFDL0MsY0FBYyxFQUFFLGdCQUFnQjtDQUNqQyxDQUFDLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgeyBjb21wb3NlTG9nTGluZSB9IGZyb20gJy4vbG9nLWZvcm1hdC5qcyc7XG5pbXBvcnQgeyBnZXRBY3RpdmVTcGFuIH0gZnJvbSAnLi90ZWxlbWV0cnkuanMnO1xuXG50eXBlIExvZ01ldGFkYXRhID0gUmVjb3JkPHN0cmluZywgdW5rbm93bj47XG5cbnR5cGUgTG9nRm4gPSAobWVzc2FnZTogc3RyaW5nLCBtZXRhZGF0YT86IExvZ01ldGFkYXRhKSA9PiB2b2lkO1xuXG5leHBvcnQgaW50ZXJmYWNlIExvZ2dlciB7XG4gIGRlYnVnOiBMb2dGbjtcbiAgaW5mbzogTG9nRm47XG4gIHdhcm46IExvZ0ZuO1xuICBlcnJvcjogTG9nRm47XG4gIC8qKlxuICAgKiBSZXR1cm5zIGEgY2hpbGQgbG9nZ2VyIHRoYXQgbWVyZ2VzIHRoZSBnaXZlbiBtZXRhZGF0YSBpbnRvIGV2ZXJ5IGNhbGwuXG4gICAqIFVzZWZ1bCBmb3IgYXR0YWNoaW5nIHN0YWJsZSBjb250ZXh0IChlLmcuIGB3b3JrZmxvd1J1bklkYCwgYHdvcmtmbG93TmFtZWAsXG4gICAqIGBzdGVwSWRgKSBzbyBjYWxsZXJzIGRvbid0IGhhdmUgdG8gcmVwZWF0IGl0IG9uIGV2ZXJ5IGxvZy5cbiAgICpcbiAgICogQ2FsbC1zaXRlIG1ldGFkYXRhIHdpbnMgb24gY29uZmxpY3QsIHNvIGNoaWxkcmVuIGNhbiBzdGlsbCBvdmVycmlkZS5cbiAgICovXG4gIGNoaWxkOiAobWV0YWRhdGE6IExvZ01ldGFkYXRhKSA9PiBMb2dnZXI7XG4gIC8qKlxuICAgKiBDb252ZW5pZW5jZSBjaGlsZCBsb2dnZXIgZm9yIGEgd29ya2Zsb3cgcnVuLiBFcXVpdmFsZW50IHRvXG4gICAqIGBsb2dnZXIuY2hpbGQoeyB3b3JrZmxvd1J1bklkLCB3b3JrZmxvd05hbWUgfSlgLCBidXQgY2VudHJhbGl6ZWQgc28gYWxsXG4gICAqIHJ1bnRpbWUgY29kZSBzdHJ1Y3R1cmVzIHJ1biBtZXRhZGF0YSBjb25zaXN0ZW50bHkuXG4gICAqL1xuICBmb3JSdW46IChcbiAgICB3b3JrZmxvd1J1bklkOiBzdHJpbmcsXG4gICAgd29ya2Zsb3dOYW1lPzogc3RyaW5nLFxuICAgIGV4dHJhPzogTG9nTWV0YWRhdGFcbiAgKSA9PiBMb2dnZXI7XG59XG5cbnR5cGUgTG9nZ2VyT3B0aW9ucyA9IHtcbiAgZGVidWdOYW1lc3BhY2U/OiBzdHJpbmc7XG59O1xuXG4vKipcbiAqIExpZ2h0d2VpZ2h0IGBERUJVRz1gIHBhdHRlcm4gbWF0Y2hlci4gUmVwbGFjZXMgdGhlIGBkZWJ1Z2AgcGFja2FnZSwgd2hpY2hcbiAqIHdhcyBwcmV2aW91c2x5IGEgc3RhdGljIGRlcGVuZGVuY3kgb2YgdGhpcyBtb2R1bGUg4oCUIHRoYXQgaW1wb3J0IHBhdGhcbiAqIHB1bGxlZCBgZGVidWcvc3JjL25vZGVgIGFuZCBpdHMgZHluYW1pYyBgcmVxdWlyZSgndHR5JylgIGludG8gdGhlXG4gKiBnZW5lcmF0ZWQgTmV4dC5qcyB3ZWJwYWNrIGZsb3cgcm91dGUsIGJyZWFraW5nIHRoZSBWMiBjb21iaW5lZC1idW5kbGVcbiAqIGJ1aWxkIHdpdGggYER5bmFtaWMgcmVxdWlyZSBvZiBcInR0eVwiIGlzIG5vdCBzdXBwb3J0ZWRgLiBLZWVwaW5nIHRoaXNcbiAqIG1vZHVsZSBmcmVlIG9mIGBkZWJ1Z2AgaXMgYSBwcmVyZXF1aXNpdGUgZm9yIFYyIHdlYnBhY2sgYnVpbGRzLlxuICovXG5mdW5jdGlvbiBtYXRjaGVzRGVidWdOYW1lc3BhY2UoXG4gIG5hbWVzcGFjZTogc3RyaW5nLFxuICBwYXR0ZXJuTGlzdDogc3RyaW5nIHwgdW5kZWZpbmVkXG4pOiBib29sZWFuIHtcbiAgaWYgKCFwYXR0ZXJuTGlzdCkge1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuXG4gIGxldCBlbmFibGVkID0gZmFsc2U7XG4gIGZvciAoY29uc3QgcmF3UGF0dGVybiBvZiBwYXR0ZXJuTGlzdC5zcGxpdCgnLCcpKSB7XG4gICAgY29uc3QgcGF0dGVybiA9IHJhd1BhdHRlcm4udHJpbSgpO1xuICAgIGlmICghcGF0dGVybikge1xuICAgICAgY29udGludWU7XG4gICAgfVxuXG4gICAgY29uc3QgaXNOZWdhdGVkID0gcGF0dGVybi5zdGFydHNXaXRoKCctJyk7XG4gICAgY29uc3QgY2FuZGlkYXRlID0gaXNOZWdhdGVkID8gcGF0dGVybi5zbGljZSgxKSA6IHBhdHRlcm47XG4gICAgY29uc3QgcmVnZXggPSBuZXcgUmVnRXhwKFxuICAgICAgYF4ke2NhbmRpZGF0ZS5yZXBsYWNlKC9bfFxcXFx7fSgpW1xcXV4kKz8uXS9nLCAnXFxcXCQmJykucmVwbGFjZSgvXFwqL2csICcuKicpfSRgXG4gICAgKTtcblxuICAgIGlmIChyZWdleC50ZXN0KG5hbWVzcGFjZSkpIHtcbiAgICAgIGVuYWJsZWQgPSAhaXNOZWdhdGVkO1xuICAgIH1cbiAgfVxuXG4gIHJldHVybiBlbmFibGVkO1xufVxuXG5mdW5jdGlvbiBjcmVhdGVMb2dnZXIobmFtZXNwYWNlOiBzdHJpbmcsIG9wdGlvbnM6IExvZ2dlck9wdGlvbnMgPSB7fSk6IExvZ2dlciB7XG4gIGNvbnN0IGJ1aWxkID0gKHBhcmVudE1ldGFkYXRhOiBMb2dNZXRhZGF0YSk6IExvZ2dlciA9PiB7XG4gICAgY29uc3QgZ2V0RGVidWdOYW1lc3BhY2UgPSAobGV2ZWw6IHN0cmluZykgPT5cbiAgICAgIG9wdGlvbnMuZGVidWdOYW1lc3BhY2UgPz8gYHdvcmtmbG93OiR7bmFtZXNwYWNlfToke2xldmVsfWA7XG5cbiAgICBjb25zdCBsb2dnZXIgPSAobGV2ZWw6IHN0cmluZyk6IExvZ0ZuID0+IHtcbiAgICAgIGNvbnN0IGRlYnVnTmFtZXNwYWNlID0gZ2V0RGVidWdOYW1lc3BhY2UobGV2ZWwpO1xuXG4gICAgICByZXR1cm4gKG1lc3NhZ2UsIG1ldGFkYXRhKSA9PiB7XG4gICAgICAgIGNvbnN0IGhhc1BhcmVudCA9IE9iamVjdC5rZXlzKHBhcmVudE1ldGFkYXRhKS5sZW5ndGggPiAwO1xuICAgICAgICBjb25zdCBoYXNDYWxsU2l0ZSA9IG1ldGFkYXRhICYmIE9iamVjdC5rZXlzKG1ldGFkYXRhKS5sZW5ndGggPiAwO1xuICAgICAgICBjb25zdCBtZXJnZWQgPVxuICAgICAgICAgIGhhc1BhcmVudCB8fCBoYXNDYWxsU2l0ZVxuICAgICAgICAgICAgPyB7IC4uLnBhcmVudE1ldGFkYXRhLCAuLi4obWV0YWRhdGEgPz8ge30pIH1cbiAgICAgICAgICAgIDogdW5kZWZpbmVkO1xuXG4gICAgICAgIC8vIEFsd2F5cyBvdXRwdXQgZXJyb3Ivd2FybiB0byBjb25zb2xlIHNvIHVzZXJzIHNlZSBjcml0aWNhbCBpc3N1ZXMuXG4gICAgICAgIC8vIGRlYnVnL2luZm8gb25seSBvdXRwdXQgd2hlbiBERUJVRyBlbnYgdmFyIG1hdGNoZXMgdGhlIG5hbWVzcGFjZS5cbiAgICAgICAgLy9cbiAgICAgICAgLy8gQ29tcG9zZSB0aGUgZnJhbWluZyArIHN0cnVjdHVyZWQgZmllbGRzICsgKHRyaW1tZWQpIHN0YWNrIGludG8gYVxuICAgICAgICAvLyBzaW5nbGUgc3RyaW5nIHNvIHRoZSBydW50aW1lJ3MgYGNvbnNvbGUuZXJyb3JgIC8gYHV0aWwuaW5zcGVjdGBcbiAgICAgICAgLy8gZG9lc24ndCBxdW90ZS1lc2NhcGUgbXVsdGktbGluZSBzdGFja3Mgb3IgcGFyYWdyYXBoIGhpbnRzIGluc2lkZVxuICAgICAgICAvLyBhIEpTT04teSBvYmplY3QgZHVtcC4gVGhlIGZyYW1pbmcgbGluZSBzdGF5cyBhdCB0aGUgdG9wIHdpdGggdGhlXG4gICAgICAgIC8vIHN0cnVjdHVyZWQgZmllbGRzIHJpZ2h0IHVuZGVyIGl0OyB0aGUgc3RhY2sgYm9keSDigJQgd2l0aCBmcmFtZXdvcmtcbiAgICAgICAgLy8gaW50ZXJuYWwgZnJhbWVzIGNvbGxhcHNlZCDigJQgc2l0cyBhdCB0aGUgYm90dG9tLiBTZWUgbG9nLWZvcm1hdC50cy5cbiAgICAgICAgaWYgKGxldmVsID09PSAnZXJyb3InIHx8IGxldmVsID09PSAnd2FybicpIHtcbiAgICAgICAgICBjb25zdCBvdXQgPSBsZXZlbCA9PT0gJ2Vycm9yJyA/IGNvbnNvbGUuZXJyb3IgOiBjb25zb2xlLndhcm47XG4gICAgICAgICAgb3V0KGNvbXBvc2VMb2dMaW5lKCdbd29ya2Zsb3ctc2RrXScsIG1lc3NhZ2UsIG1lcmdlZCkpO1xuICAgICAgICB9XG5cbiAgICAgICAgY29uc3QgZGVidWdFbmFibGVkID0gbWF0Y2hlc0RlYnVnTmFtZXNwYWNlKFxuICAgICAgICAgIGRlYnVnTmFtZXNwYWNlLFxuICAgICAgICAgIHByb2Nlc3MuZW52LkRFQlVHXG4gICAgICAgICk7XG5cbiAgICAgICAgaWYgKGRlYnVnRW5hYmxlZCkge1xuICAgICAgICAgIGNvbnNvbGUuZGVidWcoYFske2RlYnVnTmFtZXNwYWNlfV0gJHttZXNzYWdlfWAsIG1lcmdlZCA/PyAnJyk7XG4gICAgICAgICAgZ2V0QWN0aXZlU3BhbigpXG4gICAgICAgICAgICAudGhlbigoc3BhbikgPT4ge1xuICAgICAgICAgICAgICBzcGFuPy5hZGRFdmVudChgJHtsZXZlbH0uJHtuYW1lc3BhY2V9YCwgeyBtZXNzYWdlLCAuLi5tZXJnZWQgfSk7XG4gICAgICAgICAgICB9KVxuICAgICAgICAgICAgLmNhdGNoKCgpID0+IHtcbiAgICAgICAgICAgICAgLy8gU2lsZW50bHkgaWdub3JlIHRlbGVtZXRyeSBlcnJvcnNcbiAgICAgICAgICAgIH0pO1xuICAgICAgICB9XG4gICAgICB9O1xuICAgIH07XG5cbiAgICByZXR1cm4ge1xuICAgICAgZGVidWc6IGxvZ2dlcignZGVidWcnKSxcbiAgICAgIGluZm86IGxvZ2dlcignaW5mbycpLFxuICAgICAgd2FybjogbG9nZ2VyKCd3YXJuJyksXG4gICAgICBlcnJvcjogbG9nZ2VyKCdlcnJvcicpLFxuICAgICAgY2hpbGQ6IChtZXRhZGF0YSkgPT4gYnVpbGQoeyAuLi5wYXJlbnRNZXRhZGF0YSwgLi4ubWV0YWRhdGEgfSksXG4gICAgICBmb3JSdW46ICh3b3JrZmxvd1J1bklkLCB3b3JrZmxvd05hbWUsIGV4dHJhKSA9PlxuICAgICAgICBidWlsZCh7XG4gICAgICAgICAgLi4ucGFyZW50TWV0YWRhdGEsXG4gICAgICAgICAgd29ya2Zsb3dSdW5JZCxcbiAgICAgICAgICAuLi4od29ya2Zsb3dOYW1lICE9PSB1bmRlZmluZWQgPyB7IHdvcmtmbG93TmFtZSB9IDoge30pLFxuICAgICAgICAgIC4uLihleHRyYSA/PyB7fSksXG4gICAgICAgIH0pLFxuICAgIH07XG4gIH07XG5cbiAgcmV0dXJuIGJ1aWxkKHt9KTtcbn1cblxuZXhwb3J0IGNvbnN0IHN0ZXBMb2dnZXIgPSBjcmVhdGVMb2dnZXIoJ3N0ZXAnKTtcbmV4cG9ydCBjb25zdCBydW50aW1lTG9nZ2VyID0gY3JlYXRlTG9nZ2VyKCdydW50aW1lJyk7XG5leHBvcnQgY29uc3Qgd2ViaG9va0xvZ2dlciA9IGNyZWF0ZUxvZ2dlcignd2ViaG9vaycpO1xuZXhwb3J0IGNvbnN0IGV2ZW50c0xvZ2dlciA9IGNyZWF0ZUxvZ2dlcignZXZlbnRzJyk7XG5leHBvcnQgY29uc3QgYWRhcHRlckxvZ2dlciA9IGNyZWF0ZUxvZ2dlcignYWRhcHRlcicpO1xuZXhwb3J0IGNvbnN0IGJ1aWxkTG9nZ2VyID0gY3JlYXRlTG9nZ2VyKCdidWlsZCcsIHtcbiAgZGVidWdOYW1lc3BhY2U6ICd3b3JrZmxvdzpidWlsZCcsXG59KTtcbiJdfQ==

package/dist/private.d.ts

@@ -1,10 +1,12 @@
 /**
  * Utils used by the bundler when transforming code
  */
-import type { CryptoKey } from './encryption.js';
+import type { WorldCapabilities } from '@workflow/world';
 import type { EventsConsumer } from './events-consumer.js';
 import type { QueueItem } from './global.js';
+import type { ReplayPayloadCache } from './replay-payload-cache.js';
 import type { Serializable } from './schemas.js';
+import type { PayloadKey } from './serialization/encryption.js';
 export type StepFunction<Args extends Serializable[] = any[], Result extends Serializable | unknown = unknown> = ((...args: Args) => Promise<Result>) & {
     maxRetries?: number;
     stepId?: string;
@@ -25,8 +27,19 @@ export declare function registerStepFunction(stepId: string, stepFn: StepFunctio
 export declare function getStepFunction(stepId: string): StepFunction | undefined;
 export interface WorkflowOrchestratorContext {
     runId: string;
-    encryptionKey: CryptoKey | undefined;
+    encryptionKey: PayloadKey | undefined;
+    worldCapabilities?: WorldCapabilities;
     globalThis: typeof globalThis;
+    /**
+     * Increments when a suspension is accepted and on every retained-session
+     * resume. STEP suspension signals capture it when scheduled and no-op if
+     * it moved (see step.ts) — this drops same-boundary sibling signals and
+     * timers queued at boundary N that would fire after the session resumed
+     * into boundary N+1. Sleep/hook/attribute signals are intentionally
+     * unguarded: their presence makes the boundary unretainable, so a late
+     * signal correctly demotes the session (workflow.ts `onWorkflowError`).
+     */
+    suspensionGeneration: number;
     eventsConsumer: EventsConsumer;
     /**
      * Map of pending invocations keyed by correlationId.
@@ -34,6 +47,11 @@ export interface WorkflowOrchestratorContext {
      */
     invocationsQueue: Map<string, QueueItem>;
     onWorkflowError: (error: Error) => void;
+    /**
+     * Mints the ULID body of a correlation id. Every entity a replay creates
+     * draws from this one monotonic sequence, so an id is an ordinal over the
+     * whole run and both replays of a run must draw in the same order.
+     */
     generateUlid: () => string;
     generateNanoid: () => string;
     /**
@@ -46,18 +64,238 @@ export interface WorkflowOrchestratorContext {
     promiseQueue: Promise<void>;
     /**
      * Counter of in-flight async data delivery operations (step result
-     * hydration, hook payload hydration). Suspensions must wait for this
-     * to reach 0 before firing, to avoid preempting data delivery.
+     * hydration, hook payload hydration, abort signal hydration). Suspensions
+     * must wait for this to reach 0 before firing, to avoid preempting data
+     * delivery — e.g. dehydrating a step's arguments while an abort that should
+     * be reflected in those arguments is still hydrating its reason.
      */
     pendingDeliveries: number;
+    /**
+     * Ordered registry of in-flight "branch-deciding" deliveries — the
+     * resolutions a workflow typically `Promise.race`s on, or awaits from
+     * independent concurrent branches: hook payloads (`hook_received`), wait
+     * completions (`wait_completed`), and step results (`step_completed` /
+     * `step_failed`). Keyed by the delivery's position (index) in the consumed
+     * event log.
+     *
+     * The problem: each of these resolutions reaches workflow code after a
+     * different, workload-dependent number of microtask hops. A buffered hook
+     * payload is observed via the async hook iterator (`yield await this`),
+     * costing extra hops; a `wait_completed` resolves with fewer, and a reused
+     * sleep can resolve in an entirely earlier loop iteration; a step result is
+     * gated on hydration whose cost varies between replays of the SAME
+     * invocation — the first replay pays the full decrypt/decompress/revive,
+     * while later replays sharing the invocation's `ReplayPayloadCache`
+     * memo-hit small primitive results and resolve in one or two hops. Either
+     * way, the resolution that the committed event log ordered first can lose a
+     * `Promise.race` (or a `useStep` ULID allocation) to a faster- or
+     * already-resolved competitor, diverging from the log and surfacing as
+     * `CorruptedEventLogError`.
+     *
+     * The fix is a strict, deterministic delivery order anchored on
+     * event-log position: a delivery does not resolve to the workflow until
+     * every relevant earlier-in-log delivery has been delivered. Because the
+     * gate is "the earlier delivery resolved", not "won a timing race", the
+     * outcome is independent of microtask hops, hydration/decryption time,
+     * and `Promise.race` argument order. Which earlier kinds a delivery defers
+     * behind is spelled out on {@link awaitEarlierDeliveries}.
+     *
+     * Index is used rather than the `eventId` string because `eventId` is an
+     * opaque, world-assigned value not guaranteed to sort in creation order
+     * (only the bundled ULID worlds happen to).
+     *
+     * Optional so older/out-of-tree contexts (and lightweight test harnesses)
+     * that do not initialize it degrade gracefully to the previous behavior.
+     */
+    pendingDeliveryBarriers?: Map<number, DeliveryBarrierEntry>;
+    /**
+     * Invocation-scoped cache of prepared serialized payloads and immutable final
+     * values. Prepared bytes survive fresh replay VMs; object graphs do not.
+     */
+    replayPayloadCache: ReplayPayloadCache;
+}
+/** The kind of branch-deciding delivery a barrier represents. */
+export type DeliveryKind = 'hook' | 'wait' | 'step';
+interface DeliveryBarrierEntry {
+    kind: DeliveryKind;
+    /** Resolves once this delivery has resolved to the workflow. */
+    delivered: Promise<void>;
+    /**
+     * Whether this delivery is committed to reaching the workflow without any
+     * further action by workflow code. True for wait completions and step
+     * results, which always resolve from their own chain, and for a hook payload
+     * that already had a waiting consumer when it was consumed.
+     *
+     * False for a BUFFERED hook payload no consumer has claimed yet: it is
+     * delivered by `claim()`, i.e. whenever the workflow next reads the hook —
+     * which may be causally *after* a later-in-log delivery. `arm()` flips it
+     * once a consumer takes the payload.
+     */
+    armed: boolean;
+}
+/**
+ * Awaits, in strict event-log order, every still-registered delivery that is
+ * earlier in the log than `eventIndex` and that a delivery of `kind` defers
+ * behind (see {@link DEFER_BEHIND}), so that this resolution is handed to the
+ * workflow only after all relevant earlier-in-log deliveries have been. This
+ * is what keeps a `Promise.race` — or the ULID a follow-up `useStep` draws on
+ * a concurrent branch — deterministic and aligned with the committed event
+ * log, independent of microtask-hop counts, hydration time, or race-argument
+ * order. When this delivery does have to wait, it also yields a macrotask
+ * afterwards so the earlier delivery's consumer can run to its own next
+ * suspension point first; see the comment at that `await` for why ordering the
+ * `resolve()` calls alone is not enough.
+ *
+ * What counts as "defers behind" is {@link gatesOn}, shared with
+ * {@link computeResolvesOnItsOwn} so the two cannot drift.
+ *
+ * One asymmetry: a STEP result skips any earlier delivery that is UNARMED,
+ * i.e. a buffered hook payload no consumer has claimed. Such a payload is
+ * delivered only when the workflow next reads the hook, and reaching that read
+ * very commonly requires the step result itself (`await stepX()` before the
+ * read). Gating the step on it would stall the workflow until the barrier's
+ * idle safety net fires, which then releases every delivery queued behind that
+ * payload at once — losing exactly the race this ordering exists to protect.
+ * Waits and hooks keep gating on unclaimed payloads: for them, waiting for the
+ * claim IS the ordering guarantee (a `wait_completed` must not preempt a
+ * payload the log ordered first).
+ *
+ * The skip is direct, never transitive. A step still gates on an earlier ARMED
+ * wait or hook, including one that is itself parked behind an unclaimed
+ * payload. Skipping those too would invert log order for the commonest shape
+ * there is: a workflow that creates a hook it does not read on this branch,
+ * races `step` against `sleep`, and has the log say the sleep won. The step
+ * would then overtake the wait, both branches would swap the correlation ids
+ * they draw next, and replay would diverge — see
+ * `step-delivery-ordering.test.ts`. Waiting instead is safe because the
+ * payload's own idle safety net retires it and the whole chain then delivers
+ * in log order; {@link hasParkedCommittedDelivery} deliberately reports such a
+ * step as not self-resolving so that idle stays reachable.
+ *
+ * "The whole chain then delivers in log order" rests on the PAYLOAD's safety
+ * net observing idle before the net of the wait parked behind it. If the
+ * wait's net fired first, the step's gate would open while the wait was still
+ * parked on the payload barrier and the inversion above would reappear. Within
+ * one drain window that order is structural, and carried by FIFO of the
+ * safety-net polls: nets arm via `setTimeout` in log order during synchronous
+ * consumption, each polling round re-arms through `promiseQueue.then(...)` in
+ * the order the checks ran, and each net that fires flips
+ * {@link hasParkedCommittedDelivery} back to true, re-blocking the rest until
+ * the released delivery completes. Replay — where divergence manifests —
+ * always consumes the log in one window. Do not "optimize" the net scheduling
+ * in a way that breaks that per-window FIFO.
+ */
+export declare function awaitEarlierDeliveries(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind): Promise<void>;
+/** Handle for a registered branch-deciding delivery barrier. */
+export interface DeliveryBarrier {
+    /**
+     * Mark this delivery as delivered to the workflow. Resolves its
+     * `delivered` promise so any later-in-log delivery gated on it (via
+     * {@link awaitEarlierDeliveries}) may proceed, and removes it from the
+     * registry. Idempotent.
+     */
+    markDelivered: () => void;
+    /**
+     * Mark this delivery as committed to happening, for a barrier registered
+     * unarmed (a buffered hook payload) once a consumer has claimed it. From
+     * then on a later step result may be ordered behind it. Idempotent.
+     */
+    arm: () => void;
 }
+/**
+ * Register a branch-deciding delivery at its event-log index so that later
+ * deliveries can be ordered strictly after it. Returns an inert handle when
+ * `pendingDeliveryBarriers` is not initialized.
+ *
+ * Pass `armed: false` for a delivery whose resolution waits on workflow code
+ * asking for it (a buffered hook payload); call `arm()` when it does.
+ *
+ * To guarantee a later delivery gated on this one can never hang when this
+ * delivery is abandoned (the workflow took a different branch or is
+ * suspending and never observes it), the barrier auto-resolves at idle.
+ *
+ * INVARIANT required of every call site: a barrier that is ever `armed` must
+ * be paired with a delivery chain that runs unconditionally — attached when
+ * the event is consumed (waits, step results, waiting-consumer hook payloads,
+ * aborts), or by the `claim()` whose invocation is what arms it (buffered
+ * hook payloads). The idle check ({@link scheduleWhenIdle}) refuses to
+ * observe idle while an armed, self-resolving barrier is undelivered, and the
+ * safety net below is itself idle-gated — so an armed barrier with no
+ * unconditional chain would livelock every idle check in the run, including
+ * its own retirement.
+ */
+export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext, eventIndex: number | undefined, kind: DeliveryKind, options?: {
+    armed?: boolean;
+}): DeliveryBarrier;
+/**
+ * Whether some registered branch-deciding delivery is going to reach the
+ * workflow without any further help (it is armed and not transitively parked
+ * behind an unclaimed buffered payload — see {@link resolvesOnItsOwn}) but
+ * has not been handed over yet.
+ *
+ * This is the delivery state `pendingDeliveries` cannot see. That counter
+ * covers the hydration window inside a serial `promiseQueue` slot and is
+ * released there, while the delivery's `resolve()` runs later, from a
+ * detached continuation behind {@link awaitEarlierDeliveries} — including its
+ * macrotask yield whenever the delivery had to defer. Replaying a batch of N
+ * parallel step results consumed in one drain window leaves N-1 of them
+ * parked on that yield with `pendingDeliveries` already at 0. An idle check
+ * armed during the same window (a pending `sleep()` arms one on every replay)
+ * could then observe "idle" mid-deferral and raise a `WorkflowSuspension`
+ * BEFORE the workflow's own continuations ran — a suspension carrying none of
+ * the follow-up work the batch was about to create, which the runtime
+ * dutifully schedules as nothing, leaving the run dormant until an unrelated
+ * timer fires (vercel/workflow#3183).
+ *
+ * Deliveries that do NOT resolve on their own must be excluded, not for
+ * accuracy but for termination: an unclaimed buffered hook payload is retired
+ * BY the idle safety net in {@link registerDeliveryBarrier}, so counting it
+ * here would gate its own retirement. That reasoning extends to whatever is
+ * parked behind such a payload — a wait, and a step gating on that wait — for
+ * the same reason: the whole chain moves only once the net fires, and it
+ * cannot fire while the chain is counted. Self-resolving deliveries always
+ * deliver from their own chains (see the INVARIANT on
+ * {@link registerDeliveryBarrier}) and never need that net, so waiting on
+ * them is deadlock-free.
+ */
+export declare function hasParkedCommittedDelivery(ctx: WorkflowOrchestratorContext): boolean;
+/**
+ * Whether no data delivery (step result, hook payload) is in flight right now.
+ *
+ * "In flight" is two distinct windows, each with its own guard:
+ * `pendingDeliveries > 0` covers hydration inside the serial queue slots, and
+ * {@link hasParkedCommittedDelivery} covers the detached gap between a slot
+ * releasing that counter and the delivery's `resolve()` actually running —
+ * deliberately outside `pendingDeliveries` (see step.ts), and invisible to it.
+ *
+ * Anything that decides a replay is over, or that a replay went wrong, has to
+ * consult this first: while it is false the workflow VM is mid-reaction, so
+ * what it has and has not done yet says nothing about the run. Two callers
+ * read it, for the two such decisions: {@link scheduleWhenIdle} for the
+ * suspension, and the events consumer's unconsumed-event check for divergence.
+ */
+export declare function isDeliveryIdle(ctx: WorkflowOrchestratorContext): boolean;
 /**
  * Schedule a callback to fire only after all pending data deliveries
  * (step results, hook payloads) and async deserialization have completed.
- * Uses a polling loop: setTimeout(0) → check pendingDeliveries →
- * if > 0, wait for promiseQueue → repeat. This handles the multi-round
- * delivery pattern where each hook payload delivery cycle appends new
- * async work to the promiseQueue.
+ * Uses a polling loop: setTimeout(0) → check pendingDeliveries and the
+ * barrier registry → if anything is still in flight, wait for promiseQueue →
+ * repeat. This handles the multi-round delivery pattern where each hook
+ * payload delivery cycle appends new async work to the promiseQueue. What
+ * counts as in flight is {@link isDeliveryIdle}.
+ *
+ * The initial `setTimeout(0)` macrotask is load-bearing and must NOT be
+ * downgraded to a microtask (`queueMicrotask`/`Promise.resolve().then`).
+ * `pendingDeliveries` only guards the host-side hydration window; between a
+ * delivery's `resolve()` and the workflow VM body running its continuation to
+ * register the next subscriber, `pendingDeliveries` is already 0 even though
+ * the VM is mid-reaction. Node does not guarantee a microtask scheduled in
+ * the host context settles after the cross-VM promise chain (resolve in host
+ * → workflow code in VM → subscribe back in host); the macrotask boundary
+ * gives that chain time to run, so the suspension does not preempt a sibling
+ * delivery still in flight. Empirically, replacing it with `queueMicrotask`
+ * breaks hook/sleep `Promise.race` ordering (CorruptedEventLogError).
  */
 export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
+export {};
 //# sourceMappingURL=private.d.ts.map

package/dist/private.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,YAAY,CACtB,IAAI,SAAS,YAAY,EAAE,GAAG,GAAG,EAAE,EACnC,MAAM,SAAS,YAAY,GAAG,OAAO,GAAG,OAAO,IAC7C,CAAC,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAsEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,QAGxE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAoBxE;AAOD,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,SAAS,GAAG,SAAS,CAAC;IACrC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,cAAc,EAAE,cAAc,CAAC;IAC/B;;;OAGG;IACH,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACxC,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,2BAA2B,EAChC,EAAE,EAAE,MAAM,IAAI,GACb,IAAI,CAYN"}
+{"version":3,"file":"private.d.ts","sourceRoot":"","sources":["../src/private.ts"],"names":[],"mappings":"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"}