@lostgradient/weft 0.2.0

package/dist/server/runtime/request-gate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Request admission gate: authentication then per-key rate limiting.
+ *
+ * Extracted from the server fetch dispatcher so the dispatch path stays small.
+ * `gateRequest` runs the two short-circuiting steps a request must pass before
+ * any handler sees it:
+ *   1. **Authentication** — produces the auth context, a 401, or a public-path
+ *      bypass. Auth-event auditing happens inside the authenticator itself.
+ *   2. **Rate limiting** — throttles per principal-or-IP key, returning 429 with
+ *      `Retry-After` once a key exceeds its window budget. Public-path requests
+ *      and servers without a `rateLimit` are never throttled. Failed-auth
+ *      requests are also checked against the IP-keyed limiter so that
+ *      credential-stuffing floods are shed before returning the 401.
+ *
+ * @internal
+ */
+import type { AuthContext } from '../authentication.ts';
+import type { ServerContext } from './context.ts';
+/**
+ * Outcome of {@link authenticateRequest}: the resolved auth context (absent for
+ * public-path bypass and unauthenticated servers), a short-circuit `response`
+ * (a 401 on rejection, else `null`), and whether the request hit a public path.
+ */
+export type AuthenticationOutcome = {
+    authContext?: AuthContext;
+    response: Response | null;
+    /**
+     * `true` when the request matched a configured public path and bypassed
+     * authentication. The rate-limit step uses this to exempt health, metrics,
+     * and discovery probes from per-key throttling.
+     */
+    publicBypass: boolean;
+};
+export declare function authenticateRequest(context: ServerContext, request: Request): Promise<AuthenticationOutcome>;
+/**
+ * Run the request gate: authenticate, then rate-limit. Returns a short-circuit
+ * `response` (401 or 429) when either step rejects, otherwise `response: null`
+ * with the resolved authentication outcome.
+ *
+ * Failed-auth requests are checked against the IP-keyed limiter before the 401
+ * is returned so that credential-stuffing floods consume the rate-limit budget
+ * and are eventually shed with a 429 instead of burning CPU indefinitely.
+ *
+ * `originalRequest` (when provided) is used solely for IP lookup in
+ * `server.requestIP()`. Certain callers rewrite the request URL (e.g. to strip
+ * an `/api` prefix) via `new Request(url, request)`, which loses Bun's internal
+ * socket handle — so `requestIP` on the rewritten copy returns `null`. Passing
+ * the pre-rewrite request here ensures IP-based rate limiting stays functional
+ * on the `/api/…` prefix path.
+ */
+export declare function gateRequest(server: ReturnType<typeof Bun.serve>, context: ServerContext, request: Request, originalRequest?: Request): Promise<{
+    response: Response | null;
+    authentication: AuthenticationOutcome;
+}>;

package/dist/server/runtime/request-gate.js

