@lostgradient/weft 0.18.0 → 0.19.0

package/dist/core/worker-realm-readiness.js

@@ -0,0 +1,127 @@
+import { computeWorkerManifestDigest, parseWorkerManifest } from "../worker/manifest/index.js";
+import {
+  buildDeclaredWorkflowContract,
+  declaredWorkflowContractsMatch
+} from "../worker/manifest/internal-realm.js";
+import {
+  assertWorkerProtocolMessageWithinLimit,
+  WORKER_PROTOCOL_VERSION
+} from "./worker-protocol.js";
+export function isWorkerRealmReadyMessage(message) {
+  return typeof message === "object" && message !== null && message.type === "ready";
+}
+
+export class WorkerRealmReadiness {
+  #dependencies;
+  #readyByWorker = new Map;
+  #pendingByWorker = new Map;
+  constructor(dependencies) {
+    this.#dependencies = dependencies;
+  }
+  isReady(worker) {
+    return this.#readyByWorker.has(worker);
+  }
+  async waitForReady(worker) {
+    const known = this.#readyByWorker.get(worker);
+    if (known)
+      return { ok: !0, ...known };
+    return new Promise((resolve) => {
+      let settled = !1;
+      const settleOnce = (outcome) => {
+        if (settled)
+          return;
+        settled = !0;
+        resolve(outcome);
+      }, timeout = setTimeout(() => {
+        this.#pendingByWorker.delete(worker);
+        settleOnce({
+          ok: !1,
+          error: `Worker realm did not send a ready message within ${this.#dependencies.timeoutMs}ms`,
+          failureCategory: "timeout"
+        });
+      }, this.#dependencies.timeoutMs);
+      this.#pendingByWorker.set(worker, (outcome) => {
+        clearTimeout(timeout);
+        settleOnce(outcome);
+      });
+    });
+  }
+  async noteReadyMessage(worker, message) {
+    const outcome = await this.#validate(message);
+    if (outcome.ok)
+      this.#readyByWorker.set(worker, {
+        realmGeneration: outcome.realmGeneration,
+        manifestDigest: outcome.manifestDigest
+      });
+    const pending = this.#pendingByWorker.get(worker);
+    if (pending) {
+      this.#pendingByWorker.delete(worker);
+      pending(outcome);
+    }
+  }
+  forget(worker) {
+    this.#readyByWorker.delete(worker);
+    const pending = this.#pendingByWorker.get(worker);
+    if (pending) {
+      this.#pendingByWorker.delete(worker);
+      pending({
+        ok: !1,
+        error: "Worker was discarded before its ready handshake completed",
+        failureCategory: "system"
+      });
+    }
+  }
+  clear() {
+    for (const resolve of this.#pendingByWorker.values())
+      resolve({
+        ok: !1,
+        error: "Worker execution strategy was disposed before the ready handshake completed",
+        failureCategory: "system"
+      });
+    this.#pendingByWorker.clear();
+    this.#readyByWorker.clear();
+  }
+  async#validate(message) {
+    try {
+      assertWorkerProtocolMessageWithinLimit(message, this.#dependencies.maxProtocolMessageBytes);
+    } catch (error) {
+      return {
+        ok: !1,
+        error: error instanceof Error ? error.message : String(error),
+        failureCategory: "resource"
+      };
+    }
+    const record = message;
+    if (record.protocolVersion !== WORKER_PROTOCOL_VERSION)
+      return {
+        ok: !1,
+        error: `Worker realm ready message protocol version mismatch: expected ${WORKER_PROTOCOL_VERSION}, got ${String(record.protocolVersion)}`,
+        failureCategory: "system"
+      };
+    if (typeof record.realmGeneration !== "string" || record.realmGeneration.length === 0)
+      return {
+        ok: !1,
+        error: "Worker realm ready message must include a non-empty realmGeneration string",
+        failureCategory: "system"
+      };
+    const parsed = parseWorkerManifest(record.manifest);
+    if (!parsed.ok)
+      return {
+        ok: !1,
+        error: `Worker realm manifest rejected: ${parsed.message}`,
+        failureCategory: "system"
+      };
+    const missing = this.#dependencies.getExpectedWorkflowTypes().filter((workflowType) => {
+      const reported = parsed.manifest.workflows[workflowType];
+      return !reported || !declaredWorkflowContractsMatch(reported, buildDeclaredWorkflowContract(workflowType));
+    }).toSorted();
+    if (missing.length > 0)
+      return {
+        ok: !1,
+        error: `Worker realm manifest is missing or disagrees on workflow type(s) the host expects: ${missing.join(", ")}`,
+        failureCategory: "system"
+      };
+    const manifestDigest = await computeWorkerManifestDigest(parsed.manifest);
+    return { ok: !0, realmGeneration: record.realmGeneration, manifestDigest };
+  }
+}

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { AlertManager } from './alerting/index';
 export type { AlertAction, AlertMetric, AlertRule, AlertStateSnapshot, AlertStatus, AlertingOptions, WebhookTarget, } from './alerting/types';
 export { ActivityAsyncPendingEvent, ActivityCompletedEvent, ActivityFailedEvent, ActivityStartedEvent, AlertFiredEvent, AlertResolvedEvent, AttributesChangedEvent, CheckpointSizeWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, ScheduleFiredEvent, ScheduleMissedFireEvent, SignalDeliveredEvent, SignalReceivedEvent, StorageSizeReportedEvent, TaskResultDeadLetteredEvent, UpdateCompletedEvent, UpdateReceivedEvent, WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowDefinitionRegisteredEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTeardownEvent, WorkflowTimedOutEvent, } from './core/events';
 export type { TypedEventTarget, WeftEventMap, WorkflowRecoverySkippedReason, WorkflowTeardownStatus, } from './core/events';
