eve 0.22.1 → 0.22.3

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

@@ -1,2 +1,2 @@
-export declare const version = "5.0.0-beta.26";
+export declare const version = "5.0.0-beta.28";
 //# sourceMappingURL=version.d.ts.map

package/dist/src/compiled/@workflow/core/workflow/world-init-stub.d.ts

@@ -5,8 +5,8 @@
  * is responsible for loading `world.ts` and populating the globalThis
  * world cache before any VM or step code executes. Including this module
  * (rather than letting the resolver fall through to the host file) keeps
- * `world.ts` and its server-only deps (`@workflow/world-vercel`,
- * `@workflow/world-local`, `cbor-x`, …) out of the workflow sandbox.
+ * `world.ts` and the configured server-only world package out of the
+ * workflow sandbox.
  *
  * See `../runtime/world-init.ts` for the host-side implementation and the
  * full rationale.

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

@@ -1 +1 @@
-import{c as e,i as t}from"../../_chunks/workflow/dist-Dxrjttr2.js";import{dn as n,fn as r,fr as i,lr as a,mr as o,nn as s,on as c,t as l,tn as u,un as d,ur as f}from"../../_chunks/workflow/attribute-changes-zAifvEhb.js";import{t as p}from"../../_chunks/workflow/sleep-C8B-TYir.js";import{t as m}from"../../_chunks/workflow/run-BJUPZ0Ni.js";async function h(e,n={}){let i=l(e,n);if(i.length===0)return;let a=n.allowReservedAttributes===!0,o=globalThis[r];if(!o)throw new t("experimental_setAttributes() called outside a workflow runtime context. It must be called from within a workflow body (`use workflow`).");await o(i,a?{allowReservedAttributes:!0}:{})}s(u,m);function g(e){let t=globalThis[d];return t||f(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,g),t(e)}function _(e){let{respondWith:t,token:n,...r}=e??{};if(n!==void 0)throw Error("`createWebhook()` does not accept a `token` option. Webhook tokens are always randomly generated. Use `createHook()` with `resumeHook()` for deterministic token patterns.");let i;t!==void 0&&(i={respondWith:t});let a=g({...r,metadata:i,isWebhook:!0}),{url:s}=o();return a.url=`${s}/.well-known/workflow/v1/webhook/${encodeURIComponent(a.token)}`,a}function v(){function e(t,n){i(`defineHook().resume()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,e)}return{create(e){return g(e)},resume:e}}function y(e={}){let{namespace:t}=e,r=globalThis[n](t);return Object.create(globalThis.WritableStream.prototype,{[c]:{value:r,writable:!1}})}function b(){a(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,b)}function x(){i(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,x)}export{t as FatalError,e as RetryableError,g as createHook,_ as createWebhook,v as defineHook,h as experimental_setAttributes,b as getStepMetadata,o as getWorkflowMetadata,y as getWritable,x as resumeHook,p as sleep};
+import{i as e}from"../../_chunks/workflow/dist-CttsoN4D.js";import{c as t,i as n}from"../../_chunks/workflow/dist-DpDDcpTl.js";import{An as r,En as i,On as a,Tn as o,dn as s,fn as c,nn as l,pn as u,rn as d,sn as f,t as p}from"../../_chunks/workflow/attribute-changes-BnKD8Y3m.js";import{t as m}from"../../_chunks/workflow/sleep-phozDCW8.js";import{t as h}from"../../_chunks/workflow/run-BSANnUPR.js";async function g(e,t={}){let r=p(e,t);if(r.length===0)return;let i=t.allowReservedAttributes===!0,a=globalThis[u];if(!a)throw new n("experimental_setAttributes() called outside a workflow runtime context. It must be called from within a workflow body (`use workflow`).");await a(r,i?{allowReservedAttributes:!0}:{})}d(l,h);function _(e){let t=globalThis[s];return t||i(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,_),t(e)}function v(t){let{respondWith:n,token:i,...a}=t??{};if(i!==void 0)throw Error("`createWebhook()` does not accept a `token` option. Webhook tokens are always randomly generated. Use `createHook()` with `resumeHook()` for deterministic token patterns.");let o;n!==void 0&&(o={respondWith:n});let s=_({...a,metadata:o,isWebhook:!0}),{url:c}=r();return s.url=e(c,{type:`webhook`,token:s.token}),s}function y(){function e(t,n){a(`defineHook().resume()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,e)}return{create(e){return _(e)},resume:e}}function b(e={}){let{namespace:t}=e,n=globalThis[c](t);return Object.create(globalThis.WritableStream.prototype,{[f]:{value:n,writable:!1}})}function x(){o(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,x)}function S(){a(`resumeHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow-api/resume-hook`,S)}export{n as FatalError,t as RetryableError,_ as createHook,v as createWebhook,y as defineHook,g as experimental_setAttributes,x as getStepMetadata,r as getWorkflowMetadata,b as getWritable,S as resumeHook,m as sleep};

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

