eve 0.81.1 → 0.83.0

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

@@ -26,6 +26,27 @@ export declare function resolveQueueNamespace(namespace?: string): string | unde
  * - `getQueueTopicPrefix('workflow', 'custom')` → `'__custom_wkf_workflow_'`
  */
 export declare function getQueueTopicPrefix(kind: QueueKind, namespace?: string): QueuePrefix;
+/**
+ * The route a World that delivers over HTTP sends a prefix's messages to when
+ * no other route or handler is registered for that prefix (see
+ * {@link Queue.registerRoute}): the Workflow SDK's generated flow route,
+ * relative to the app's base URL.
+ */
+export declare const WORKFLOW_FLOW_ROUTE = "/.well-known/workflow/v1/flow";
+/**
+ * Validates a delivery route for {@link Queue.registerRoute}: an absolute path
+ * on the app's base URL (`/api/agent/queue`), with no query or fragment.
+ * Returns it unchanged.
+ */
+export declare function parseQueueRoute(path: string): string;
+/**
+ * The queue namespace a run's messages travel on, as recorded when the run was
+ * created (`executionContext.queueNamespace`), or `undefined` when it recorded
+ * none (or an invalid one), in which case the World's default namespace
+ * applies. A World uses this to re-enqueue a run to its own consumer (see
+ * `reenqueueActiveRuns`) rather than to the recovering process's prefix.
+ */
+export declare function getRunQueueNamespace(executionContext: unknown): string | undefined;
 export declare function parseQueueName(name: ValidQueueName): {
     prefix: QueuePrefix;
     id: string;
@@ -86,6 +107,10 @@ export type RunInput = z.infer<typeof RunInputSchema>;
  *
  * The `input` is the already-serialized (and possibly encrypted) step input:
  * the identical bytes the producer also sent on the direct `events.create`.
+ *
+ * The current `@workflow/core` runtime neither attaches nor reads this field:
+ * it publishes a step message only after its `step_created` write. The schema
+ * keeps accepting it so a message that carries it still parses.
  */
 export declare const StepDispatchInputSchema: z.ZodObject<{
     input: z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>;
@@ -227,21 +252,19 @@ export type HealthCheckPayload = z.infer<typeof HealthCheckPayloadSchema>;
 export declare const HealthCheckPayloadSchema: z.ZodObject<{
     __healthCheck: z.ZodLiteral<true>;
     correlationId: z.ZodString;
+    probeRunId: z.ZodOptional<z.ZodString>;
     runId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Health check MUST come first.
  *
  * Zod unions return the first matching member's output, and `z.object` strips
- * keys the matching member doesn't declare. `HealthCheckPayloadSchema` carries
- * an optional `runId`, so a probe payload also satisfies
- * `WorkflowInvokePayloadSchema` (whose only required field is `runId`). With
- * the invoke member first, parsing a runId-bearing probe silently dropped
- * `__healthCheck` and `correlationId`, and the runtime (which dispatches on
- * `__healthCheck` before falling through to the invoke schema) reinterpreted
- * the probe as "replay this run". That made the queue handler POST
- * `run_started` for a run that doesn't exist yet (404), fail, and retry
- * forever, so the probe never answered and `start()` timed out.
+ * keys the matching member doesn't declare. A probe from an older caller can
+ * carry the legacy `runId`, which also satisfies `WorkflowInvokePayloadSchema`
+ * (whose only required field is `runId`). With the invoke member first,
+ * parsing such a probe silently drops `__healthCheck` and `correlationId`, and
+ * the runtime (which dispatches on `__healthCheck` before falling through to
+ * the invoke schema) reinterprets the probe as "replay this run".
  *
  * Ordering health check first is safe in the other direction: it requires
  * `__healthCheck: true`, which an invoke payload never carries.
@@ -249,6 +272,7 @@ export declare const HealthCheckPayloadSchema: z.ZodObject<{
 export declare const QueuePayloadSchema: z.ZodUnion<readonly [z.ZodObject<{
     __healthCheck: z.ZodLiteral<true>;
     correlationId: z.ZodString;
+    probeRunId: z.ZodOptional<z.ZodString>;
     runId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     runId: z.ZodString;
@@ -431,12 +455,50 @@ export interface Queue {
      * whose queue mints a fresh ID per delivery degrades gracefully: owner
      * redeliveries fall back to the delayed-backstop path instead of executing
      * immediately, adding recovery latency but never wedging or duplicating.
+     *
+     * `meta.deliveryCount`, when the World reports it, is 1 on a message's first
+     * delivery and increments on every redelivery, whatever caused it (lease
+     * lapse, a rejected handler, a `{ timeoutSeconds }` result). A World whose
+     * queue cannot say leaves it `undefined`. `meta.createdAt`, when known, is
+     * when the message was first enqueued, unchanged across its redeliveries.
      */
     createQueueHandler(queueNamePrefix: QueuePrefix, handler: (message: unknown, meta: {
         attempt: number;
+        deliveryCount?: number;
+        createdAt?: Date;
         queueName: ValidQueueName;
         messageId: MessageId;
         requestId?: string;
     }) => Promise<unknown>): (req: Request) => Promise<Response>;
+    /**
+     * Optional. Delivers every message whose queue name starts with `prefix` to
+     * `handler` inside this process, without HTTP. For Worlds whose queue runs
+     * in the app's own process (world-local, world-postgres). `handler` takes
+     * the same request a route serving `createQueueHandler(prefix, ...)` would,
+     * so passing that route handler works. Takes precedence over
+     * {@link Queue.registerRoute} for the prefix; a later registration for the
+     * same prefix replaces an earlier one.
+     *
+     * Keyed by the exact prefix: registering `__wkf_workflow_` also takes the
+     * Workflow SDK's own messages. A queue consumer other than the Workflow SDK
+     * uses a prefix of its own, `__{namespace}_wkf_workflow_`.
+     */
+    registerHandler?(prefix: QueuePrefix, handler: (req: Request) => Promise<Response>): void;
+    /**
+     * Optional. The route (a path on the app's base URL, such as
+     * `/api/agent/queue`) that this World's HTTP delivery POSTs the messages of
+     * `prefix` to. The app serves it with `createQueueHandler(prefix, ...)`.
+     * A prefix without a registered route goes to the Workflow SDK's flow route
+     * ({@link WORKFLOW_FLOW_ROUTE}), so only the Workflow SDK relies on that
+     * path, and a queue consumer of its own registers its route here, before
+     * the World's `start()` when it has one (`start()` re-enqueues active runs).
+     * An in-process handler for the prefix ({@link Queue.registerHandler})
+     * takes precedence; a later registration for the same prefix replaces an
+     * earlier one.
+     *
+     * Worlds that deliver by subscription rather than by path (world-vercel)
+     * do not implement this: subscribe the route to the prefix's topics there.
+     */
+    registerRoute?(prefix: QueuePrefix, path: string): void;
 }
 //# sourceMappingURL=queue.d.ts.map

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

@@ -5,6 +5,12 @@ import { type Queue } from './queue.js';
  * processing after a world restart. The workflow handler is idempotent
  * (event-log replay), so duplicate enqueues are safe.
  *
+ * A run goes back to the queue namespace it recorded when it was created
+ * (`executionContext.queueNamespace`, see `getRunQueueNamespace`), so a run
+ * started under another namespace, or by a queue consumer other than the
+ * Workflow SDK, reaches its own consumer rather than this process's. Runs that
+ * recorded none use `namespace`.
+ *
  * @param runs - Storage runs interface for listing active runs
  * @param enqueue - Queue's enqueue method
  * @param label - Log prefix for identifying the world implementation (e.g. "world-local")

package/dist/src/compiled/@workflow/world/test-support/duplicate-event-fixtures.d.ts

@@ -10,6 +10,9 @@ import type { EventType } from '../events.js';
  * them with the log's own record of when each entity finished, because that is
  * the point past which the runtime has no consumer left for the entity.
  *
+ * Both apply the terminal-inert rule: once an entity's terminal event is in
+ * the log, every later event for that entity is inert, whatever its class.
+ *
  * The two rules agree on every fixture here, and the interesting ones are the
  * near misses: a retried step writes several `step_started` events that are
  * all consumed, and a step that is still open absorbs a second `step_created`.

package/dist/src/compiled/@workflow/world/test-support/in-band-fence-conformance.d.ts

@@ -0,0 +1,46 @@
+import type { Storage, WorldCapabilities } from '../interfaces.js';
+/**
+ * Conformance for the optional in-band writer fence (see
+ * `WorldCapabilities.inBandFence` and `CreateEventParams.inBand`).
+ *
+ * What every World that implements it must agree on, whatever it stores the
+ * count in:
+ *
+ * - It declares `capabilities.inBandFence`.
+ * - `list` returns `snapshot: { seq, seqInBand }`, and a new run holds one
+ *   in-band position (`run_created`'s), which `atRunCreation` names.
+ * - An in-band write at the current count is accepted and advances it by one.
+ * - A stale in-band write is refused with `InBandSupersededError` (412,
+ *   `in-band-superseded`) and allocates nothing: the log and the counts are
+ *   unchanged, and the next accepted write takes the very next slot.
+ * - Out-of-band writes move `seq` and never `seqInBand`.
+ * - Of several concurrent in-band writers holding the same count, exactly one
+ *   wins.
+ * - An in-band write with no expected count is refused with a 400.
+ *
+ * Import it from a World's own test file (by relative path, like the other
+ * test-support modules) and call it at module level.
+ */
+export interface InBandFenceConformanceOptions {
+    /** Describe-block name, usually the World's name. */
+    name: string;
+    /** The events storage under test. Called once per test. */
+    events: () => Storage['events'];
+    /** The capabilities the World under test declares (`World.capabilities`). */
+    capabilities: () => WorldCapabilities | undefined;
+    /** A run id for `run_created`, or `null` when the World mints it. */
+    newRunId: () => string | null;
+    /** In-band positions a new run holds (the World's documented initial count). */
+    atRunCreation: number;
+    /**
+     * A second events storage over the same backing data as the one passed in
+     * (for example a second instance on the same data directory or database),
+     * to check that the fence is shared between instances. Omit when the World
+     * cannot have two instances over one store.
+     */
+    secondEvents?: (first: Storage['events']) => Storage['events'];
+    /** How many concurrent writers to race. Defaults to 8. */
+    concurrentWriters?: number;
+}
+export declare function inBandFenceConformance(options: InBandFenceConformanceOptions): void;
+//# sourceMappingURL=in-band-fence-conformance.d.ts.map