@@ -0,0 +1,71 @@
+import { DEFAULT_PUBLIC_PATHS, normalizeRequestPathname } from "../authentication/types.js";
+const DEFAULT_PUBLIC_PATH_SET = new Set(DEFAULT_PUBLIC_PATHS);
+export async function authenticateRequest(context, request) {
+  if (!context.authenticatorPromise)
+    return { response: null, publicBypass: DEFAULT_PUBLIC_PATH_SET.has(normalizeRequestPathname(request)) };
+  const authResult = await (await context.authenticatorPromise)(request);
+  if (authResult.authenticated) {
+    if (authResult.method === "public")
+      return { response: null, publicBypass: !0 };
+    return {
+      authContext: {
+        method: authResult.method,
+        ...authResult.claims !== void 0 ? { claims: authResult.claims } : {},
+        ...authResult.principal !== void 0 ? { principal: authResult.principal } : {}
+      },
+      response: null,
+      publicBypass: !1
+    };
+  }
+  return {
+    response: new Response(JSON.stringify({ error: authResult.error }), {
+      status: 401,
+      headers: {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": "Bearer"
+      }
+    }),
+    publicBypass: !1
+  };
+}
+function subjectFromAuthContext(authContext) {
+  if (authContext?.principal?.subject !== void 0)
+    return authContext.principal.subject;
+  const sub = authContext?.claims?.sub;
+  return typeof sub === "string" ? sub : void 0;
+}
+function rateLimitKeyForRequest(server, request, authContext) {
+  const subject = subjectFromAuthContext(authContext);
+  if (subject !== void 0)
+    return `principal:${subject}`;
+  const address = server.requestIP(request)?.address;
+  if (address !== void 0 && address.length > 0)
+    return `ip:${address}`;
+  return "unidentified";
+}
+function enforceRateLimit(context, server, request, authContext, publicBypass) {
+  if (context.rateLimiter === null || publicBypass)
+    return null;
+  const decision = context.rateLimiter.check(rateLimitKeyForRequest(server, request, authContext));
+  if (decision.allowed)
+    return null;
+  return new Response(JSON.stringify({ error: "Too Many Requests" }), {
+    status: 429,
+    headers: {
+      "Content-Type": "application/json",
+      "Retry-After": String(decision.retryAfterSeconds),
+      "X-RateLimit-Limit": String(decision.limit),
+      "X-RateLimit-Remaining": String(decision.remaining)
+    }
+  });
+}
+export async function gateRequest(server, context, request, originalRequest = request) {
+  const authentication = await authenticateRequest(context, request);
+  if (authentication.response !== null) {
+    const failedAuthThrottle = enforceRateLimit(context, server, originalRequest, void 0, !1);
+    if (failedAuthThrottle !== null)
+      return { response: failedAuthThrottle, authentication };
+    return { response: authentication.response, authentication };
+  }
+  return { response: enforceRateLimit(context, server, originalRequest, authentication.authContext, authentication.publicBypass), authentication };
+}

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

