@lostgradient/weft 0.17.0 → 0.19.0

package/dist/core/worker-realm-readiness.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Realm-ready handshake for internal `workflowExecutionMode: 'worker'`
+ * Workers (WFT-28).
+ *
+ * An internal Worker realm sends a `ready` message — its own manifest, built
+ * from exactly the workflow types its bootstrap script registered — before
+ * it can receive a `run` turn. The host checks that every workflow type it
+ * has registered appears in that manifest with a matching contract (a
+ * subset check, not exact-set equality — a realm may legitimately advertise
+ * more types than any one host dispatches to it, e.g. a shared worker pool
+ * serving several engines). A missing or mismatched type means the realm's
+ * bundle disagrees with the host about a workflow it needs (a stale build, a
+ * bootstrap script that fell out of sync), and the realm is discarded before
+ * it can ever execute a turn, rather than failing opaquely mid-dispatch.
+ *
+ * `ready` has no `workflowId` — it is a per-worker-lifetime handshake, not a
+ * per-workflow-turn message — so it cannot fit {@link WorkerOutboundMessage}'s
+ * shape (every variant there requires one) and is validated on its own path
+ * instead of through {@link assertWorkerOutboundMessageShape}, the same way
+ * `log` is handled outside the strict turn gate.
+ *
+ * @module core/worker-realm-readiness
+ */
+import type { WorkerManifest } from '../worker/manifest/types.ts';
+import type { FailureCategory } from './types.ts';
+/** Sent once by a Worker realm, before its first `run` turn. See {@link WorkerRealmReadiness}. */
+export type WorkerRealmReadyMessage = Readonly<{
+    type: 'ready';
+    protocolVersion: number;
+    realmGeneration: string;
+    manifest: WorkerManifest;
+}>;
+/** Shallow type guard — deep field validation happens in {@link WorkerRealmReadiness.noteReadyMessage}. */
+export declare function isWorkerRealmReadyMessage(message: unknown): message is WorkerRealmReadyMessage;
+export type RealmReadyOutcome = {
+    ok: true;
+    realmGeneration: string;
+    manifestDigest: string;
+} | {
+    ok: false;
+    error: string;
+    failureCategory: FailureCategory;
+};
+export interface WorkerRealmReadinessDependencies {
+    /**
+     * Live accessor for the host's registered workflow types, called fresh on
+     * every handshake rather than snapshotted at construction — the engine's
+     * registrations map is still empty when the strategy is constructed (the
+     * registration loop runs later in `Engine.create()`).
+     */
+    getExpectedWorkflowTypes: () => readonly string[];
+    timeoutMs: number;
+    maxProtocolMessageBytes: number | undefined;
+}
+/**
+ * Tracks, per pooled `Worker` instance, whether its one-time ready handshake
+ * has completed. A worker is validated at most once per lifetime — recycled
+ * workers skip straight to {@link isReady}.
+ */
+export declare class WorkerRealmReadiness {
+    #private;
+    constructor(dependencies: WorkerRealmReadinessDependencies);
+    isReady(worker: Worker): boolean;
+    /**
+     * Wait for `worker`'s ready handshake. Resolves immediately if the worker
+     * already completed it. The caller must attach its message listener (which
+     * routes into {@link noteReadyMessage}) before calling this, in the same
+     * synchronous continuation — `acquireAndSend` does exactly that, so no
+     * `ready` message can arrive before this registers its pending waiter.
+     */
+    waitForReady(worker: Worker): Promise<RealmReadyOutcome>;
+    /** Validate an inbound `ready` message and settle any pending {@link waitForReady} call. */
+    noteReadyMessage(worker: Worker, message: unknown): Promise<void>;
+    /** Drop a discarded worker's state, settling any pending waiter with a failure. */
+    forget(worker: Worker): void;
+    /** Settle every pending waiter on strategy disposal so no wait hangs past teardown. */
+    clear(): void;
+}

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/authorization-scope.d.ts

@@ -15,11 +15,41 @@
  * imply `workflows:read` or `workflows:write`. Operation authors must declare
  * the exact scope they require. Scope-implication semantics (if any) are a
  * future track.
+ *
+ * Public export so dashboards and API-key provisioning tooling can consume
+ * the canonical vocabulary instead of hand-copying it.
+ *
+ * @example
+ * ```ts
+ * import { AUTHORIZATION_SCOPES } from '@lostgradient/weft/server';
+ *
+ * console.log(AUTHORIZATION_SCOPES.includes('workflows:read'));
+ * ```
  */
 export declare const AUTHORIZATION_SCOPES: readonly ["workflows:read", "workflows:write", "workflows:admin", "schedules:read", "schedules:write", "signals:write", "updates:write", "queries:read", "reviews:read", "reviews:write", "attributes:read", "attributes:write", "tags:write", "streams:read", "events:read", "storage:read", "storage:write", "storage:admin", "workers:write", "system:read", "system:admin"];
-/** String-literal union of every authorization scope. */
+/**
+ * String-literal union of every authorization scope.
+ *
+ * @example
+ * ```ts
+ * import { type AuthorizationScope } from '@lostgradient/weft/server';
+ *
+ * const scope: AuthorizationScope = 'workflows:read';
+ * console.log(scope);
+ * ```
+ */
 export type AuthorizationScope = (typeof AUTHORIZATION_SCOPES)[number];
-/** Runtime type guard for the `AuthorizationScope` union. */
+/**
+ * Runtime type guard for the `AuthorizationScope` union.
+ *
+ * @example
+ * ```ts
+ * import { isAuthorizationScope } from '@lostgradient/weft/server';
+ *
+ * console.log(isAuthorizationScope('workflows:read'));
+ * console.log(isAuthorizationScope('not-a-scope'));
+ * ```
+ */
 export declare function isAuthorizationScope(value: string): value is AuthorizationScope;
 /**
  * Extract the full set of scopes granted by a JWT payload by *merging* every

package/dist/server/index.d.ts

@@ -13,17 +13,23 @@ 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';
 export type { RetryPolicy } from '../core/types.ts';
 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';
 /**
@@ -188,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
@@ -202,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
@@ -221,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'`.
@@ -261,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
@@ -273,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' },
@@ -284,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. */
@@ -343,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.
      *
@@ -354,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;
@@ -370,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,13 +22,16 @@ import {
   buildServerContext,
   cleanupWorkflowIndex,
   registerStackDisposers,
-  resolveNetworkConfig,
-  restoreInflightTasks
+  resolveNetworkConfig
 } from "./serve-internals.js";
 import { TaskQueue } from "./task-queue.js";
 export {
   wireEventBroadcasting
 } from "./runtime/event-broadcasting.js";
+export {
+  AUTHORIZATION_SCOPES,
+  isAuthorizationScope
+} from "./authorization-scope.js";
 export {
   createRateLimiter,
   createRotatingApiKeyStore,
@@ -49,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)
@@ -75,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,
@@ -83,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),