@lostgradient/weft 0.2.0

package/dist/server/runtime/context.d.ts

@@ -0,0 +1,73 @@
+import type { ServerWebSocket } from 'bun';
+import type { McpSessionManager } from '../../mcp/session.ts';
+import type { MetricsCollector } from '../../observability/metrics.ts';
+import type { WorkerRegistry } from '../../worker/registry.ts';
+import type { Authenticator, RateLimiter } from '../authentication.ts';
+import type { DeadlineTracker } from '../deadline-tracker.ts';
+import type { createEngineEventFeedBackend } from '../engine-event-feed-backend.ts';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+import type { JsonRpcWebSocketSession } from '../json-rpc-websocket.ts';
+import type { OpenApiSecuritySchemeName } from '../openapi.ts';
+import type { createLiveOperationRegistry, createLiveRestBindings } from '../rest-bindings.ts';
+import type { TaskQueue } from '../task-queue.ts';
+import type { WorkflowEventFeed } from '../workflow-event-feed.ts';
+import type { ResolvedCorsPolicy } from './cors.ts';
+/**
+ * Internal closure state for a single `serve()` invocation.
+ *
+ * Extracted runtime helpers receive this record explicitly so they do not
+ * rely on closure capture from `serve()`.
+ */
+export interface ServerContext {
+    readonly registry: WorkerRegistry;
+    readonly taskQueue: TaskQueue;
+    readonly workerSockets: Map<string, ServerWebSocket<WebSocketData>>;
+    readonly streamSockets: Map<string, Set<ServerWebSocket<WebSocketData>>>;
+    /** Tracks per-workflow worker affinity for sticky routing. Maps workflowId to workerId. */
+    readonly workerAffinity: Map<string, string>;
+    /** Reverse index: workflowId to set of operationIds currently in-flight for that workflow. */
+    readonly workflowOperations: Map<string, Set<string>>;
+    /** Reverse lookup: operationId to workflowId for O(1) cleanup on task completion. */
+    readonly operationToWorkflow: Map<string, string>;
+    /** Tracks pending backoff-delay timers so they can be cleared on shutdown. */
+    readonly pendingTimers: Set<ReturnType<typeof setTimeout>>;
+    /** In-memory min-heap for inflight task deadlines, avoiding full storage scans on each visibility tick. */
+    readonly deadlineTracker: DeadlineTracker;
+    readonly liveOperationRegistry: ReturnType<typeof createLiveOperationRegistry>;
+    readonly liveRestBindings: ReturnType<typeof createLiveRestBindings>;
+    readonly supportedAuthenticationSchemes: ReadonlySet<OpenApiSecuritySchemeName>;
+    /** Resolved CORS policy, or `null` when `serve()` was called without `cors` (same-origin only). */
+    readonly corsPolicy: ResolvedCorsPolicy | null;
+    /** Server-owned process-local metrics collector used by runtime diagnostics. */
+    readonly metricsCollector: MetricsCollector;
+    readonly eventFeedBackend: ReturnType<typeof createEngineEventFeedBackend>;
+    readonly workflowEventFeed: WorkflowEventFeed;
+    readonly activeJsonRpcSessions: Set<JsonRpcWebSocketSession>;
+    readonly mcpSessionManager: McpSessionManager;
+    readonly authenticatorPromise: Promise<Authenticator> | null;
+    /**
+     * Per-key request rate limiter, or `null` when `serve()` was called without
+     * `rateLimit`. Keyed by authenticated principal subject when available, else
+     * by client address. Disposed on `server.stop()`.
+     */
+    readonly rateLimiter: RateLimiter | null;
+    /** Visibility poll interval in milliseconds. */
+    readonly visibilityPollMs: number;
+    /**
+     * Grace period (in ms) before the close handler requeues a disconnected
+     * worker's in-flight tasks. A re-register from the same worker id within
+     * this window cancels the pending requeue. `0` means inline requeue.
+     */
+    readonly workerReconnectGracePeriodMs: number;
+    /**
+     * Pending requeue timers keyed by `workerId`. A successful re-register clears
+     * the timer for that worker, suppressing the deferred requeue.
+     */
+    readonly pendingWorkerRequeues: Map<string, ReturnType<typeof setTimeout>>;
+    /** Mutex: prevents concurrent visibility scans from running simultaneously. */
+    scanRunning: boolean;
+    /** Fine-grained mutex for in-flight operation IDs being processed by expiry paths. */
+    readonly processingOperations: Set<string>;
+    /** Mutex: prevents concurrent reconciliation scans from running simultaneously. */
+    reconciliationRunning: boolean;
+}