@@ -0,0 +1,10 @@
+import type { ServerContext } from './context.ts';
+export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/** Send a shutdown message to a specific worker and wait for it to disconnect. */
+export declare function shutdownWorker(context: ServerContext, workerId: string, shutdownOptions?: {
+    timeoutMs?: number;
+}): Promise<boolean>;
+/** Send a shutdown message to all connected workers and wait for them to disconnect. */
+export declare function shutdownAllWorkers(context: ServerContext, shutdownOptions?: {
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/server/runtime/shutdown.js

@@ -0,0 +1,18 @@
+export const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+export async function shutdownWorker(context, workerId, shutdownOptions) {
+  const ws = context.workerSockets.get(workerId);
+  if (!ws)
+    return !1;
+  ws.send(JSON.stringify({ type: "shutdown" }));
+  const timeout = shutdownOptions?.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS, deadline = Date.now() + timeout;
+  while (context.workerSockets.has(workerId)) {
+    if (Date.now() >= deadline)
+      return !0;
+    await Bun.sleep(50);
+  }
+  return !0;
+}
+export async function shutdownAllWorkers(context, shutdownOptions) {
+  const workerIds = [...context.workerSockets.keys()];
+  await Promise.all(workerIds.map((id) => shutdownWorker(context, id, shutdownOptions)));
+}

package/dist/server/runtime/stop-server.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from 'bun';
+import type { WebSocketData } from '../json-rpc-websocket-runtime.ts';
+export declare function stopBunServerForShutdown(server: Server<WebSocketData>): Promise<void>;

package/dist/server/runtime/stop-server.js

@@ -0,0 +1,19 @@
+const SERVER_FORCE_STOP_SETTLE_TIMEOUT_MS = 250;
+export async function stopBunServerForShutdown(server) {
+  let timeout;
+  const stopPromise = server.stop(!0);
+  stopPromise.catch((error) => {
+    console.error("[weft] Bun server stop failed:", error);
+  });
+  try {
+    await Promise.race([
+      stopPromise,
+      new Promise((resolve) => {
+        timeout = setTimeout(resolve, SERVER_FORCE_STOP_SETTLE_TIMEOUT_MS);
+      })
+    ]);
+  } finally {
+    if (timeout !== void 0)
+      clearTimeout(timeout);
+  }
+}

package/dist/server/runtime/task-dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { ServeOptions, TaskDispatch } from '../index.ts';
+import type { ServerContext } from './context.ts';
+/** Schedule a delayed dispatch, tracking the timer for cleanup on shutdown. */
+export declare function scheduleDelayedDispatch(context: ServerContext, options: ServeOptions, task: TaskDispatch, delay: number): void;
+export declare function resolveTaskPriority(_context: ServerContext, _options: ServeOptions, task: TaskDispatch): number | undefined;
+export declare function dispatchTaskImpl(context: ServerContext, options: ServeOptions, task: TaskDispatch): Promise<boolean>;
+/** Send a cancel message to the worker handling a specific operation. */
+export declare function cancelTask(context: ServerContext, operationId: string): boolean;

package/dist/server/runtime/task-dispatch.js

@@ -0,0 +1,157 @@
+import { evictOldestAffinityEntries } from "../runtime-helpers.js";
+import { markQueued, readQueuedRecord, transitionQueuedToInflight } from "../task-state.js";
+import {
+  recordTaskBacklogMetric,
+  recordTaskQueueLatencyMetric,
+  recordWorkerCapacitySaturationMetric
+} from "./task-metrics.js";
+const MAX_AFFINITY_ENTRIES = 1e4, DEFAULT_VISIBILITY_TIMEOUT = 30000, MIN_VISIBILITY_TIMEOUT = 10, MAX_VISIBILITY_TIMEOUT = 3600000;
+function clampVisibilityTimeout(value) {
+  if (value === void 0 || !Number.isFinite(value))
+    return DEFAULT_VISIBILITY_TIMEOUT;
+  return Math.min(Math.max(value, MIN_VISIBILITY_TIMEOUT), MAX_VISIBILITY_TIMEOUT);
+}
+export function scheduleDelayedDispatch(context, options, task, delay) {
+  const timer = setTimeout(() => {
+    context.pendingTimers.delete(timer);
+    dispatchTaskImpl(context, options, task).catch((err) => console.error(`[weft] Delayed redispatch failed for "${task.operationId}":`, err));
+  }, delay);
+  context.pendingTimers.add(timer);
+}
+export function resolveTaskPriority(_context, _options, task) {
+  if (task.priority !== void 0)
+    return task.priority;
+  return;
+}
+function validateTaskEnvelope(context, task) {
+  return !context.registry.isAssigned(task.operationId) && !context.taskQueue.isTracked(task.operationId);
+}
+function buildRoutingOptions(context, task, queue) {
+  const routingOptions = { queue };
+  if (task.sticky && task.workflowId) {
+    const stickyWorkerId = context.workerAffinity.get(task.workflowId);
+    if (stickyWorkerId !== void 0)
+      routingOptions.sticky = stickyWorkerId;
+  }
+  if (task.fairShareKey !== void 0)
+    routingOptions.fairShareKey = task.fairShareKey;
+  if (context.pendingWorkerRequeues.size > 0)
+    routingOptions.excludeWorkerIds = new Set(context.pendingWorkerRequeues.keys());
+  return routingOptions;
+}
+function recordDispatchOutcome(context, task, workerId) {
+  if (!task.workflowId)
+    return;
+  context.workerAffinity.set(task.workflowId, workerId);
+  evictOldestAffinityEntries(context.workerAffinity, MAX_AFFINITY_ENTRIES);
+  let operationIds = context.workflowOperations.get(task.workflowId);
+  if (!operationIds) {
+    operationIds = new Set;
+    context.workflowOperations.set(task.workflowId, operationIds);
+  }
+  operationIds.add(task.operationId);
+  context.operationToWorkflow.set(task.operationId, task.workflowId);
+}
+async function selectAndReserveWorker(context, options, task, queue, visibilityTimeout) {
+  const routingOptions = buildRoutingOptions(context, task, queue), worker = context.registry.findWorker(task.activityName, routingOptions);
+  if (!worker)
+    return !1;
+  const ws = context.workerSockets.get(worker.id);
+  if (!ws)
+    return !1;
+  const now = Date.now(), existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId);
+  context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey);
+  const deadline = now + visibilityTimeout;
+  context.deadlineTracker.add({ operationId: task.operationId, deadline });
+  const inflightRecord = {
+    operationId: task.operationId,
+    workerId: worker.id,
+    deadline,
+    activityName: task.activityName,
+    queue,
+    input: task.input,
+    attempt: task.attempt ?? 1,
+    visibilityTimeout,
+    retryPolicy: task.retryPolicy,
+    workflowId: task.workflowId
+  }, normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord, {
+    queuedRecord: existingQueuedRecord,
+    now
+  });
+  ws.send(JSON.stringify({
+    type: "task",
+    operationId: task.operationId,
+    activityName: task.activityName,
+    input: task.input === void 0 ? null : task.input,
+    attempt: task.attempt ?? 1,
+    ...task.headers ? { headers: task.headers } : {}
+  }));
+  recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);
+  recordWorkerCapacitySaturationMetric(context.metricsCollector, context.registry);
+  recordDispatchOutcome(context, task, worker.id);
+  return !0;
+}
+function mergeQueuedRecordLifecycle(fresh, existing) {
+  return {
+    ...fresh,
+    firstQueuedAt: existing?.firstQueuedAt ?? fresh.queuedAt,
+    lastQueuedAt: fresh.queuedAt,
+    lastDispatchedAt: existing?.lastDispatchedAt,
+    startedAt: existing?.startedAt,
+    retryCount: existing?.retryCount ?? fresh.retryCount,
+    requeueCount: existing?.requeueCount ?? fresh.requeueCount,
+    lastRequeueReason: existing?.lastRequeueReason
+  };
+}
+async function enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority) {
+  const attempt = task.attempt ?? 1, freshRecord = {
+    operationId: task.operationId,
+    activityName: task.activityName,
+    input: task.input,
+    queue,
+    attempt,
+    visibilityTimeout,
+    retryPolicy: task.retryPolicy,
+    queuedAt: Date.now(),
+    workflowId: task.workflowId,
+    retryCount: Math.max(0, attempt - 1),
+    requeueCount: 0
+  }, existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId), normalizedQueuedRecord = await markQueued(options.engine.storage, mergeQueuedRecordLifecycle(freshRecord, existingQueuedRecord)), enqueued = context.taskQueue.enqueue(queue, {
+    operationId: task.operationId,
+    activityName: task.activityName,
+    input: task.input,
+    attempt,
+    retryPolicy: task.retryPolicy,
+    visibilityTimeout,
+    workflowId: task.workflowId,
+    firstQueuedAt: normalizedQueuedRecord.firstQueuedAt,
+    lastQueuedAt: normalizedQueuedRecord.lastQueuedAt,
+    lastDispatchedAt: normalizedQueuedRecord.lastDispatchedAt,
+    startedAt: normalizedQueuedRecord.startedAt,
+    retryCount: normalizedQueuedRecord.retryCount,
+    requeueCount: normalizedQueuedRecord.requeueCount,
+    lastRequeueReason: normalizedQueuedRecord.lastRequeueReason,
+    ...task.headers ? { headers: task.headers } : {},
+    ...resolvedPriority !== void 0 ? { priority: resolvedPriority } : {}
+  });
+  recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
+  return enqueued;
+}
+export async function dispatchTaskImpl(context, options, task) {
+  const queue = task.queue ?? "default", visibilityTimeout = clampVisibilityTimeout(task.visibilityTimeout), resolvedPriority = resolveTaskPriority(context, options, task);
+  if (!validateTaskEnvelope(context, task))
+    return !1;
+  if (await selectAndReserveWorker(context, options, task, queue, visibilityTimeout))
+    return !0;
+  return enqueueTaskForLongPoll(context, options, task, queue, visibilityTimeout, resolvedPriority);
+}
+export function cancelTask(context, operationId) {
+  const task = context.registry.getTask(operationId);
+  if (!task)
+    return !1;
+  const ws = context.workerSockets.get(task.workerId);
+  if (!ws)
+    return !1;
+  ws.send(JSON.stringify({ type: "cancel", operationId }));
+  return !0;
+}

