eve 0.7.0 → 0.7.3

package/dist/src/compiled/@workflow/core/create-hook.d.ts

@@ -1,3 +1,4 @@
+import type { Run } from './runtime/run.js';
 import type { Serializable } from './schemas.js';
 /**
  * An object that can be awaited to receive a value.
@@ -24,6 +25,42 @@ export interface Hook<T = any> extends AsyncIterable<T>, Thenable<T> {
      * The token used to identify this hook.
      */
     token: string;
+    /**
+     * Returns a promise that resolves with the conflicting {@link Run} if
+     * another active hook already owns this hook's token, or `null` once
+     * the hook has been registered and is ready to receive payloads.
+     *
+     * Calling `createHook()` alone does not register the hook — registration
+     * only happens when the workflow suspends. Awaiting `getConflict()`
+     * suspends the workflow to commit the hook registration, so it can be
+     * used to claim the token (and detect token conflicts early) without
+     * waiting for payload data.
+     *
+     * When a conflict is detected, the resolved `Run` is the run that
+     * currently owns the token. The workflow can decide how to handle the
+     * duplicate in code: return or log `conflict.runId`, inspect
+     * `await conflict.status`, await `conflict.returnValue`, or cancel the
+     * owner with `await conflict.cancel()` and continue in the current run.
+     *
+     * Note that awaiting the hook's payload (`await hook`) when the token is
+     * already owned by another active hook still rejects with
+     * `HookConflictError`. In the rare case where the conflicting run cannot
+     * be identified (a `hook_conflict` event persisted by an old world that
+     * did not record the owning run's ID), `getConflict()` also rejects with
+     * `HookConflictError` rather than resolving with an incomplete value.
+     *
+     * @example
+     * ```ts
+     * using hook = createHook({ token: `order:${orderId}` });
+     * const conflict = await hook.getConflict();
+     * if (conflict) {
+     *   // another run already owns this token
+     *   return { dedupedTo: conflict.runId };
+     * }
+     * // token is now claimed, without waiting for payload data
+     * ```
+     */
+    getConflict(): Promise<Run<unknown> | null>;
     /**
      * Disposes the hook, releasing its token for reuse by other workflows.
      *

package/dist/src/compiled/@workflow/core/global.d.ts

@@ -1,3 +1,4 @@
+import type { AttributeChange } from '#compiled/@workflow/world/index.js';
 import type { Serializable } from './schemas.js';
 export interface StepInvocationQueueItem {
     type: 'step';
@@ -14,6 +15,8 @@ export interface HookInvocationQueueItem {
     token: string;
     metadata?: Serializable;
     hasCreatedEvent?: boolean;
+    /** Whether the workflow is awaiting `hook.getConflict()` for this hook */
+    hasConflictAwaiter?: boolean;
     disposed?: boolean;
     isWebhook?: boolean;
     isSystem?: boolean;
@@ -26,7 +29,13 @@ export interface WaitInvocationQueueItem {
     resumeAt: Date;
     hasCreatedEvent?: boolean;
 }