package/dist/server/runtime/cors.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Cross-Origin Resource Sharing (CORS) for the Weft server.
+ *
+ * The server supports browser clients such as external dashboards and the
+ * documented browser runtime (Service Worker + IndexedDB). When those run on a
+ * different origin than the API, the browser enforces CORS — and with no policy
+ * configured it blocks every cross-origin call. This module supplies an
+ * opt-in, **safe by default** policy: when `serve()` is called without a `cors`
+ * option, the server emits no `Access-Control-*` headers at all (same-origin
+ * only). It never defaults to `Access-Control-Allow-Origin: *`.
+ *
+ * Three pieces wire into the request pipeline:
+ *   - {@link buildPreflightResponse} answers `OPTIONS` preflight requests
+ *     before authentication runs (browsers never send credentials on
+ *     preflight, so auth-gating it would break CORS).
+ *   - {@link decorateResponseWithCors} adds the response headers for actual
+ *     (non-preflight) requests.
+ *   - {@link isOriginAllowed} gates WebSocket upgrades, which CORS does not
+ *     otherwise protect.
+ *
+ * Origins are compared as canonical origin tuples (`scheme://host[:port]`)
+ * via the URL parser, so case, default-port elision, and trailing slashes do
+ * not cause spurious mismatches. The literal `Origin: null` (sandboxed iframe,
+ * `file://`) never matches an allowlist entry.
+ *
+ * @module server/runtime/cors
+ */
+/**
+ * Operator-supplied CORS policy. Attach to `serve({ cors })`. Omitting it is
+ * the safe default — the server emits no `Access-Control-*` headers and only
+ * same-origin browser requests succeed; it never defaults to a wildcard origin.
+ *
+ * @example
+ * ```ts
+ * import { serve, type CorsOptions } from '@lostgradient/weft/server';
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ *
+ * const cors: CorsOptions = {
+ *   allowedOrigins: ['https://dashboard.example.com'],
+ *   credentials: true,
+ * };
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * await using server = serve({ engine, port: 0, cors });
+ * void server;
+ * ```
+ */
+export interface CorsOptions {
+    /**
+     * Origins permitted to make cross-origin requests. Either an explicit
+     * allowlist (compared as canonical origins) or a predicate that receives
+     * the raw `Origin` header value. The single-element sentinel `['*']` means
+     * "any origin" and is only legal when `credentials` is not `true`.
+     *
+     * Omitting this (or an empty array) allows no cross-origin requests.
+     *
+     * Note: the array form canonicalizes both the allowlist and the incoming
+     * origin (so case, default-port elision, and trailing slashes do not matter).
+     * The predicate form receives the **raw** `Origin` header value with no
+     * canonicalization — apply `canonicalizeOrigin` yourself if you need the same
+     * normalization for case-insensitive or default-port comparisons.
+     */
+    readonly allowedOrigins?: ReadonlyArray<string> | ((origin: string) => boolean);
+    /** Methods advertised in preflight responses. Defaults to the common verbs plus `OPTIONS`. */
+    readonly allowedMethods?: ReadonlyArray<string>;
+    /** Request headers a client may send. Defaults to `Authorization, Content-Type`. */
+    readonly allowedHeaders?: ReadonlyArray<string>;
+    /** Response headers exposed to client scripts via `Access-Control-Expose-Headers`. */
+    readonly exposedHeaders?: ReadonlyArray<string>;
+    /** Whether credentialed requests are allowed. When `true`, the origin is never wildcarded. */
+    readonly credentials?: boolean;
+    /** Preflight cache lifetime in seconds (`Access-Control-Max-Age`). Defaults to 600. */
+    readonly maxAgeSeconds?: number;
+}
+/**
+ * A CorsOptions normalized into the exact strings the response builders emit,
+ * so the per-request hot path does no defaulting or array joining.
+ */
+export type ResolvedCorsPolicy = {
+    readonly matchOrigin: (origin: string) => boolean;
+    readonly allowsAnyOrigin: boolean;
+    /** Pre-joined `Access-Control-Allow-Methods` value emitted in preflight responses. */
+    readonly allowedMethodsHeader: string;
+    /** Uppercased method names, for O(1) validation of the preflight's requested method. */
+    readonly allowedMethodSet: ReadonlySet<string>;
+    /** Pre-joined `Access-Control-Allow-Headers` value emitted in preflight responses. */
+    readonly allowedHeadersHeader: string;
+    /** Lowercased header names, for O(1) validation of the preflight's requested headers. */
+    readonly allowedHeaderSet: ReadonlySet<string>;
+    readonly exposedHeadersHeader: string | null;
+    readonly credentials: boolean;
+    readonly maxAgeSeconds: number;
+};
+/**
+ * Canonicalize an origin string to its `scheme://host[:port]` tuple. Returns
+ * `null` for the literal `"null"`, empty input, or anything the URL parser
+ * rejects — those must never match an allowlist entry. Default ports are
+ * elided by the URL parser, so `https://x:443` and `https://x` compare equal.
+ */
+export declare function canonicalizeOrigin(value: string): string | null;
+/**
+ * Resolve a `CorsOptions` (already validated by {@link validateCorsOptions})
+ * into the precomputed policy used per request. When `auth` is configured the
+ * caller passes `requireAuthorizationHeader: true` so `Authorization` is
+ * always advertised in `Access-Control-Allow-Headers`.
+ */
+export declare function resolveCorsPolicy(options: CorsOptions, requireAuthorizationHeader?: boolean): ResolvedCorsPolicy;
+/**
+ * Whether a request's `Origin` header is permitted by the policy. The literal
+ * `Origin: null` (sandboxed iframe, `file://`, some redirects) is rejected
+ * unconditionally — even under a wildcard policy — so a sandboxed page can
+ * never be treated as an allowed origin.
+ */
+export declare function isOriginAllowed(policy: ResolvedCorsPolicy, origin: string | null): boolean;
+/** True when the request is a CORS preflight (an `OPTIONS` with the request-method hint). */
+export declare function isPreflightRequest(request: Request): boolean;
+/**
+ * Build the preflight (`OPTIONS`) response. Always returns a bounded 204 so
+ * the path is cheap and stateless — it emits `Access-Control-*` headers only
+ * when the origin is allowed AND the requested method and headers are within
+ * policy; otherwise the 204 carries no CORS headers and the browser blocks the
+ * real request. `Vary` covers all three request dimensions a shared cache
+ * could key on, and `Cache-Control: no-store` keeps a proxy from reusing one
+ * origin's decision for another.
+ */
+export declare function buildPreflightResponse(policy: ResolvedCorsPolicy, request: Request): Response;
+/**
+ * Add CORS response headers to an actual (non-preflight) response when the
+ * request carried an allowed `Origin`. Mutates and returns the same response.
+ * Always sets `Vary: Origin` (appending to any existing value) so caches do
+ * not serve one origin's headers to another.
+ */
+export declare function decorateResponseWithCors(policy: ResolvedCorsPolicy, request: Request, response: Response): Response;
+/**
+ * Validate a `CorsOptions` at `serve()` time so misconfigurations fail before
+ * the port binds. Throws `Error` on:
+ *   - `credentials: true` combined with a wildcard origin (illegal per spec);
+ *   - a wildcard origin paired with an `Authorization` allowed-header (lets any
+ *     origin read responses to bearer-token requests — almost never intended).
+ *
+ * `authConfigured` must mirror what `serve()` passes as `requireAuthorizationHeader`
+ * to {@link resolveCorsPolicy}: when `auth` is set, `Authorization` is auto-added
+ * to the effective allowed-headers, so the wildcard + `Authorization` check has to
+ * account for that even when the operator did not list it explicitly. Validating
+ * against `options.allowedHeaders` alone would let `cors: { allowedOrigins: ['*'],
+ * allowedHeaders: ['Content-Type'] }` pass under `auth` and then resolve to a policy
+ * that allows bearer tokens under a wildcard origin.
+ */
+export declare function validateCorsOptions(options: CorsOptions, authConfigured?: boolean): void;