-export { detectRuntime, hashBytes, hashString, sleep } from './runtime/portable';
+export { detectRuntime, detectRuntimeVersion, hashBytes, hashString, sleep, } from './runtime/portable';
 export type { RuntimeKind } from './runtime/portable';
 export { createBunCompressor, createCompressor } from './core/compression';
 export type { CompressionAlgorithm, CompressionOptions, Compressor } from './core/compression';
@@ -102,6 +102,8 @@ export type { WorkerPoolOptions } from './workers/pool';
 export { HeartbeatManager } from './worker/heartbeat';
 export { RemoteWorker } from './worker/index';
 export { LongPollWorker } from './worker/long-poll';
+export { MAX_MANIFEST_ACTIVITY_COUNT, MAX_MANIFEST_CAPABILITY_COUNT, MAX_MANIFEST_CAPABILITY_DEPTH, MAX_MANIFEST_CAPABILITY_STRING_BYTES, MAX_MANIFEST_IDENTIFIER_BYTES, MAX_MANIFEST_WORKFLOW_COUNT, MAX_NORMALIZED_MANIFEST_BYTES, WORKER_MANIFEST_DIGEST_ALGORITHM, WORKER_MANIFEST_VERSION, WorkerManifestBuildError, buildWorkerExecutionIdentity, buildWorkerManifestFromRegistry, canonicalWorkerManifestJson, computeWorkerManifestDigest, digestCanonicalWorkerManifest, executionIdentitySatisfies, normalizeWorkerManifest, parseWorkerManifest, parseWorkerManifestJson, } from './worker/manifest/index.ts';
+export type { ManifestValidationFailure, WorkerActivityContract, WorkerDeploymentIdentity, WorkerExecutionIdentity, WorkerExecutionRequirement, WorkerManifest, WorkerManifestFromRegistryOptions, WorkerManifestParseResult, WorkerManifestParseSuccess, WorkerManifestRejectionReason, WorkerRuntimeIdentity, WorkerWorkflowContract, } from './worker/manifest/index.ts';
 export { WorkerRegistry } from './worker/registry';
 export { WorkerProtocolIncompatibleError, workerProtocolIncompatibleMessage, } from './worker/worker-protocol-incompatible-error';
 export { buildQualifiedActivityTable } from './worker/workflow-activity-binding';

package/dist/index.js

@@ -91,7 +91,13 @@ export {
   WorkflowTeardownEvent,
   WorkflowTimedOutEvent
 } from "./core/events.js";
-export { detectRuntime, hashBytes, hashString, sleep } from "./runtime/portable.js";
+export {
+  detectRuntime,
+  detectRuntimeVersion,
+  hashBytes,
+  hashString,
+  sleep
+} from "./runtime/portable.js";
 export { createBunCompressor, createCompressor } from "./core/compression.js";
 export { CompressedStorage } from "./storage/compressed-storage.js";
 export { storageDeleteRange } from "./storage/delete-range.js";
@@ -209,6 +215,27 @@ export { WorkerPool } from "./workers/pool.js";
 export { HeartbeatManager } from "./worker/heartbeat.js";
 export { RemoteWorker } from "./worker/index.js";
 export { LongPollWorker } from "./worker/long-poll.js";