-export type QueueItem = StepInvocationQueueItem | HookInvocationQueueItem | WaitInvocationQueueItem;
+export interface AttributeInvocationQueueItem {
+    type: 'attribute';
+    correlationId: string;
+    changes: AttributeChange[];
+    allowReservedAttributes?: true;
+}
+export type QueueItem = StepInvocationQueueItem | HookInvocationQueueItem | WaitInvocationQueueItem | AttributeInvocationQueueItem;
 /**
  * An error that is thrown when one or more operations (steps/hooks/etc.) are called but do
  * not yet have corresponding entries in the event log. The workflow
@@ -39,6 +48,7 @@ export declare class WorkflowSuspension extends Error {
     stepCount: number;
     hookCount: number;
     waitCount: number;
+    attributeCount: number;
     hookDisposedCount: number;
     abortCount: number;
     constructor(stepsInput: Map<string, QueueItem>, global: typeof globalThis);

package/dist/src/compiled/@workflow/core/index.js

@@ -1,2 +1,2 @@
-import{c as e,i as t}from"../../_chunks/workflow/dist-6a3viBXZ.js";import{at as n,c as r,it as i,l as a,ot as o,s}from"../../_chunks/workflow/symbols-BUTtwS7j.js";import{Bt as c,C as l,Ht as u,R as d,T as f,Vt as p,g as m,n as h,z as g,zt as _}from"../../_chunks/workflow/resume-hook-CEAS3opc.js";import{n as v,t as y}from"../../_chunks/workflow/sleep-Cup6vPoA.js";function b(e){n(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,b)}function x(e){n(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,x)}function S({schema:e}={}){function t(e){n(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await h(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
-`)}`)}return await h(t,r.value)}}}const C=Symbol.for(`@workflow/setAttributes//unsupportedWorldWarned`);async function w(e,n={}){let r=g.getStore()?.workflowMetadata?.workflowRunId;if(!r)throw new t(`experimental_setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let i=v(e,n);if(i.length===0)return;let a=await _();if(typeof a.runs.experimentalSetAttributes!=`function`){let e=globalThis;if(!e[C]){e[C]=!0;let t=`name`in a&&typeof a.name==`string`?a.name:``,n=t?` (${t})`:``;console.warn(`[workflow] setAttributes: the current world implementation${n} does not implement experimentalSetAttributes; this call (and any subsequent setAttributes calls in this process) is a no-op. Attributes will become available once the world adapter adds support.`)}return}await a.runs.experimentalSetAttributes(r,i,n.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{})}function T(){let e=g.getStore();return e||i(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,T),e.stepMetadata}function E(){let e=g.getStore();return e||o(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,E),e.workflowMetadata}function D(e={}){let t=g.getStore();t||o(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,D);let{namespace:n}=e,i=t.workflowMetadata.workflowRunId,h=d(i,n),_=t.writables??=new Map,v=_.get(h);if(v)return v.writable;let y=f(l(globalThis,t.ops,i,t.encryptionKey),t.encryptionKey),b=new m(i,h),x=c();return t.ops.push(x.promise),p(y.readable,b,x).catch(()=>{}),u(y.writable,x),Object.defineProperty(y.writable,s,{value:h,writable:!1}),Object.defineProperty(y.writable,a,{value:i,writable:!1}),t.workflowDeploymentId&&Object.defineProperty(y.writable,r,{value:t.workflowDeploymentId,writable:!1}),_.set(h,{writable:y.writable,state:x}),y.writable}export{t as FatalError,e as RetryableError,b as createHook,x as createWebhook,S as defineHook,w as experimental_setAttributes,T as getStepMetadata,E as getWorkflowMetadata,D as getWritable,y as sleep};
+import{c as e,i as t}from"../../_chunks/workflow/dist-6a3viBXZ.js";import{Jn as n,Jt as r,Kt as i,L as a,R as o,S as s,Xn as c,Yn as l,an as u,h as d,in as f,on as p,qt as m,rn as h,t as g,w as _}from"../../_chunks/workflow/attribute-changes-DGVGRGfw.js";import{n as v}from"../../_chunks/workflow/resume-hook-DMSadN9o.js";import{t as y}from"../../_chunks/workflow/sleep-CpXfoXLF.js";function b(e){l(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,b)}function x(e){l(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,x)}function S({schema:e}={}){function t(e){l(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await v(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+`)}`)}return await v(t,r.value)}}}async function C(e,n={}){let r=o.getStore(),i=r?.workflowMetadata?.workflowRunId;if(!i)throw new t(`experimental_setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let a=g(e,n);a.length!==0&&await(await h()).events.create(i,{eventType:`attr_set`,specVersion:4,eventData:{changes:a,writer:{type:`step`,stepId:r.stepMetadata.stepId,attempt:r.stepMetadata.attempt},...n.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}function w(){let e=o.getStore();return e||n(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,w),e.stepMetadata}function T(){let e=o.getStore();return e||c(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,T),e.workflowMetadata}function E(e={}){let t=o.getStore();t||c(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,E);let{namespace:n}=e,l=t.workflowMetadata.workflowRunId,h=a(l,n),g=t.writables??=new Map,v=g.get(h);if(v)return v.writable;let y=_(s(globalThis,t.ops,l,t.encryptionKey,!0),t.encryptionKey),b=new d(l,h),x=f();return t.ops.push(x.promise),u(y.readable,b,x).catch(()=>{}),p(y.writable,x),Object.defineProperty(y.writable,i,{value:h,writable:!1}),Object.defineProperty(y.writable,r,{value:l,writable:!1}),t.workflowDeploymentId&&Object.defineProperty(y.writable,m,{value:t.workflowDeploymentId,writable:!1}),g.set(h,{writable:y.writable,state:x}),y.writable}export{t as FatalError,e as RetryableError,b as createHook,x as createWebhook,S as defineHook,C as experimental_setAttributes,w as getStepMetadata,T as getWorkflowMetadata,E as getWritable,y as sleep};

package/dist/src/compiled/@workflow/core/runtime/start.d.ts

@@ -10,6 +10,12 @@ export interface StartOptionsBase {
      * The spec version to use for the workflow run. Defaults to the latest version.
      */
     specVersion?: number;
+    /**
+     * Plaintext attributes to seed on the run as it is created.
+     *
+     * Available for native-attributes runs (spec version 4 and later).
+     */
+    attributes?: Record<string, string>;
 }
 export interface StartOptionsWithDeploymentId extends StartOptionsBase {
     /**

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -24,10 +24,23 @@ export interface SuspensionHandlerResult {
      * into the same batch boundary.
      */
     createdStepCorrelationIds: Set<string>;
-    /** Timeout from waits, if any */
-    timeoutSeconds?: number;
+    /**
+     * The soonest pending wait, if any: seconds until it elapses and the
+     * correlationId of the wait that produced that timeout. The
+     * correlationId seeds the idempotency key for the wait-continuation
+     * queue message so that repeated suspension passes over the same
+     * pending wait collapse into a single delayed continuation.
+     */
+    waitTimeout?: {
+        seconds: number;
+        correlationId: string;
+    };
     /** Whether a hook conflict was detected (should re-invoke immediately) */
     hasHookConflict: boolean;
+    /** Whether a `hook.getConflict()` awaiter needs the workflow to continue immediately */
+    hasAwaitedHookCreation: boolean;
+    /** Whether native workflow attribute events were written for replay. */
+    hasAttributeEvents: boolean;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).