package/dist/server/runtime/cors.js

@@ -0,0 +1,123 @@
+const DEFAULT_ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"], DEFAULT_ALLOWED_HEADERS = ["Authorization", "Content-Type"], DEFAULT_MAX_AGE_SECONDS = 600, WILDCARD_ORIGIN = "*";
+export function canonicalizeOrigin(value) {
+  const trimmed = value.trim();
+  if (trimmed === "" || trimmed === "null")
+    return null;
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.origin === "null" ? null : parsed.origin;
+  } catch {
+    return null;
+  }
+}
+function buildOriginMatcher(allowedOrigins) {
+  if (typeof allowedOrigins === "function")
+    return { match: allowedOrigins, allowsAny: !1 };
+  const list = allowedOrigins ?? [];
+  if (list.length === 1 && list[0] === WILDCARD_ORIGIN)
+    return { match: () => !0, allowsAny: !0 };
+  const canonical = new Set;
+  for (const entry of list) {
+    const normalized = canonicalizeOrigin(entry);
+    if (normalized !== null)
+      canonical.add(normalized);
+  }
+  return {
+    match: (origin) => {
+      const normalized = canonicalizeOrigin(origin);
+      return normalized !== null && canonical.has(normalized);
+    },
+    allowsAny: !1
+  };
+}
+export function resolveCorsPolicy(options, requireAuthorizationHeader = !1) {
+  const { match, allowsAny } = buildOriginMatcher(options.allowedOrigins), methods = options.allowedMethods ?? DEFAULT_ALLOWED_METHODS, headerList = [...options.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS];
+  if (requireAuthorizationHeader && !headerList.some((header) => header.toLowerCase() === "authorization"))
+    headerList.push("Authorization");
+  const allowedHeaderSet = new Set(headerList.map((header) => header.toLowerCase())), allowedMethodSet = new Set(methods.map((method) => method.toUpperCase())), exposed = options.exposedHeaders ?? [];
+  return {
+    matchOrigin: match,
+    allowsAnyOrigin: allowsAny,
+    allowedMethodsHeader: methods.join(", "),
+    allowedMethodSet,
+    allowedHeadersHeader: headerList.join(", "),
+    allowedHeaderSet,
+    exposedHeadersHeader: exposed.length > 0 ? exposed.join(", ") : null,
+    credentials: options.credentials === !0,
+    maxAgeSeconds: options.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS
+  };
+}
+export function isOriginAllowed(policy, origin) {
+  if (origin === null || origin.trim() === "null" || origin.trim() === "")
+    return !1;
+  return policy.matchOrigin(origin);
+}
+function allowOriginValue(policy, requestOrigin) {
+  if (policy.allowsAnyOrigin && !policy.credentials)
+    return WILDCARD_ORIGIN;
+  return requestOrigin;
+}
+export function isPreflightRequest(request) {
+  return request.method === "OPTIONS" && request.headers.get("access-control-request-method") !== null;
+}
+export function buildPreflightResponse(policy, request) {
+  const baseHeaders = {
+    Vary: "Origin, Access-Control-Request-Method, Access-Control-Request-Headers",
+    "Cache-Control": "no-store"
+  }, denied = new Response(null, { status: 204, headers: baseHeaders }), origin = request.headers.get("origin");
+  if (origin === null || !isOriginAllowed(policy, origin))
+    return denied;
+  const requestedMethod = request.headers.get("access-control-request-method");
+  if (requestedMethod === null || !policy.allowedMethodSet.has(requestedMethod.toUpperCase()))
+    return denied;
+  if (!parseRequestedHeaders(request.headers.get("access-control-request-headers")).every((header) => policy.allowedHeaderSet.has(header)))
+    return denied;
+  const headers = {
+    ...baseHeaders,
+    "Access-Control-Allow-Origin": allowOriginValue(policy, origin),
+    "Access-Control-Allow-Methods": policy.allowedMethodsHeader,
+    "Access-Control-Allow-Headers": policy.allowedHeadersHeader,
+    "Access-Control-Max-Age": String(policy.maxAgeSeconds)
+  };
+  if (policy.credentials)
+    headers["Access-Control-Allow-Credentials"] = "true";
+  return new Response(null, { status: 204, headers });
+}
+export function decorateResponseWithCors(policy, request, response) {
+  const origin = request.headers.get("origin");
+  if (origin === null || !isOriginAllowed(policy, origin))
+    return response;
+  appendVary(response.headers, "Origin");
+  response.headers.set("Access-Control-Allow-Origin", allowOriginValue(policy, origin));
+  if (policy.credentials)
+    response.headers.set("Access-Control-Allow-Credentials", "true");
+  if (policy.exposedHeadersHeader !== null)
+    response.headers.set("Access-Control-Expose-Headers", policy.exposedHeadersHeader);
+  return response;
+}
+function parseRequestedHeaders(value) {
+  if (value === null || value.trim() === "")
+    return [];
+  return value.split(",").map((header) => header.trim().toLowerCase()).filter((header) => header !== "");
+}
+function appendVary(headers, token) {
+  const existing = headers.get("Vary");
+  if (existing === null || existing.trim() === "") {
+    headers.set("Vary", token);
+    return;
+  }
+  const tokens = existing.split(",").map((entry) => entry.trim().toLowerCase());
+  if (tokens.includes(token.toLowerCase()) || tokens.includes("*"))
+    return;
+  headers.set("Vary", `${existing}, ${token}`);
+}
+export function validateCorsOptions(options, authConfigured = !1) {
+  const allowed = options.allowedOrigins;
+  if (!(Array.isArray(allowed) && allowed.length === 1 && allowed[0] === WILDCARD_ORIGIN))
+    return;
+  if (options.credentials === !0)
+    throw Error('serve({ cors }): allowedOrigins ["*"] cannot be combined with credentials: true \u2014 ' + "a wildcard origin is illegal for credentialed CORS. List explicit origins instead.");
+  const headers = options.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS;
+  if (authConfigured || headers.some((header) => header.toLowerCase() === "authorization"))
+    throw Error('serve({ cors }): allowedOrigins ["*"] combined with an Authorization allowed-header lets any web origin send bearer tokens and read the response. List explicit origins, or drop Authorization from allowedHeaders if the wildcard is truly intended for a public API. (When serve({ auth }) is configured, Authorization is always an allowed header, so a wildcard origin is rejected regardless of allowedHeaders.)');
+}