package/dist/server/runtime/task-metrics.d.ts

@@ -0,0 +1,12 @@
+import { type MetricsCollector } from '../../observability/metrics.ts';
+import type { WorkerRegistry } from '../../worker/registry.ts';
+import type { TaskQueue } from '../task-queue.ts';
+import { type InflightRecord, type ResolvedRecord } from '../task-state.ts';
+export declare function recordTaskBacklogMetric(metricsCollector: MetricsCollector | undefined, taskQueue: TaskQueue): void;
+export declare function recordTaskQueueLatencyMetric(metricsCollector: MetricsCollector | undefined, record: InflightRecord | ResolvedRecord): void;
+export declare function recordTaskExecutionLatencyMetric(metricsCollector: MetricsCollector | undefined, record: InflightRecord | ResolvedRecord, completedAt: number): void;
+export declare function recordTaskRetryMetric(metricsCollector: MetricsCollector | undefined, count?: number): void;
+export declare function recordTaskRequeueMetric(metricsCollector: MetricsCollector | undefined, count?: number): void;
+export declare function isTaskHeartbeatStaleForMetrics(record: InflightRecord, currentTime: number, staleAfterMs?: number): boolean;
+export declare function recordTaskStaleHeartbeatMetric(metricsCollector: MetricsCollector | undefined, count: number): void;
+export declare function recordWorkerCapacitySaturationMetric(metricsCollector: MetricsCollector | undefined, registry: WorkerRegistry): void;