package/dist/src/compiled/@workflow/core/runtime/wait-continuation.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Wait-continuation dispatch: delay + idempotency-key selection.
+ *
+ * When V2 suspension processing observes a pending wait, it enqueues a
+ * delayed "continuation" message that fires once the wait elapses and
+ * drives the next replay (which completes the wait via the "complete
+ * elapsed waits" pass). This module decides the message's `delaySeconds`
+ * and `idempotencyKey`.
+ *
+ * The continuation is keyed on the wait's correlationId: while a wait is
+ * pending, every replay pass over the run re-observes it (e.g., once per
+ * step completion in `Promise.all([steps..., sleep()])`), and without
+ * dedupe each pass would enqueue another delayed continuation — each one
+ * a spurious full replay when the wait elapses, and each a fresh message
+ * that resets the delivery-attempt runaway guard. A key is attached in
+ * all cases: some worlds (e.g. world-postgres) serialize key-less
+ * workflow messages per run, which would park the continuation behind
+ * the handler's own inline step execution and defeat the race semantics
+ * the continuation exists to provide.
+ *
+ * The bare correlationId cannot be the key in every case, though: world
+ * dedupe windows outlive the first delivery (VQS keeps idempotency
+ * records until message-retention TTL; world-postgres keeps a
+ * completed-keys cache), so once a key has been used, a later enqueue
+ * under the same key is silently dropped. Any situation where a
+ * continuation is delivered while its wait is still pending therefore
+ * needs a fresh key for the re-enqueue, or the wait's timer is lost and
+ * the run stalls until unrelated traffic happens to wake it. Two such
+ * situations exist, each with its own key variation:
+ *
+ * - Waits longer than the maximum queue delay are chained: the delay is
+ *   clamped to `WAIT_CONTINUATION_MAX_DELAY_SECONDS` (23h — VQS messages
+ *   have a 24h retention limit, and one hour of buffer matches
+ *   world-vercel's own clamp for delayed re-enqueues), so the
+ *   continuation intentionally fires early, re-observes the wait, and
+ *   must enqueue the next hop. The key is suffixed with the hop index
+ *   (`ceil(timeoutSeconds / maxDelay)`): stable for every re-observation
+ *   within the same hop window (so passes dedupe), decremented at each
+ *   hop delivery (so the chain always advances). Worlds without a delay
+ *   limit (world-postgres, world-local) simply take the same ≤23h hops.
+ *
+ * - Near-elapsed waits (≤2s remaining) get a second-bucketed suffix. A
+ *   continuation delivered marginally early (clock skew between the
+ *   enqueuing and handling hosts; the ceil() on the delay can leave a ~0
+ *   margin) re-observes the wait as pending with ~1s remaining and must
+ *   be able to enqueue a fresh short-delay retry. The bucket suffix
+ *   keeps that retry enqueueable (its ≥1s delay guarantees a later
+ *   bucket) while still collapsing same-instant duplicates.
+ *
+ * Mid-range waits (more than the near-elapsed threshold, at most one
+ * hop) use the bare correlationId: every re-observation targets the same
+ * deadline, so deduping to the first message is semantically lossless.
+ * Host clock skew beyond the near-elapsed threshold could in principle
+ * deliver such a continuation early enough to re-observe its wait and
+ * lose the re-enqueue to the burnt key; the threshold is the skew
+ * tolerance we accept for the benefit of exactly-one continuation per
+ * wait.
+ */
+/**
+ * Maximum `delaySeconds` for a single wait-continuation message. Waits
+ * longer than this are chained across multiple hops. 23 hours: VQS
+ * messages have a 24h retention limit; the 1h buffer mirrors
+ * world-vercel's `MAX_DELAY_SECONDS`.
+ */
+export declare const WAIT_CONTINUATION_MAX_DELAY_SECONDS = 82800;
+/**
+ * Waits with at most this many seconds remaining use a second-bucketed
+ * idempotency key so an early-delivered continuation can re-enqueue its
+ * short-delay retry. This is also the host clock-skew tolerance for
+ * mid-range waits keyed on the bare correlationId.
+ */
+export declare const NEAR_ELAPSED_WAIT_THRESHOLD_SECONDS = 2;
+export interface WaitContinuationDispatch {
+    delaySeconds: number;
+    idempotencyKey: string;
+}
+/**
+ * Computes the queue delay and idempotency key for a wait-continuation
+ * message. `timeoutSeconds` is the time until the wait's `resumeAt`
+ * (floored at 1s by the suspension handler); `waitCorrelationId`
+ * identifies the wait so repeated suspension passes dedupe.
+ */
+export declare function getWaitContinuationDispatch(timeoutSeconds: number, waitCorrelationId: string, now?: number): WaitContinuationDispatch;
+//# sourceMappingURL=wait-continuation.d.ts.map