package/dist/server/runtime/event-broadcasting.d.ts

@@ -0,0 +1,71 @@
+import type { Engine } from '../../core/engine.ts';
+import type { ServerContext } from './context.ts';
+/**
+ * Result of wiring up engine-to-WebSocket event broadcasting.
+ *
+ * - `dispose`: removes all listeners (abort signal). Called on server shutdown.
+ * - `cleanupWorkflow`: drops the per-workflow sequence state for the given
+ *   workflow id. Should be invoked when a workflow reaches a terminal state
+ *   so the bookkeeping maps do not grow unbounded over the server's lifetime.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import { wireEventBroadcasting, type EventBroadcastingHandle } from '@lostgradient/weft/server';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * const bunServer = Bun.serve({ fetch: () => new Response('ok') });
+ * const handle: EventBroadcastingHandle = wireEventBroadcasting(engine, bunServer);
+ * // Later, on shutdown:
+ * handle.dispose();
+ * ```
+ */
+export interface EventBroadcastingHandle {
+    dispose: () => void;
+    cleanupWorkflow: (workflowId: string) => void;
+}
+/**
+ * Extract a `workflowId` from a DOM `Event` when the concrete event carries
+ * one. All workflow, activity, token, signal, attribute, and update events
+ * in `core/events.ts` expose a `workflowId: string` field, but the `Event`
+ * base type does not know about it — so a runtime structural check narrows
+ * the value before we use it to key bookkeeping maps. Returns `undefined`
+ * for events without a string `workflowId` property.
+ */
+export declare function getWorkflowIdFromEvent(event: Event): string | undefined;
+export declare function registerWorkflowEventLifecycle(engine: Engine, context: ServerContext, broadcastingHandle: EventBroadcastingHandle): () => void;
+/**
+ * Attach event listeners to the engine that broadcast events via WebSocket
+ * and persist each event to storage so `GET /v1/workflows/:id/events` returns data.
+ * Returns a handle exposing a cleanup function and a per-workflow eviction hook.
+ *
+ * @param engine - The engine whose events will be listened to.
+ * @param server - The Bun server used to `server.publish()` WebSocket messages.
+ * @param options.publishTokenMessage - Optional override for token-event delivery.
+ *   When provided, this callback is called instead of `server.publish()` for
+ *   token messages, enabling per-workflow stream sockets to be used in
+ *   place of the default pub/sub channel. Leave unset unless you manage stream
+ *   sockets separately (as `serve()` does internally).
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import { wireEventBroadcasting } from '@lostgradient/weft/server';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * const bunServer = Bun.serve({ fetch: () => new Response('ok') });
+ * const handle = wireEventBroadcasting(engine, bunServer);
+ *
+ * // Wire a terminal-event listener to clean up per-workflow bookkeeping.
+ * engine.addEventListener('workflow:completed', (e) => {
+ *   const workflowId = (e as { workflowId?: string }).workflowId;
+ *   if (workflowId) handle.cleanupWorkflow(workflowId);
+ * });
+ *
+ * // On server shutdown, remove all event listeners.
+ * handle.dispose();
+ * ```
+ */
+export declare function wireEventBroadcasting(engine: Engine, server: ReturnType<typeof Bun.serve>, options?: {
+    publishTokenMessage?: (workflowId: string, sequence: number, message: string) => void;
+}): EventBroadcastingHandle;