@@ -1 +1 @@
-import{C as e,E as t,S as n,T as r,_ as i,a,b as o,c as s,d as c,f as l,g as u,h as d,i as f,l as p,m,n as h,o as g,p as _,r as v,s as y,t as b,u as x,v as S,w as C,x as w,y as T}from"../../_chunks/workflow/dist-Dxrjttr2.js";export{b as CorruptedEventLogError,h as ERROR_SLUGS,v as EntityConflictError,f as FatalError,a as HookConflictError,g as HookNotFoundError,t as RUN_ERROR_CODES,y as ReplayDivergenceError,s as RetryableError,p as RunExpiredError,x as RunNotSupportedError,c as RuntimeDecryptionError,l as SerializationError,_ as StepNotRegisteredError,m as ThrottleError,d as TooEarlyError,u as VERCEL_403_ERROR_MESSAGE,i as WorkflowBuildError,S as WorkflowError,T as WorkflowNotRegisteredError,o as WorkflowRunCancelledError,w as WorkflowRunFailedError,n as WorkflowRunNotCompletedError,e as WorkflowRunNotFoundError,C as WorkflowRuntimeError,r as WorkflowWorldError};
+import{C as e,E as t,S as n,T as r,_ as i,a,b as o,c as s,d as c,f as l,g as u,h as d,i as f,l as p,m,n as h,o as g,p as _,r as v,s as y,t as b,u as x,v as S,w as C,x as w,y as T}from"../../_chunks/workflow/dist-DpDDcpTl.js";export{b as CorruptedEventLogError,h as ERROR_SLUGS,v as EntityConflictError,f as FatalError,a as HookConflictError,g as HookNotFoundError,t as RUN_ERROR_CODES,y as ReplayDivergenceError,s as RetryableError,p as RunExpiredError,x as RunNotSupportedError,c as RuntimeDecryptionError,l as SerializationError,_ as StepNotRegisteredError,m as ThrottleError,d as TooEarlyError,u as VERCEL_403_ERROR_MESSAGE,i as WorkflowBuildError,S as WorkflowError,T as WorkflowNotRegisteredError,o as WorkflowRunCancelledError,w as WorkflowRunFailedError,n as WorkflowRunNotCompletedError,e as WorkflowRunNotFoundError,C as WorkflowRuntimeError,r as WorkflowWorldError};

package/dist/src/compiled/@workflow/world/analytics.d.ts