package/dist/server/runtime/task-metrics.js

@@ -0,0 +1,36 @@
+import { METRICS } from "../../observability/metrics.js";
+import {
+  calculateExecutionLatencyMs,
+  calculateQueueLatencyMs,
+  isHeartbeatStale
+} from "../task-state.js";
+const DEFAULT_STALE_HEARTBEAT_METRIC_AFTER_MS = 60000;
+export function recordTaskBacklogMetric(metricsCollector, taskQueue) {
+  metricsCollector?.gauge(METRICS.taskBacklog.name, taskQueue.totalPendingCount());
+}
+export function recordTaskQueueLatencyMetric(metricsCollector, record) {
+  const latency = calculateQueueLatencyMs(record);
+  if (latency !== void 0)
+    metricsCollector?.record(METRICS.taskQueueLatency.name, latency);
+}
+export function recordTaskExecutionLatencyMetric(metricsCollector, record, completedAt) {
+  const latency = calculateExecutionLatencyMs(record, completedAt);
+  if (latency !== void 0)
+    metricsCollector?.record(METRICS.taskExecutionLatency.name, latency);
+}
+export function recordTaskRetryMetric(metricsCollector, count = 1) {
+  metricsCollector?.increment(METRICS.taskRetries.name, count);
+}
+export function recordTaskRequeueMetric(metricsCollector, count = 1) {
+  metricsCollector?.increment(METRICS.taskRequeues.name, count);
+}
+export function isTaskHeartbeatStaleForMetrics(record, currentTime, staleAfterMs = DEFAULT_STALE_HEARTBEAT_METRIC_AFTER_MS) {
+  return isHeartbeatStale(record, currentTime, staleAfterMs);
+}
+export function recordTaskStaleHeartbeatMetric(metricsCollector, count) {
+  metricsCollector?.gauge(METRICS.taskStaleHeartbeats.name, count);
+}
+export function recordWorkerCapacitySaturationMetric(metricsCollector, registry) {
+  const workers = registry.getAll(), totalCapacity = workers.reduce((sum, worker) => sum + worker.concurrency, 0), totalInFlight = workers.reduce((sum, worker) => sum + worker.inFlight, 0), saturation = totalCapacity === 0 ? 0 : totalInFlight / totalCapacity;
+  metricsCollector?.gauge(METRICS.workerCapacitySaturation.name, saturation);
+}

package/dist/server/runtime/task-polling.d.ts