package/dist/server/runtime/event-broadcasting.js

@@ -0,0 +1,205 @@
+import { encode } from "../../core/codec.js";
+import {
+  ActivityCompletedEvent,
+  ActivityFailedEvent,
+  ActivityStartedEvent,
+  AttributesChangedEvent,
+  SignalDeliveredEvent,
+  SignalReceivedEvent,
+  UpdateCompletedEvent,
+  UpdateReceivedEvent,
+  WorkflowCancelledEvent,
+  WorkflowCompletedEvent,
+  WorkflowFailedEvent,
+  WorkflowStartedEvent,
+  WorkflowTimedOutEvent
+} from "../../core/events.js";
+import { KEYS } from "../../storage/interface.js";
+import { claimNextSequence } from "../runtime-helpers.js";
+import { cancelTask } from "./task-dispatch.js";
+import { withRetry } from "./websocket-worker.js";
+const TOKEN_EVENT_TYPE = "stream:token";
+function workflowChannelPath(workflowId, connectionType) {
+  return `/v1/workflows/${encodeURIComponent(workflowId)}/${connectionType}`;
+}
+function serializeEvent(event) {
+  const data = {};
+  for (const [key, value] of Object.entries(event)) {
+    if (key === "type")
+      continue;
+    if (value instanceof Error)
+      data[key] = value.message;
+    else
+      data[key] = value;
+  }
+  const message = {
+    type: event.type,
+    timestamp: Date.now(),
+    data
+  };
+  return JSON.stringify(message);
+}
+export function getWorkflowIdFromEvent(event) {
+  if (!("workflowId" in event))
+    return;
+  const candidate = event.workflowId;
+  return typeof candidate === "string" ? candidate : void 0;
+}
+export function registerWorkflowEventLifecycle(engine, context, broadcastingHandle) {
+  const affinityController = new AbortController, terminalEventTypes = [
+    WorkflowCompletedEvent.type,
+    WorkflowFailedEvent.type,
+    WorkflowCancelledEvent.type,
+    WorkflowTimedOutEvent.type
+  ];
+  for (const eventType of terminalEventTypes)
+    engine.addEventListener(eventType, (event) => {
+      const workflowId = getWorkflowIdFromEvent(event);
+      if (workflowId) {
+        context.workerAffinity.delete(workflowId);
+        broadcastingHandle.cleanupWorkflow(workflowId);
+      }
+    }, { signal: affinityController.signal });
+  const cancelPropagationController = new AbortController;
+  engine.addEventListener(WorkflowCancelledEvent.type, (event) => {
+    const workflowId = getWorkflowIdFromEvent(event);
+    if (!workflowId)
+      return;
+    const operationIds = context.workflowOperations.get(workflowId);
+    if (!operationIds || operationIds.size === 0)
+      return;
+    for (const operationId of operationIds) {
+      cancelTask(context, operationId);
+      context.operationToWorkflow.delete(operationId);
+    }
+    context.workflowOperations.delete(workflowId);
+  }, { signal: cancelPropagationController.signal });
+  return () => {
+    affinityController.abort();
+    cancelPropagationController.abort();
+  };
+}
+export function wireEventBroadcasting(engine, server, options) {
+  const controller = new AbortController, { signal } = controller, sequenceCounters = new Map, sequenceInitPromises = new Map, tokenSequenceCounters = new Map, tokenSequenceInitPromises = new Map, sequenceChains = new Map;
+  function ensureSequenceInitialized(workflowId) {
+    const existing = sequenceInitPromises.get(workflowId);
+    if (existing)
+      return existing;
+    const promise = (async () => {
+      const prefix = KEYS.eventPrefix(workflowId);
+      let highestSequence = -1;
+      for await (const [key] of engine.storage.scan(prefix, { reverse: !0, limit: 1 })) {
+        const parts = key.split(":"), sequencePart = parts[parts.length - 1];
+        if (sequencePart !== void 0)
+          highestSequence = parseInt(sequencePart, 10);
+      }
+      sequenceCounters.set(workflowId, highestSequence + 1);
+    })().catch((error) => {
+      sequenceInitPromises.delete(workflowId);
+      throw error;
+    });
+    sequenceInitPromises.set(workflowId, promise);
+    return promise;
+  }
+  function ensureTokenSequenceInitialized(workflowId) {
+    const existing = tokenSequenceInitPromises.get(workflowId);
+    if (existing)
+      return existing;
+    const promise = (async () => {
+      const prefix = KEYS.streamChunkPrefix(workflowId, "tokens");
+      let highestSequence = -1;
+      for await (const [key] of engine.storage.scan(prefix, { reverse: !0, limit: 1 })) {
+        const sequenceText = key.slice(prefix.length), parsedSequence = Number.parseInt(sequenceText, 10);
+        if (Number.isSafeInteger(parsedSequence))
+          highestSequence = parsedSequence;
+      }
+      tokenSequenceCounters.set(workflowId, highestSequence + 1);
+    })().catch((error) => {
+      tokenSequenceInitPromises.delete(workflowId);
+      throw error;
+    });
+    tokenSequenceInitPromises.set(workflowId, promise);
+    return promise;
+  }
+  async function persistAndPublishEvent(workflowId, eventType, message) {
+    await ensureSequenceInitialized(workflowId);
+    const parsed = JSON.parse(message), sequence = claimNextSequence(sequenceCounters, workflowId), storageKey = KEYS.event(workflowId, sequence), encoded = encode(parsed);
+    await withRetry(async () => engine.storage.put(storageKey, encoded), `persist event "${eventType}" for workflow "${workflowId}"`);
+    const watchChannel = workflowChannelPath(workflowId, "watch");
+    server.publish(watchChannel, message);
+    if (eventType === TOKEN_EVENT_TYPE) {
+      const tokenPayload = {
+        workflowId: typeof parsed.data.workflowId === "string" ? parsed.data.workflowId : workflowId,
+        token: typeof parsed.data.token === "string" ? parsed.data.token : "",
+        model: typeof parsed.data.model === "string" ? parsed.data.model : ""
+      };
+      await ensureTokenSequenceInitialized(workflowId);
+      const tokenSequence = claimNextSequence(tokenSequenceCounters, workflowId);
+      await withRetry(async () => engine.storage.put(KEYS.streamChunk(workflowId, "tokens", tokenSequence), encode(tokenPayload)), `persist token stream chunk for workflow "${workflowId}"`);
+      const streamMessage = JSON.stringify({
+        ...parsed,
+        sequence: tokenSequence,
+        data: tokenPayload
+      });
+      if (options?.publishTokenMessage)
+        options.publishTokenMessage(workflowId, tokenSequence, streamMessage);
+      else {
+        const streamChannel = workflowChannelPath(workflowId, "stream");
+        server.publish(streamChannel, streamMessage);
+      }
+    }
+  }
+  const eventTypes = [
+    WorkflowStartedEvent.type,
+    WorkflowCompletedEvent.type,
+    WorkflowFailedEvent.type,
+    WorkflowCancelledEvent.type,
+    WorkflowTimedOutEvent.type,
+    ActivityStartedEvent.type,
+    ActivityCompletedEvent.type,
+    ActivityFailedEvent.type,
+    TOKEN_EVENT_TYPE,
+    SignalReceivedEvent.type,
+    SignalDeliveredEvent.type,
+    AttributesChangedEvent.type,
+    UpdateReceivedEvent.type,
+    UpdateCompletedEvent.type
+  ];
+  for (const eventType of eventTypes)
+    engine.addEventListener(eventType, (event) => {
+      const workflowId = getWorkflowIdFromEvent(event);
+      if (workflowId === void 0)
+        return;
+      const message = serializeEvent(event);
+      if (message === null)
+        return;
+      const nextChain = (sequenceChains.get(workflowId) ?? Promise.resolve()).then(() => persistAndPublishEvent(workflowId, eventType, message)).catch((error) => {
+        console.error(`[weft] Failed to persist event "${eventType}" for workflow "${workflowId}":`, error);
+      });
+      sequenceChains.set(workflowId, nextChain);
+    }, { signal });
+  function cleanupWorkflow(workflowId) {
+    const pendingChain = sequenceChains.get(workflowId), drop = () => {
+      sequenceCounters.delete(workflowId);
+      sequenceInitPromises.delete(workflowId);
+      tokenSequenceCounters.delete(workflowId);
+      tokenSequenceInitPromises.delete(workflowId);
+      sequenceChains.delete(workflowId);
+    };
+    if (!pendingChain) {
+      drop();
+      return;
+    }
+    pendingChain.finally(() => {
+      if (sequenceChains.get(workflowId) !== pendingChain) {
+        cleanupWorkflow(workflowId);
+        return;
+      }
+      drop();
+    });
+  }
+  return {
+    dispose: () => controller.abort(),
+    cleanupWorkflow
+  };
+}