@@ -0,0 +1,182 @@
+import { z } from '#compiled/zod/index.js';
+import type { PaginatedResponse, PaginationOptions } from './shared.js';
+export declare const AnalyticsRunSchema: z.ZodObject<{
+    runId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    deploymentId: z.ZodString;
+    workflowName: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const AnalyticsStepSchema: z.ZodObject<{
+    runId: z.ZodString;
+    stepId: z.ZodString;
+    stepName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        completed: "completed";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>;
+    attempt: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    startedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const AnalyticsEventSchema: z.ZodObject<{
+    runId: z.ZodString;
+    eventId: z.ZodString;
+    eventType: z.ZodEnum<{
+        run_created: "run_created";
+        run_completed: "run_completed";
+        run_failed: "run_failed";
+        step_created: "step_created";
+        step_completed: "step_completed";
+        step_failed: "step_failed";
+        step_retrying: "step_retrying";
+        hook_created: "hook_created";
+        hook_received: "hook_received";
+        run_started: "run_started";
+        run_cancelled: "run_cancelled";
+        attr_set: "attr_set";
+        step_started: "step_started";
+        hook_disposed: "hook_disposed";
+        hook_conflict: "hook_conflict";
+        wait_created: "wait_created";
+        wait_completed: "wait_completed";
+    }>;
+    correlationId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    entityId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    stepName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowName: z.ZodString;
+    deploymentId: z.ZodString;
+    specVersion: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    runCreatedAt: z.ZodCoercedDate<unknown>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    vercelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    retryAfter: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    errorCode: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    isWebhook: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    isSystem: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const AnalyticsHookSchema: z.ZodObject<{
+    runId: z.ZodString;
+    hookId: z.ZodString;
+    status: z.ZodEnum<{
+        created: "created";
+        received: "received";
+        disposed: "disposed";
+        conflict: "conflict";
+    }>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    receivedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    disposedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    isWebhook: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    isSystem: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const AnalyticsWaitSchema: z.ZodObject<{
+    runId: z.ZodString;
+    waitId: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        waiting: "waiting";
+    }>;
+    resumeAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    createdAt: z.ZodCoercedDate<unknown>;
+    updatedAt: z.ZodCoercedDate<unknown>;
+    completedAt: z.ZodOptional<z.ZodNullable<z.ZodCoercedDate<unknown>>>;
+    workflowCoreVersion: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    workflowEncryptionEnabled: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type AnalyticsRun = z.infer<typeof AnalyticsRunSchema>;
+export type AnalyticsStep = z.infer<typeof AnalyticsStepSchema>;
+export type AnalyticsEvent = z.infer<typeof AnalyticsEventSchema>;
+export type AnalyticsHook = z.infer<typeof AnalyticsHookSchema>;
+export type AnalyticsWait = z.infer<typeof AnalyticsWaitSchema>;
+export interface AnalyticsListRunsParams {
+    workflowName?: string;
+    status?: AnalyticsRun['status'];
+    /**
+     * Bound the listing to runs active between `startTime` and `endTime`
+     * (ISO 8601 timestamps). Both must be provided together. A bounded window
+     * lets the backend prune its scan — the ClickHouse-backed Vercel
+     * implementation is significantly faster with one. Requesting a window
+     * older than the plan's observability lookback fails with
+     * `observability-upgrade-required`.
+     */
+    startTime?: string;
+    endTime?: string;
+    pagination?: PaginationOptions;
+}
+export interface AnalyticsListRunScopedParams {
+    runId: string;
+    pagination?: PaginationOptions;
+}
+export interface AnalyticsListEventsParams extends AnalyticsListRunScopedParams {
+    eventType?: AnalyticsEvent['eventType'];
+    correlationId?: string;
+}
+export interface AnalyticsListEventsByCorrelationIdParams {
+    correlationId: string;
+    pagination?: PaginationOptions;
+}
+export interface AnalyticsListHooksParams {
+    runId: string;
+    pagination?: PaginationOptions;
+}
+export interface AnalyticsListWaitsParams extends AnalyticsListRunScopedParams {
+    status?: AnalyticsWait['status'];
+}
+export interface Analytics {
+    runs: {
+        get(runId: string): Promise<AnalyticsRun>;
+        list(params?: AnalyticsListRunsParams): Promise<PaginatedResponse<AnalyticsRun>>;
+    };
+    steps: {
+        get(runId: string, stepId: string): Promise<AnalyticsStep>;
+        list(params: AnalyticsListRunScopedParams): Promise<PaginatedResponse<AnalyticsStep>>;
+    };
+    events: {
+        get(runId: string, eventId: string): Promise<AnalyticsEvent>;
+        list(params: AnalyticsListEventsParams): Promise<PaginatedResponse<AnalyticsEvent>>;
+        listByCorrelationId(params: AnalyticsListEventsByCorrelationIdParams): Promise<PaginatedResponse<AnalyticsEvent>>;
+    };
+    hooks: {
+        get(hookId: string, params?: {
+            runId?: string;
+        }): Promise<AnalyticsHook>;
+        list(params: AnalyticsListHooksParams): Promise<PaginatedResponse<AnalyticsHook>>;
+    };
+    waits: {
+        get(runId: string, waitId: string): Promise<AnalyticsWait>;
+        list(params: AnalyticsListWaitsParams): Promise<PaginatedResponse<AnalyticsWait>>;
+    };
+}
+//# sourceMappingURL=analytics.d.ts.map

package/dist/src/compiled/@workflow/world/env-config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Helpers for resolving numeric runtime-tuning constants from environment
+ * variables.
+ *
+ * Several SDK constants (timeouts, retry counts, stream buffering, …) are
+ * useful to tune per-deployment — most notably to dial them down on a
+ * dedicated e2e deployment so the test suite exercises edge paths (reconnects,
+ * batch splitting, retries) that otherwise only trigger after long durations
+ * or large payloads.
+ *
+ * `envNumber` reads `process.env[name]` lazily (so tests and deployments can
+ * override per invocation), clamps to an optional `[min, max]` range, and
+ * never throws — an env override is an escape hatch, not a hard requirement,
+ * so an invalid value falls back to the constant's compiled-in default. A
+ * misconfigured value warns once per process so the mistake is observable
+ * without spamming logs.
+ */
+export interface EnvNumberOptions {
+    /** Inclusive lower bound; values below are clamped up to it. Default 0. */
+    min?: number;
+    /** Inclusive upper bound; values above are clamped down to it. */
+    max?: number;
+    /** Require an integer; fractional values fall back to the default. */
+    integer?: boolean;
+}
+/**
+ * Resolve a numeric tuning constant from `process.env[name]`, falling back to
+ * `fallback` when the variable is unset, empty, or invalid. Clamps to
+ * `[min, max]` when provided.
+ */
+export declare function envNumber(name: string, fallback: number, options?: EnvNumberOptions): number;
+/**
+ * Reset the warn-once cache. Test-only — exported so unit tests can exercise
+ * the warning path repeatedly without sharing state across cases.
+ *
+ * @internal
+ */
+export declare function _resetEnvWarnCacheForTests(): void;
+//# sourceMappingURL=env-config.d.ts.map

package/dist/src/compiled/@workflow/world/events.d.ts

@@ -31,6 +31,15 @@ export declare const EventTypeSchema: z.ZodEnum<{
     wait_created: "wait_created";
     wait_completed: "wait_completed";
 }>;
+export type EventType = z.infer<typeof EventTypeSchema>;
+export declare const TerminalRunEventTypeSchema: z.ZodEnum<{
+    run_completed: "run_completed";
+    run_failed: "run_failed";
+    run_cancelled: "run_cancelled";
+}>;
+export type TerminalRunEventType = z.infer<typeof TerminalRunEventTypeSchema>;
+export declare const TERMINAL_RUN_EVENT_TYPES: ("run_completed" | "run_failed" | "run_cancelled")[];
+export declare function isTerminalRunEventType(eventType: string): eventType is TerminalRunEventType;
 export declare const BaseEventSchema: z.ZodObject<{
     eventType: z.ZodEnum<{
         run_created: "run_created";
@@ -54,6 +63,21 @@ export declare const BaseEventSchema: z.ZodObject<{
     correlationId: z.ZodOptional<z.ZodString>;
     specVersion: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * Event created when a hook is first invoked. The World implementation
+ * atomically creates both the event and the hook entity.
+ */
+export declare const HookCreatedEventSchema: z.ZodObject<{
+    specVersion: z.ZodOptional<z.ZodNumber>;
+    eventType: z.ZodLiteral<"hook_created">;
+    correlationId: z.ZodString;
+    eventData: z.ZodObject<{
+        token: z.ZodString;
+        metadata: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>>;
+        isWebhook: z.ZodOptional<z.ZodBoolean>;
+        isSystem: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
 declare const HookReceivedEventSchema: z.ZodObject<{
     specVersion: z.ZodOptional<z.ZodNumber>;
     eventType: z.ZodLiteral<"hook_received">;
@@ -404,6 +428,7 @@ export declare const EventSchema: z.ZodIntersection<z.ZodDiscriminatedUnion<[z.Z
     specVersion: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>>;
 export type Event = z.infer<typeof EventSchema>;
+export type HookCreatedEvent = z.infer<typeof HookCreatedEventSchema>;
 export type HookReceivedEvent = z.infer<typeof HookReceivedEventSchema>;
 export type HookConflictEvent = z.infer<typeof HookConflictEventSchema>;
 /**

package/dist/src/compiled/@workflow/world/index.d.ts

@@ -1,7 +1,10 @@
+export type * from './analytics.js';
+export { AnalyticsEventSchema, AnalyticsHookSchema, AnalyticsRunSchema, AnalyticsStepSchema, AnalyticsWaitSchema, } from './analytics.js';
 export type * from './attributes.js';
 export { ATTRIBUTE_KEY_MAX_LENGTH, ATTRIBUTE_MAX_PER_RUN, ATTRIBUTE_VALUE_MAX_BYTES, AttributeChangeSchema, AttributeChangesSchema, AttributeValidationError, applyAttributeChanges, RESERVED_ATTRIBUTE_KEY_PREFIX, validateAttributeChanges, validateAttributeKey, validateAttributeValue, } from './attributes.js';
+export { _resetEnvWarnCacheForTests, type EnvNumberOptions, envNumber, } from './env-config.js';
 export type * from './events.js';
-export { BaseEventSchema, CreateEventSchema, EVENT_DATA_REF_FIELDS, EventSchema, EventTypeSchema, stripEventDataRefs, } from './events.js';
+export { BaseEventSchema, CreateEventSchema, EVENT_DATA_REF_FIELDS, EventSchema, EventTypeSchema, HookCreatedEventSchema, isTerminalRunEventType, stripEventDataRefs, TERMINAL_RUN_EVENT_TYPES, TerminalRunEventTypeSchema, } from './events.js';
 export type * from './hooks.js';
 export { HookSchema } from './hooks.js';
 export type * from './interfaces.js';
@@ -9,7 +12,7 @@ export type * from './queue.js';
 export { getQueuePrefixKind, getQueueTopicPrefix, HealthCheckPayloadSchema, MessageId, parseQueueName, QueuePayloadSchema, QueuePrefix, RunInputSchema, resolveQueueNamespace, StepInvokePayloadSchema, ValidQueueName, WorkflowInvokePayloadSchema, } from './queue.js';
 export { reenqueueActiveRuns } from './recovery.js';
 export type * from './runs.js';
-export { WorkflowRunBaseSchema, WorkflowRunSchema, WorkflowRunStatusSchema, } from './runs.js';
+export { isTerminalWorkflowRunStatus, TERMINAL_WORKFLOW_RUN_STATUSES, TerminalWorkflowRunStatusSchema, WorkflowRunBaseSchema, WorkflowRunSchema, WorkflowRunStatusSchema, } from './runs.js';
 export type { SerializedData } from './serialization.js';
 export { LegacySerializedDataSchemaV1, SerializedDataSchema, } from './serialization.js';
 export type * from './shared.js';
@@ -18,7 +21,7 @@ export { PaginatedResponseSchema, StructuredErrorSchema, } from './shared.js';
 export type { SpecVersion } from './spec-version.js';
 export { isLegacySpecVersion, requiresNewerWorld, SPEC_VERSION_CURRENT, SPEC_VERSION_LEGACY, SPEC_VERSION_SUPPORTS_ATTRIBUTES, SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT, SPEC_VERSION_SUPPORTS_COMPRESSION, SPEC_VERSION_SUPPORTS_EVENT_SOURCING, } from './spec-version.js';
 export type * from './steps.js';
-export { StepSchema, StepStatusSchema } from './steps.js';
+export { isTerminalStepStatus, StepSchema, StepStatusSchema, TERMINAL_STEP_STATUSES, TerminalStepStatusSchema, } from './steps.js';
 export { DEFAULT_TIMESTAMP_THRESHOLD_FUTURE_MS, DEFAULT_TIMESTAMP_THRESHOLD_MS, DEFAULT_TIMESTAMP_THRESHOLD_PAST_MS, ulidToDate, validateUlidTimestamp, } from './ulid.js';
 export type * from './waits.js';
 export { WaitSchema, WaitStatusSchema } from './waits.js';

package/dist/src/compiled/@workflow/world/interfaces.d.ts

@@ -1,3 +1,4 @@
+import type { Analytics } from './analytics.js';
 import type { AttributeChange, ExperimentalSetAttributesResult } from './attributes.js';
 import type { CreateEventParams, CreateEventRequest, Event, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
 import type { GetHookParams, Hook, ListHooksParams } from './hooks.js';
@@ -180,15 +181,21 @@ export interface Storage {
  */
 export interface World extends Queue, Streamer, Storage {
     /**
-     * The highest spec version this World supports.
+     * Optional analytics read namespace for observability surfaces.
      *
-     * When set, `start()` creates runs at this version so world-specific
-     * features (e.g., CBOR queue transport) are enabled automatically.
-     * When omitted, runs default to `SPEC_VERSION_SUPPORTS_EVENT_SOURCING` (2),
-     * the safe baseline that all worlds — including community worlds on
-     * older @workflow/world versions — are expected to handle.
+     * These APIs return metadata-only rows intended for UI/CLI listing and
+     * trace views. Payload-bearing fields remain on the canonical runtime
+     * storage APIs (`runs`, `steps`, `events`, `hooks`) and their RemoteRef
+     * resolution path.
      */
-    specVersion?: number;
+    analytics?: Analytics;
+    /**
+     * The Workflow protocol spec version this World implements.
+     *
+     * Current runtimes require this to exactly match their
+     * `SPEC_VERSION_CURRENT` before they create or replay runs.
+     */
+    specVersion: number;
     /**
      * Whether calling `process.exit(1)` from a queue handler is observed by
      * the World as a delivery failure that will be retried.

package/dist/src/compiled/@workflow/world/runs.d.ts

@@ -8,6 +8,15 @@ export declare const WorkflowRunStatusSchema: z.ZodEnum<{
     failed: "failed";
     cancelled: "cancelled";
 }>;
+export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
+export declare const TerminalWorkflowRunStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+export type TerminalWorkflowRunStatus = z.infer<typeof TerminalWorkflowRunStatusSchema>;
+export declare const TERMINAL_WORKFLOW_RUN_STATUSES: ("completed" | "failed" | "cancelled")[];
+export declare function isTerminalWorkflowRunStatus(status: string): status is TerminalWorkflowRunStatus;
 /**
  * Base schema for the Workflow runs. Prefer using WorkflowRunSchema
  * which implements a discriminatedUnion for various states.
@@ -112,7 +121,6 @@ export declare const WorkflowRunSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     error: z.ZodUnion<readonly [z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>]>;
     completedAt: z.ZodCoercedDate<unknown>;
 }, z.core.$strip>], "status">;
-export type WorkflowRunStatus = z.infer<typeof WorkflowRunStatusSchema>;
 export type WorkflowRun = z.infer<typeof WorkflowRunSchema>;
 /**
  * WorkflowRun with input/output fields excluded (when resolveData='none').

package/dist/src/compiled/@workflow/world/shared.d.ts

@@ -11,10 +11,25 @@ export interface PaginationOptions {
     cursor?: string;
     sortOrder?: 'asc' | 'desc';
 }
+export declare const PageInfoSchema: z.ZodObject<{
+    currentLookbackDays: z.ZodNumber;
+    maxLookbackDays: z.ZodNumber;
+    currentWindowStart: z.ZodCoercedDate<unknown>;
+    maxWindowStart: z.ZodCoercedDate<unknown>;
+    upgradeAvailable: z.ZodBoolean;
+}, z.core.$strip>;
+export type PageInfo = z.infer<typeof PageInfoSchema>;
 export declare const PaginatedResponseSchema: <T extends z.ZodTypeAny>(dataSchema: T) => z.ZodObject<{
     data: z.ZodArray<T>;
     cursor: z.ZodNullable<z.ZodString>;
     hasMore: z.ZodBoolean;
+    pageInfo: z.ZodOptional<z.ZodObject<{
+        currentLookbackDays: z.ZodNumber;
+        maxLookbackDays: z.ZodNumber;
+        currentWindowStart: z.ZodCoercedDate<unknown>;
+        maxWindowStart: z.ZodCoercedDate<unknown>;
+        upgradeAvailable: z.ZodBoolean;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PaginatedResponse<T> = z.infer<ReturnType<typeof PaginatedResponseSchema<z.ZodType<T>>>>;
 /**

package/dist/src/compiled/@workflow/world/steps.d.ts

@@ -38,6 +38,14 @@ export declare const StepSchema: z.ZodObject<{
     specVersion: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type StepStatus = z.infer<typeof StepStatusSchema>;
+export declare const TerminalStepStatusSchema: z.ZodEnum<{
+    completed: "completed";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+export type TerminalStepStatus = z.infer<typeof TerminalStepStatusSchema>;
+export declare const TERMINAL_STEP_STATUSES: ("completed" | "failed" | "cancelled")[];
+export declare function isTerminalStepStatus(status: string): status is TerminalStepStatus;
 export type Step = z.infer<typeof StepSchema>;
 /**
  * Step with input/output fields excluded (when resolveData='none').

package/dist/src/compiled/@workflow/world-local/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        <http://www.apache.org/licenses/>
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Vercel Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.