@@ -0,0 +1,9 @@
+import type { ServeOptions } from '../index.ts';
+import { type Principal } from '../principal.ts';
+import type { PendingTask } from '../task-queue-types.ts';
+import type { InflightRecord } from '../task-state.ts';
+import type { ServerContext } from './context.ts';
+export declare function createLongPollInflightRecord(queue: string, task: PendingTask): InflightRecord;
+export declare function markTaskClaimedByLongPollWorker(context: ServerContext, options: ServeOptions, queue: string, task: PendingTask): Promise<string>;
+export declare function handleTaskPollRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;
+export declare function handleTaskResultRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;

package/dist/server/runtime/task-polling.js

@@ -0,0 +1,132 @@
+import { isAuthenticated } from "../principal.js";
+import {
+  readInflightRecord,
+  transitionInflightToResolved,
+  transitionQueuedToInflight
+} from "../task-state.js";
+import {
+  recordTaskBacklogMetric,
+  recordTaskExecutionLatencyMetric,
+  recordTaskQueueLatencyMetric
+} from "./task-metrics.js";
+const TASK_POLL_RE = /^\/v1\/tasks\/([\w-]+)$/, TASK_RESULT_RE = /^\/v1\/tasks\/([\w-]+)\/result$/, TASK_DIAGNOSTICS_PATH = "/v1/tasks/diagnostics", MAX_POLL_TIMEOUT = 60000, DEFAULT_POLL_TIMEOUT = 30000, DEFAULT_VISIBILITY_TIMEOUT = 30000;
+async function parseTaskResultBody(request) {
+  try {
+    return await request.json();
+  } catch {
+    return null;
+  }
+}
+function authorizeWorkerPrincipal(principal) {
+  if (principal === void 0)
+    return null;
+  if (isAuthenticated(principal) && principal.hasScope("workers:write"))
+    return null;
+  return Response.json({ error: "Forbidden" }, { status: 403 });
+}
+function validateTaskResultBody(body) {
+  const { operationId, status } = body;
+  if (typeof operationId !== "string" || typeof status !== "string")
+    return Response.json({ error: "Missing required fields: operationId, status" }, { status: 400 });
+  if (status !== "completed" && status !== "failed")
+    return Response.json({ error: 'status must be "completed" or "failed"' }, { status: 400 });
+  return {
+    operationId,
+    status,
+    workerId: typeof body.workerId === "string" ? body.workerId : void 0,
+    value: body.value,
+    error: typeof body.error === "string" ? body.error : void 0
+  };
+}
+async function applyTaskResult(context, options, result, inflightRecord) {
+  const { operationId, status, value, error } = result, resolvedStatus = status === "failed" ? "failed" : "completed";
+  try {
+    context.taskQueue.complete({ operationId, status, value, error });
+    context.deadlineTracker.remove(operationId);
+    const resolvedAt = Date.now();
+    await transitionInflightToResolved(options.engine.storage, operationId, resolvedStatus, {
+      ...inflightRecord === null ? {} : { record: inflightRecord },
+      resolvedAt,
+      resolutionReason: resolvedStatus,
+      ...status === "completed" ? { value } : { error }
+    });
+    if (inflightRecord !== null)
+      recordTaskExecutionLatencyMetric(context.metricsCollector, inflightRecord, resolvedAt);
+  } catch (storageError) {
+    console.error(`[weft] Failed to transition task "${operationId}" to resolved \u2014 inflight record may leak:`, storageError);
+  }
+}
+export function createLongPollInflightRecord(queue, task) {
+  const now = Date.now(), visibilityTimeout = task.visibilityTimeout ?? DEFAULT_VISIBILITY_TIMEOUT, deadline = now + visibilityTimeout;
+  return {
+    operationId: task.operationId,
+    workerId: `longpoll-${crypto.randomUUID().slice(0, 8)}`,
+    deadline,
+    activityName: task.activityName,
+    queue,
+    input: task.input,
+    attempt: task.attempt ?? 1,
+    visibilityTimeout,
+    retryPolicy: task.retryPolicy,
+    workflowId: task.workflowId,
+    firstQueuedAt: task.firstQueuedAt ?? task.enqueuedAt ?? now,
+    lastQueuedAt: task.lastQueuedAt ?? task.enqueuedAt ?? now,
+    lastDispatchedAt: now,
+    startedAt: now,
+    retryCount: task.retryCount ?? Math.max(0, (task.attempt ?? 1) - 1),
+    requeueCount: task.requeueCount ?? 0,
+    lastRequeueReason: task.lastRequeueReason
+  };
+}
+export async function markTaskClaimedByLongPollWorker(context, options, queue, task) {
+  const inflightRecord = createLongPollInflightRecord(queue, task);
+  context.deadlineTracker.add({
+    operationId: task.operationId,
+    deadline: inflightRecord.deadline
+  });
+  const normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord);
+  recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);
+  recordTaskBacklogMetric(context.metricsCollector, context.taskQueue);
+  return normalizedInflightRecord.workerId;
+}
+export async function handleTaskPollRequest(context, options, request, url, principal) {
+  if (request.method !== "GET")
+    return null;
+  if (url.pathname === TASK_DIAGNOSTICS_PATH)
+    return null;
+  const pollMatch = TASK_POLL_RE.exec(url.pathname);
+  if (!pollMatch?.[1])
+    return null;
+  const authorizationResponse = authorizeWorkerPrincipal(principal);
+  if (authorizationResponse !== null)
+    return authorizationResponse;
+  const queue = decodeURIComponent(pollMatch[1]), activities = url.searchParams.getAll("activity");
+  if (activities.length === 0)
+    return Response.json({ error: 'At least one "activity" query parameter is required' }, { status: 400 });
+  const rawTimeout = url.searchParams.get("timeout"), timeout = rawTimeout !== null ? Math.min(Math.max(0, Number(rawTimeout)), MAX_POLL_TIMEOUT) : DEFAULT_POLL_TIMEOUT, task = await context.taskQueue.poll(queue, activities, timeout, request.signal);
+  if (task !== null) {
+    const workerId = await markTaskClaimedByLongPollWorker(context, options, queue, task);
+    return Response.json({ ...task, workerId });
+  }
+  return new Response(null, { status: 204 });
+}
+export async function handleTaskResultRequest(context, options, request, url, principal) {
+  if (request.method !== "POST")
+    return null;
+  if (!TASK_RESULT_RE.exec(url.pathname)?.[1])
+    return null;
+  const authorizationResponse = authorizeWorkerPrincipal(principal);
+  if (authorizationResponse !== null)
+    return authorizationResponse;
+  const body = await parseTaskResultBody(request);
+  if (body === null)
+    return Response.json({ error: "Invalid JSON body" }, { status: 400 });
+  const validated = validateTaskResultBody(body);
+  if (validated instanceof Response)
+    return validated;
+  const inflightRecord = await readInflightRecord(options.engine.storage, validated.operationId);
+  if (inflightRecord !== null && (validated.workerId === void 0 || inflightRecord.workerId !== validated.workerId))
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  await applyTaskResult(context, options, validated, inflightRecord);
+  return Response.json({ ok: !0 });
+}

package/dist/server/runtime/task-reconciliation.d.ts

@@ -0,0 +1,17 @@
+import type { ServeOptions } from '../index.ts';
+import type { InflightRecord, TaskRequeueReason } from '../task-state.ts';
+import type { ServerContext } from './context.ts';
+/**
+ * Given a persisted inflight record, either permanently fail the task (if
+ * retry attempts are exhausted) or transition it back to queued and
+ * re-dispatch with backoff. Both the worker-disconnect handler and the
+ * visibility-timeout scanner share this logic.
+ */
+export declare function reassignOrExpireTask(context: ServerContext, options: ServeOptions, operationId: string, record: InflightRecord, reason?: TaskRequeueReason): Promise<void>;
+/**
+ * Drain expired entries from the in-memory deadline heap and reassign
+ * their tasks. Only touches storage for the specific operations whose
+ * deadlines have actually passed — no full `op:inflight:*` scan.
+ */
+export declare function scanExpiredTasks(context: ServerContext, options: ServeOptions, cleanupWorkflowIndex: (operationId: string) => void): Promise<void>;
+export declare function reconcileOrphanedRecords(context: ServerContext, options: ServeOptions, cleanupWorkflowIndex: (operationId: string) => void): Promise<void>;