+export {
+  MAX_MANIFEST_ACTIVITY_COUNT,
+  MAX_MANIFEST_CAPABILITY_COUNT,
+  MAX_MANIFEST_CAPABILITY_DEPTH,
+  MAX_MANIFEST_CAPABILITY_STRING_BYTES,
+  MAX_MANIFEST_IDENTIFIER_BYTES,
+  MAX_MANIFEST_WORKFLOW_COUNT,
+  MAX_NORMALIZED_MANIFEST_BYTES,
+  WORKER_MANIFEST_DIGEST_ALGORITHM,
+  WORKER_MANIFEST_VERSION,
+  WorkerManifestBuildError,
+  buildWorkerExecutionIdentity,
+  buildWorkerManifestFromRegistry,
+  canonicalWorkerManifestJson,
+  computeWorkerManifestDigest,
+  digestCanonicalWorkerManifest,
+  executionIdentitySatisfies,
+  normalizeWorkerManifest,
+  parseWorkerManifest,
+  parseWorkerManifestJson
+} from "./worker/manifest/index.js";
 export { WorkerRegistry } from "./worker/registry.js";
 export {
   WorkerProtocolIncompatibleError,

package/dist/json-schema.js

@@ -1,4 +1,4 @@
 // @bun
-var O=import.meta.require,T=(j,q,z)=>{if(q!=null){if(typeof q!=="object"&&typeof q!=="function")throw TypeError('Object expected to be assigned to "using" declaration');let A;if(z)A=q[Symbol.asyncDispose];if(A===void 0)A=q[Symbol.dispose];if(typeof A!=="function")throw TypeError("Object not disposable");j.push([z,A,q])}else if(z)j.push([z]);return q},y=(j,q,z)=>{let A=(G)=>q=z?new SuppressedError(G,q,"An error was suppressed during disposal"):(z=!0,G),H=(G)=>{while(G=j.pop())try{var $=G[1]&&G[1].call(G[2]);if(G[0])return Promise.resolve($).then(H,(Q)=>(A(Q),H()))}catch(Q){A(Q)}if(z)throw q};return H()};class X extends Error{code;constructor(j,q,z){super(q,z);this.code=j,this.name=j}}var B={WorkflowAlreadyExistsError:!0,BulkDeleteRequiresTerminalWorkflowsError:!0,BulkOperationConfirmationError:!0,WorkflowTypeNotRegisteredForRecoveryError:!0,EngineCreateNameMismatchError:!0,EngineDisposedError:!0,EngineDisposalError:!0,WorkflowNotFoundError:!0,WorkflowNotRegisteredError:!0,WorkflowConcurrencyLimitExceededError:!0,WorkflowSuspendNotSupportedError:!0,ActivityResolutionError:!0,BranchTopologyChangedError:!0,PersistedDataIncompatibleError:!0,WorkflowTimeoutError:!0,HttpClientError:!0,WorkerProtocolIncompatibleError:!0,UpdateTimeoutError:!0,UpdateValidationError:!0,WorkflowTerminalError:!0,WorkflowBuilderError:!0,VersionMismatchError:!0,EffectReplayConflictError:!0,ReviewTimeoutError:!0,AtomicStateConflictError:!0,StandardSchemaValidationError:!0,ActivityReconciliationCapabilityError:!0,ActivityReconciliationConflictError:!0,ActivityReconciliationIndeterminateError:!0,DurableActivityScopeError:!0,DurableActivityUnsupportedError:!0,AsyncActivityTokenNotFoundError:!0,ActivityScheduleToCloseTimeoutError:!0,ActivityPerAttemptTimeoutError:!0,PayloadSizeExceededError:!0,StartOrSignalConflictError:!0,WorkflowTeardownPendingError:!0,IdempotencyKeyPurgedError:!0},R=new Set(Object.keys(B));class K extends X{fieldName;operation;issues;constructor(j){super("StandardSchemaValidationError",M(j.fieldName,j.operation,j.issues));this.fieldName=j.fieldName,this.operation=j.operation,this.issues=j.issues}}async function Z(j,q,z){let A=j["~standard"];if(!D(A))throw TypeError(`Schema for ${z.fieldName} does not provide runtime validation. Attach a Standard Schema validator (Zod, Valibot, or another vendor) or supply a runtime-validating schema at this boundary.`);let H=await A.validate(q);if(H.issues===void 0)return H.value;throw new K({fieldName:z.fieldName,operation:z.operation,issues:H.issues.map(U)})}function Y(j){return j.map((q)=>q.path===""?q.message:`${q.path}: ${q.message}`).join(`
+var O=import.meta.require,T=(j,q,z)=>{if(q!=null){if(typeof q!=="object"&&typeof q!=="function")throw TypeError('Object expected to be assigned to "using" declaration');let A;if(z)A=q[Symbol.asyncDispose];if(A===void 0)A=q[Symbol.dispose];if(typeof A!=="function")throw TypeError("Object not disposable");j.push([z,A,q])}else if(z)j.push([z]);return q},y=(j,q,z)=>{let A=(G)=>q=z?new SuppressedError(G,q,"An error was suppressed during disposal"):(z=!0,G),H=(G)=>{while(G=j.pop())try{var $=G[1]&&G[1].call(G[2]);if(G[0])return Promise.resolve($).then(H,(Q)=>(A(Q),H()))}catch(Q){A(Q)}if(z)throw q};return H()};class X extends Error{code;constructor(j,q,z){super(q,z);this.code=j,this.name=j}}var B={WorkflowAlreadyExistsError:!0,BulkDeleteRequiresTerminalWorkflowsError:!0,BulkOperationConfirmationError:!0,WorkflowTypeNotRegisteredForRecoveryError:!0,EngineCreateNameMismatchError:!0,EngineDisposedError:!0,EngineDisposalError:!0,WorkflowNotFoundError:!0,WorkflowNotRegisteredError:!0,WorkflowConcurrencyLimitExceededError:!0,WorkflowSuspendNotSupportedError:!0,ActivityResolutionError:!0,BranchTopologyChangedError:!0,PersistedDataIncompatibleError:!0,WorkflowTimeoutError:!0,HttpClientError:!0,WorkerProtocolIncompatibleError:!0,UpdateTimeoutError:!0,UpdateValidationError:!0,WorkflowTerminalError:!0,WorkflowBuilderError:!0,VersionMismatchError:!0,EffectReplayConflictError:!0,ReviewTimeoutError:!0,AtomicStateConflictError:!0,StandardSchemaValidationError:!0,ActivityReconciliationCapabilityError:!0,ActivityReconciliationConflictError:!0,ActivityReconciliationIndeterminateError:!0,DurableActivityScopeError:!0,DurableActivityUnsupportedError:!0,AsyncActivityTokenNotFoundError:!0,ActivityScheduleToCloseTimeoutError:!0,ActivityPerAttemptTimeoutError:!0,PayloadSizeExceededError:!0,StartOrSignalConflictError:!0,WorkflowTeardownPendingError:!0,IdempotencyKeyPurgedError:!0,WorkerManifestBuildError:!0},R=new Set(Object.keys(B));class K extends X{fieldName;operation;issues;constructor(j){super("StandardSchemaValidationError",M(j.fieldName,j.operation,j.issues));this.fieldName=j.fieldName,this.operation=j.operation,this.issues=j.issues}}async function Z(j,q,z){let A=j["~standard"];if(!D(A))throw TypeError(`Schema for ${z.fieldName} does not provide runtime validation. Attach a Standard Schema validator (Zod, Valibot, or another vendor) or supply a runtime-validating schema at this boundary.`);let H=await A.validate(q);if(H.issues===void 0)return H.value;throw new K({fieldName:z.fieldName,operation:z.operation,issues:H.issues.map(U)})}function Y(j){return j.map((q)=>q.path===""?q.message:`${q.path}: ${q.message}`).join(`
 `)}function D(j){return typeof j.validate==="function"}function U(j){return{message:j.message,path:b(j.path)}}function b(j){if(j===void 0||j.length===0)return"";let q="";for(let z of j)q+="/",q+=w(z);return q}function w(j){let q=F(j)?j.key:j;return J(String(q))}function F(j){return j!==null&&typeof j==="object"&&"key"in j}function J(j){return j.replace(/~/g,"~0").replace(/\//g,"~1")}function M(j,q,z){return`Validation failed for ${q===void 0?j:`${q} ${j}`}:
 ${Y(z)}`}var V=Y,k=K,P=Z;export{P as validateStandardSchema,V as formatStandardSchemaIssues,k as StandardSchemaValidationError};

package/dist/runtime/portable.d.ts

@@ -40,6 +40,20 @@ export declare function isBunRuntime(): boolean;
  * ```
  */
 export declare function detectRuntime(): RuntimeKind;
+/**
+ * Detect the current runtime's version string, matching {@link detectRuntime}'s
+ * detection precedence. A browser or edge runtime exposes no version, so an
+ * empty string is a truthful answer rather than a missing field.
+ *
+ * @example
+ * ```ts
+ * import { detectRuntimeVersion } from '@lostgradient/weft';
+ *
+ * const version = detectRuntimeVersion();
+ * console.log(typeof version); // 'string'
+ * ```
+ */
+export declare function detectRuntimeVersion(): string;
 /**
  * Read an environment variable without assuming a runtime.
  *

package/dist/runtime/portable.js

@@ -33,6 +33,16 @@ export function detectRuntime() {
       return detector.kind;
   return "edge";
 }
+export function detectRuntimeVersion() {
+  switch (detectRuntime()) {
+    case "bun":
+      return getBunGlobal()?.version ?? "";
+    case "node":
+      return getProcess()?.versions?.node ?? "";
+    default:
+      return "";
+  }
+}
 export function readEnvironmentVariable(name) {
   const bun = getBunGlobal();
   if (bun !== void 0)

package/dist/server/index.d.ts

@@ -13,11 +13,14 @@ import type { AuthConfig, RateLimitConfig } from './authentication.ts';
 import { type DashboardAssets } from './dashboard-assets.ts';
 import type { DiscoveryInfo } from './discovery-info.ts';
 import type { CorsOptions } from './runtime/cors.ts';
+import type { TaskResultView } from './runtime/task-result-view.ts';
 import type { SchedulingPolicy } from './task-queue-types.ts';
 import { TaskQueue } from './task-queue.ts';
+import type { WorkerAdmissionPolicy } from './worker-admission-policy.ts';
 export { wireEventBroadcasting, type EventBroadcastingHandle, } from './runtime/event-broadcasting.ts';
 export type { DashboardAssets } from './dashboard-assets.ts';
 export type { CorsOptions } from './runtime/cors.ts';
+export type { WorkerAdmissionDecision, WorkerAdmissionPolicy, WorkerAdmissionRequest, } from './worker-admission-policy.ts';
 export { AUTHORIZATION_SCOPES, isAuthorizationScope, type AuthorizationScope, } from './authorization-scope.ts';
 export type { GetPrincipalOutput } from './operations/get-principal.ts';
 export { createRateLimiter, createRotatingApiKeyStore, defaultAuthAuditSink, isSensitiveHeader, redactCredential, redactHeaders, validateRateLimitConfig, type ApiKeyRegistration, type AuthAuditEvent, type AuthAuditSink, type AuthConfig, type RateLimitConfig, type RateLimitDecision, type RateLimiter, type RotatingApiKeyStore, } from './authentication.ts';
@@ -26,6 +29,7 @@ export type { PrometheusExporter } from '../observability/metrics.ts';
 export { WorkerRegistry } from '../worker/registry.ts';
 export type { RoutingPolicy } from '../worker/registry.ts';
 export type { DiscoveryInfo } from './discovery-info.ts';
+export type { TaskResultView } from './runtime/task-result-view.ts';
 export type { SchedulingPolicy } from './task-queue-types.ts';
 export { TaskQueue } from './task-queue.ts';
 /**
@@ -190,7 +194,7 @@ export interface ServeOptions {
      * workflow SSE requests return `429`.
      */
     maxStreamConnectionsPerWorkflow?: number;
-    /** How often (in ms) the server scans `op:inflight:*` for expired visibility deadlines. Defaults to 5 000. */
+    /** How often (in ms) the server scans the task ledger for expired visibility deadlines. Defaults to 5 000. */
     visibilityPollIntervalMs?: number;
     /**
      * Grace period (in ms) between a worker WebSocket close and the requeue of
@@ -204,6 +208,19 @@ export interface ServeOptions {
      * `[0, 5_000]`.
      */
     workerReconnectGracePeriodMs?: number;
+    /**
+     * How long (in ms) an adopted terminal task-ledger record is retained
+     * before the periodic reconciliation scan reaps it. Defaults to `undefined`
+     * — retention is opt-in, and unset means terminal records are kept forever
+     * regardless of adoption, matching the durable ledger's default posture of
+     * never discarding a task's authoritative record without an explicit
+     * policy. Only adopted records are ever eligible; a terminal record whose
+     * result no caller has adopted via {@link WeftServer.adoptTaskResult} is
+     * retained indefinitely no matter how old it is. Unlike workflow history's
+     * count-based `history.retentionWindow`, this is time-based — a terminal
+     * task record has no natural sequence axis to bound by count.
+     */
+    taskRetentionWindowMs?: number;
     /**
      * Maximum time (in ms) `server.stop()` waits for connected remote workers to
      * drain in-flight task results after receiving a shutdown frame before the
@@ -223,6 +240,14 @@ export interface ServeOptions {
      * least-loaded for that single call.
      */
     routingPolicy?: RoutingPolicy;
+    /**
+     * Gate on which workers may become routing-eligible, evaluated after the
+     * manifest is validated and checked for deployment consistency and before
+     * registry insertion. Defaults to `undefined`, which accepts every worker
+     * that already passed authentication — the behavior before this option
+     * existed.
+     */
+    workerAdmissionPolicy?: WorkerAdmissionPolicy;
     /**
      * Scheduling policy used by the {@link TaskQueue} when ordering pending tasks
      * within a queue. Defaults to `'priority'`.
@@ -263,10 +288,10 @@ export interface ServeOptions {
  * Descriptor for a task dispatched to a remote worker via
  * {@link WeftServer.dispatchTask}.
  *
- * `operationId` and `activityName` are required; all other fields refine
- * routing, retry behaviour, and priority.  Set `sticky: true` together with
- * `workflowId` to route the task to the worker that last handled tasks for
- * that workflow.
+ * `operationId`, `activityName`, and `workflowType` are required; all other
+ * fields refine routing, retry behaviour, and priority.  Set `sticky: true`
+ * together with `workflowId` to route the task to the worker that last
+ * handled tasks for that workflow.
  *
  * @example
  * ```ts
@@ -275,6 +300,7 @@ export interface ServeOptions {
  * const task: TaskDispatch = {
  *   operationId: crypto.randomUUID(),
  *   activityName: 'sendEmail',
+ *   workflowType: 'notifications',
  *   input: { to: 'user@example.com', subject: 'Hello' },
  *   queue: 'email',
  *   retryPolicy: { maxAttempts: 3, initialBackoff: '1s', backoffMultiplier: 2, maxBackoff: '30s' },
@@ -286,9 +312,17 @@ export interface TaskDispatch {
     operationId: string;
     activityName: string;
     input: unknown;
-    attempt?: number;
     /** Queue to dispatch the task to. Defaults to `'default'`. */
     queue?: string;
+    /**
+     * The dispatching workflow's registered type. Required — the durable task
+     * ledger's envelope (`RemoteTaskBase.workflowType`) is required, and
+     * `buildWorkerExecutionIdentity` needs it to look up the claiming worker's
+     * manifest entry (`manifest.workflows[workflowType].activities[activityName]`).
+     * `dispatchTaskImpl` rejects a call missing this field with an actionable
+     * error rather than defaulting it — there is no safe placeholder value.
+     */
+    workflowType: string;
     /** Workflow ID. Required for sticky routing to track worker affinity. */
     workflowId?: string | undefined;
     /** Durable token for the workflow run that launched this task, when known. */
@@ -345,6 +379,16 @@ export interface WeftServer extends AsyncDisposable {
     readonly url: string;
     readonly registry: WorkerRegistry;
     readonly taskQueue: TaskQueue;
+    /**
+     * Resolves once startup task-ledger recovery (WFT-23) has reconstructed
+     * every non-terminal task's in-memory indexes from durable storage;
+     * rejects if the recovery scan itself failed. `dispatchTask`, long-poll
+     * claim/result handling, and worker registration all await this
+     * internally before touching the ledger, so awaiting it explicitly is
+     * optional — it exists for callers (health checks, orchestration) that
+     * want to observe readiness without dispatching a probe task.
+     */
+    readonly ready: Promise<void>;
     /**
      * Drain connected remote workers, then stop the underlying Bun server.
      *
@@ -356,6 +400,22 @@ export interface WeftServer extends AsyncDisposable {
     stop(): Promise<void>;
     /** Dispatch a task to the best available worker. Returns true if dispatched. */
     dispatchTask(task: TaskDispatch): Promise<boolean>;
+    /**
+     * Read the current public view of a dispatched task's ledger record.
+     * Returns `null` if no record exists — never dispatched, or a retained
+     * terminal record was already reaped. See {@link TaskResultView}.
+     */
+    getTaskResult(operationId: string): Promise<TaskResultView | null>;
+    /**
+     * Mark a terminal task's result as adopted — the durable assertion that
+     * whatever consumed the result (a workflow's own checkpoint, or other
+     * application logic) has durably incorporated it. `resultDigest` must
+     * match the terminal record's `resultDigest` from {@link getTaskResult}.
+     * Returns `true` once adopted; `false` if the record is not currently
+     * terminal or the digest does not match. Only adopted terminal records
+     * become eligible for {@link ServeOptions.taskRetentionWindowMs} reaping.
+     */
+    adoptTaskResult(operationId: string, resultDigest: string): Promise<boolean>;
     /** Send a shutdown message to a specific worker and wait for it to disconnect. Returns true if the worker was found. */
     shutdownWorker(workerId: string, options?: {
         timeoutMs?: number;
@@ -372,8 +432,11 @@ export interface WeftServer extends AsyncDisposable {
  *
  * `serve()` validates the supplied `auth` configuration synchronously and
  * throws `Error` before binding the port if any auth setting is invalid.
- * In-flight task records from previous server runs are restored from storage
- * on startup so no tasks are silently lost across restarts.
+ * Every non-terminal task record from previous server runs is recovered from
+ * durable storage on startup so no task is silently lost across restarts —
+ * see `WeftServer.ready`. Task dispatch, claim, completion, and worker
+ * registration all wait for that recovery to finish (or fail loudly if it
+ * doesn't) before touching the ledger.
  *
  * The returned `WeftServer.taskQueue` is exposed for inspection, not as a stable
  * mutation surface — prefer `WeftServer` methods (`dispatchTask`,

package/dist/server/index.js

@@ -1,3 +1,4 @@
+import { requireStorageCapability } from "../storage/interface.js";
 import { WorkerRegistry } from "../worker/registry.js";
 import {
   createDashboardAssetRoute,
@@ -13,6 +14,7 @@ import {
 } from "./runtime/shutdown.js";
 import { stopBunServerForShutdown } from "./runtime/stop-server.js";
 import { cancelTask, dispatchTaskImpl } from "./runtime/task-dispatch.js";
+import { adoptTaskResultImpl, getTaskResultViewImpl } from "./runtime/task-result-view.js";
 import { publishTokenMessage, publishWatchMessage } from "./runtime/websocket-stream.js";
 import {
   buildBunServeConfig,
@@ -20,8 +22,7 @@ import {
   buildServerContext,
   cleanupWorkflowIndex,
   registerStackDisposers,
-  resolveNetworkConfig,
-  restoreInflightTasks
+  resolveNetworkConfig
 } from "./serve-internals.js";
 import { TaskQueue } from "./task-queue.js";
 export {
@@ -53,6 +54,7 @@ export const DASHBOARD_PAGE_ROUTES = [
   "/system"
 ];
 export function serve(options) {
+  requireStorageCapability(options.engine.storage, "conditionalBatch", "Remote task ledger (durable dispatch, claim, heartbeat, completion, and requeue)");
   const dashboardAssets = options.dashboardAssets === void 0 ? void 0 : resolveDashboardAssets(options.dashboardAssets, DASHBOARD_PAGE_ROUTES), { port, hostname, development, tlsOptions, serverOptions, serverMetricsCollector } = resolveNetworkConfig(options), context = buildServerContext(serverOptions, serverMetricsCollector), boundCleanup = (operationId) => cleanupWorkflowIndex(context, operationId), routes = {};
   if (options.dashboard != null)
     for (const path of DASHBOARD_PAGE_ROUTES)
@@ -79,7 +81,6 @@ export function serve(options) {
     throw error;
   }
   registerStackDisposers(stack, context, options, broadcastingHandle, boundCleanup);
-  restoreInflightTasks(context, options);
   const resolvedPort = server.port ?? port, resolvedHostname = server.hostname ?? hostname;
   return {
     port: resolvedPort,
@@ -87,10 +88,13 @@ export function serve(options) {
     url: `${tlsOptions ? "https" : "http"}://${resolvedHostname}:${resolvedPort}`,
     registry: context.registry,
     taskQueue: context.taskQueue,
+    ready: context.taskLedgerRecovery.ready,
     async stop() {
       await stack[Symbol.asyncDispose]();
     },
     dispatchTask: (task) => dispatchTaskImpl(context, options, task),
+    getTaskResult: (operationId) => getTaskResultViewImpl(options.engine.storage, operationId),
+    adoptTaskResult: (operationId, resultDigest) => adoptTaskResultImpl(options.engine.storage, operationId, resultDigest),
     shutdownWorker: (workerId, shutdownOptions) => shutdownWorkerImpl(context, workerId, shutdownOptions),
     shutdownAllWorkers: (shutdownOptions) => shutdownAllWorkersImpl(context, shutdownOptions),
     cancelTask: (operationId) => cancelTask(context, operationId),

package/dist/server/operations/get-task-diagnostics.d.ts

@@ -1,10 +1,41 @@
 /**
  * `weft.tasks.diagnostics` operation + REST binding.
  *
- * Scans durable task records and live worker state to identify queue pressure,
- * stale in-flight work, retry storms, and worker capacity saturation. Results
- * are intentionally bounded and low-cardinality so operators can use them in a
- * dashboard without turning workflow or worker identifiers into metrics labels.
+ * Scans the durable task ledger (WFT-24 — previously the retired
+ * `op:queued:`/`op:inflight:`/`op:resolved:`/`op:dead-letter:` keys, which
+ * nothing has written since the WFT-22 ledger cutover) and live worker state
+ * to identify queue pressure, stale in-flight work, retry storms, dead
+ * letters, and worker capacity saturation. Results are intentionally bounded
+ * and low-cardinality so operators can use them in a dashboard without
+ * turning workflow or worker identifiers into metrics labels.
+ *
+ * The output schema's field names and `kind`/`state` vocabulary are
+ * unchanged from the pre-ledger version — only the internal scan and
+ * classification logic changed — so existing dashboards built against this
+ * endpoint's shape keep working. `leased`, `completing`, and `cancelling`
+ * ledger states are all reported as diagnostic `state: 'inflight'`: they
+ * share the same lease-holder/heartbeat shape and the same operator
+ * question ("is a worker still making progress on this attempt?"), so
+ * exposing the ledger's more granular internal states here would add
+ * distinctions operators cannot act on differently.
+ *
+ * Retry-storm detection (`kind: 'retry-storm'`) no longer covers `terminal`
+ * records: `RemoteTaskTerminal` carries no `retryCount`/`requeueCount` (WFT-25
+ * deliberately dropped attempt-count history once a task resolves), so
+ * there is nothing left to detect a storm from once an attempt reaches a
+ * disposition. The `resolved` value in the `state` enum is kept in the
+ * output schema for backward compatibility but nothing produces it anymore.
+ * `dead-lettered` diagnostics are unaffected — that is a distinct, separate
+ * `kind`.
+ *
+ * Unlike the pre-ledger scan, the full ledger scan this operation performs
+ * is one combined keyspace across every state (queued through terminal),
+ * not separate per-state prefixes — there is no time-bounded history index
+ * to limit how many terminal records get walked past on the way to
+ * classifying the ones that still matter. Operators who dispatch high
+ * volumes of tasks and want this scan to stay cheap should set
+ * {@link ServeOptions.taskRetentionWindowMs} so adopted terminal records
+ * are reaped rather than accumulating indefinitely.
  *
  * @module server/operations/get-task-diagnostics
  */
@@ -30,8 +61,8 @@ declare const taskDiagnosticItemSchema: z.ZodObject<{
     state: z.ZodEnum<{
         "dead-lettered": "dead-lettered";
         queued: "queued";
-        inflight: "inflight";
         resolved: "resolved";
+        inflight: "inflight";
         capacity: "capacity";
     }>;
     operationId: z.ZodOptional<z.ZodString>;
@@ -44,10 +75,7 @@ declare const taskDiagnosticItemSchema: z.ZodObject<{
     queueLatencyMs: z.ZodOptional<z.ZodNumber>;
     executionLatencyMs: z.ZodOptional<z.ZodNumber>;
     heartbeatAgeMs: z.ZodOptional<z.ZodNumber>;
-    lastRequeueReason: z.ZodOptional<z.ZodEnum<{
-        "visibility-timeout": "visibility-timeout";
-        "worker-disconnect": "worker-disconnect";
-    }>>;
+    lastRequeueReason: z.ZodOptional<z.ZodString>;
     resolutionReason: z.ZodOptional<z.ZodString>;
     deadLetteredAt: z.ZodOptional<z.ZodNumber>;
     deadLetterReason: z.ZodOptional<z.ZodLiteral<"result-resolution-storage-exhausted">>;
@@ -74,8 +102,8 @@ declare const getTaskDiagnosticsOutput: z.ZodObject<{
         state: z.ZodEnum<{
             "dead-lettered": "dead-lettered";
             queued: "queued";
-            inflight: "inflight";
             resolved: "resolved";
+            inflight: "inflight";
             capacity: "capacity";
         }>;
         operationId: z.ZodOptional<z.ZodString>;
@@ -88,10 +116,7 @@ declare const getTaskDiagnosticsOutput: z.ZodObject<{
         queueLatencyMs: z.ZodOptional<z.ZodNumber>;
         executionLatencyMs: z.ZodOptional<z.ZodNumber>;
         heartbeatAgeMs: z.ZodOptional<z.ZodNumber>;
-        lastRequeueReason: z.ZodOptional<z.ZodEnum<{
-            "visibility-timeout": "visibility-timeout";
-            "worker-disconnect": "worker-disconnect";
-        }>>;
+        lastRequeueReason: z.ZodOptional<z.ZodString>;
         resolutionReason: z.ZodOptional<z.ZodString>;
         deadLetteredAt: z.ZodOptional<z.ZodNumber>;
         deadLetterReason: z.ZodOptional<z.ZodLiteral<"result-resolution-storage-exhausted">>;
@@ -146,7 +171,7 @@ export declare function createGetTaskDiagnosticsOperation(options?: GetTaskDiagn
 }, {
     items: {
         kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "dead-lettered" | "queued" | "inflight" | "resolved" | "capacity";
+        state: "dead-lettered" | "queued" | "resolved" | "inflight" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];
@@ -158,7 +183,7 @@ export declare function createGetTaskDiagnosticsOperation(options?: GetTaskDiagn
         queueLatencyMs?: number | undefined;
         executionLatencyMs?: number | undefined;
         heartbeatAgeMs?: number | undefined;
-        lastRequeueReason?: "visibility-timeout" | "worker-disconnect" | undefined;
+        lastRequeueReason?: string | undefined;
         resolutionReason?: string | undefined;
         deadLetteredAt?: number | undefined;
         deadLetterReason?: "result-resolution-storage-exhausted" | undefined;
@@ -185,7 +210,7 @@ export declare const getTaskDiagnosticsOperation: import("../operation-catalog.t
 }, {
     items: {
         kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "dead-lettered" | "queued" | "inflight" | "resolved" | "capacity";
+        state: "dead-lettered" | "queued" | "resolved" | "inflight" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];
@@ -197,7 +222,7 @@ export declare const getTaskDiagnosticsOperation: import("../operation-catalog.t
         queueLatencyMs?: number | undefined;
         executionLatencyMs?: number | undefined;
         heartbeatAgeMs?: number | undefined;
-        lastRequeueReason?: "visibility-timeout" | "worker-disconnect" | undefined;
+        lastRequeueReason?: string | undefined;
         resolutionReason?: string | undefined;
         deadLetteredAt?: number | undefined;
         deadLetterReason?: "result-resolution-storage-exhausted" | undefined;