@lostgradient/weft 0.18.0 → 0.19.0

package/dist/core/weft-error.d.ts

@@ -25,7 +25,7 @@
  * }
  * ```
  */
-export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'EngineDisposalError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'WorkflowConcurrencyLimitExceededError' | 'WorkflowSuspendNotSupportedError' | 'ActivityResolutionError' | 'BranchTopologyChangedError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'DurableActivityScopeError' | 'DurableActivityUnsupportedError' | 'AsyncActivityTokenNotFoundError' | 'ActivityScheduleToCloseTimeoutError' | 'ActivityPerAttemptTimeoutError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'WorkflowTeardownPendingError' | 'IdempotencyKeyPurgedError';
+export type WeftErrorCode = 'WorkflowAlreadyExistsError' | 'BulkDeleteRequiresTerminalWorkflowsError' | 'BulkOperationConfirmationError' | 'WorkflowTypeNotRegisteredForRecoveryError' | 'EngineCreateNameMismatchError' | 'EngineDisposedError' | 'EngineDisposalError' | 'WorkflowNotFoundError' | 'WorkflowNotRegisteredError' | 'WorkflowConcurrencyLimitExceededError' | 'WorkflowSuspendNotSupportedError' | 'ActivityResolutionError' | 'BranchTopologyChangedError' | 'PersistedDataIncompatibleError' | 'WorkflowTimeoutError' | 'HttpClientError' | 'WorkerProtocolIncompatibleError' | 'UpdateTimeoutError' | 'UpdateValidationError' | 'WorkflowTerminalError' | 'WorkflowBuilderError' | 'VersionMismatchError' | 'EffectReplayConflictError' | 'ReviewTimeoutError' | 'AtomicStateConflictError' | 'StandardSchemaValidationError' | 'ActivityReconciliationCapabilityError' | 'ActivityReconciliationConflictError' | 'ActivityReconciliationIndeterminateError' | 'DurableActivityScopeError' | 'DurableActivityUnsupportedError' | 'AsyncActivityTokenNotFoundError' | 'ActivityScheduleToCloseTimeoutError' | 'ActivityPerAttemptTimeoutError' | 'PayloadSizeExceededError' | 'StartOrSignalConflictError' | 'WorkflowTeardownPendingError' | 'IdempotencyKeyPurgedError' | 'WorkerManifestBuildError';
 /**
  * Generic abstract base for all Weft library errors. The `TCode` parameter
  * makes each subclass's `code` its own literal type; the exported base surface

package/dist/core/weft-error.js

@@ -44,7 +44,8 @@ const publicWeftErrorCodeMap = {
   PayloadSizeExceededError: !0,
   StartOrSignalConflictError: !0,
   WorkflowTeardownPendingError: !0,
-  IdempotencyKeyPurgedError: !0
+  IdempotencyKeyPurgedError: !0,
+  WorkerManifestBuildError: !0
 }, PUBLIC_WEFT_ERROR_CODES = new Set(Object.keys(publicWeftErrorCodeMap));
 export function isWeftError(value) {
   return value instanceof WeftError;

package/dist/core/worker-execution-dispatcher.d.ts

@@ -9,6 +9,14 @@ export interface WorkerExecutionDispatcherDependencies {
     validateHostToWorkerMessage: (workflowId: string, message: WorkerInboundMessage, worker?: Worker) => boolean;
     attachWorkerListeners: (worker: Worker) => void;
     detachWorkerListenersIfIdle: (worker: Worker) => void;
+    /**
+     * Resolve once `worker`'s realm-ready handshake has settled (or
+     * immediately, if realm-readiness isn't required). `false` means the
+     * handshake failed or timed out; the implementation is responsible for
+     * discarding the worker and emitting the workflow failure itself, the same
+     * contract `validateHostToWorkerMessage` already uses.
+     */
+    ensureRealmReady: (worker: Worker, workflowId: string) => Promise<boolean>;
     beginTurn: (worker: Worker, workflowId: string, turnId: number, kind: 'run' | 'resume') => void;
     clearTurn: (worker: Worker) => void;
     discardWorkerAndFailWorkflows: (worker: Worker, options: {

package/dist/core/worker-execution-dispatcher.js

@@ -11,6 +11,10 @@ export class WorkerExecutionDispatcher {
       const worker = await this.#dependencies.pool.acquire();
       this.#dependencies.ownership.setActive(workflowId, worker);
       this.#dependencies.attachWorkerListeners(worker);
+      if (!await this.#dependencies.ensureRealmReady(worker, workflowId))
+        return;
+      if (this.#dependencies.isDisposed() || this.#dependencies.ownership.getActiveWorker(workflowId) !== worker)
+        return;
       this.#sendActiveMessage(worker, workflowId, message, "run");
     } catch (error) {
       this.#dependencies.emit({

package/dist/core/worker-execution-strategy-options.d.ts

@@ -5,6 +5,22 @@ export interface WorkerExecutionStrategyOptions {
     maxProtocolMessageBytes?: number;
     requireProtocolVersion?: boolean;
     discardOnCancel?: boolean;
+    /**
+     * Require every freshly acquired worker to complete the realm-ready
+     * handshake (WFT-28) — send a valid `ready` message whose manifest
+     * contains a matching contract for every type in
+     * {@link getExpectedWorkflowTypes} (a subset check, not exact-manifest
+     * equality) — before it receives its first `run` turn. Defaults to
+     * `false` so direct/test construction of this class is unaffected;
+     * `createExecutionStrategyBundle` hardcodes this to `true` for every
+     * engine-constructed worker-mode strategy, mirroring how
+     * `requireProtocolVersion` is already hardcoded there.
+     */
+    requireRealmReady?: boolean;
+    /** Required when {@link requireRealmReady} is `true`. Called fresh on every handshake. */
+    getExpectedWorkflowTypes?: () => readonly string[];
+    /** Bound (ms) on the realm-ready wait. Defaults to `DEFAULT_WORKER_REALM_READY_TIMEOUT_MS`. */
+    realmReadyTimeoutMs?: number;
     /**
      * The engine host's `EngineOptions.onLog` sink (#529). When present, the strategy
      * tells each worker (`hostHasLogSink: true` on `run`/`resume`) to forward `ctx.log`

package/dist/core/worker-execution-strategy.js

@@ -1,6 +1,7 @@
 import { WorkerCheckpointResumeState } from "./worker-checkpoint-resume-state.js";
 import { WorkerExecutionDispatcher } from "./worker-execution-dispatcher.js";
 import { WorkerExecutionOwnership } from "./worker-execution-ownership.js";
+import { WorkerFaultHandler } from "./worker-fault-handling.js";
 import {
   buildResumeMessage,
   buildRunMessage
@@ -15,7 +16,11 @@ import {
 } from "./worker-message-helpers.js";
 import { WorkerProtocolGuard } from "./worker-protocol-guard.js";
 import { isWorkerLogMessage } from "./worker-protocol-log.js";
-import { WORKER_PROTOCOL_VERSION } from "./worker-protocol.js";
+import {
+  DEFAULT_WORKER_REALM_READY_TIMEOUT_MS,
+  WORKER_PROTOCOL_VERSION
+} from "./worker-protocol.js";
+import { isWorkerRealmReadyMessage, WorkerRealmReadiness } from "./worker-realm-readiness.js";
 import {
   WorkerTurnWatchdog
 } from "./worker-turn-watchdog.js";
@@ -34,6 +39,8 @@ export class WorkerExecutionStrategy {
   #forwardedLogGate;
   #turnWatchdog;
   #protocolGuard;
+  #realmReadiness;
+  #faultHandler;
   #dispatcher;
   #messageHandler;
   #disposed;
@@ -44,7 +51,10 @@ export class WorkerExecutionStrategy {
       maxProtocolMessageBytes,
       requireProtocolVersion = !1,
       discardOnCancel = !1,
-      broadcastEvents = !1
+      broadcastEvents = !1,
+      requireRealmReady = !1,
+      getExpectedWorkflowTypes,
+      realmReadyTimeoutMs = DEFAULT_WORKER_REALM_READY_TIMEOUT_MS
     } = options ?? {};
     this.#pool = pool;
     this.#ownership = new WorkerExecutionOwnership;
@@ -56,21 +66,36 @@ export class WorkerExecutionStrategy {
     this.#discardOnCancel = discardOnCancel;
     this.#forwardedLogGate = forwardedLogGateFromStrategyOptions(options, maxProtocolMessageBytes);
     this.#turnWatchdog = new WorkerTurnWatchdog(this.#workflowTurnTimeoutMs, (turn) => {
-      this.#handleTurnTimeout(turn);
+      this.#faultHandler.handleTurnTimeout(turn);
     });
     this.#protocolGuard = new WorkerProtocolGuard(this.#maxProtocolMessageBytes, this.#requireProtocolVersion, this.#turnWatchdog);
+    this.#realmReadiness = WorkerExecutionStrategy.#buildRealmReadiness(requireRealmReady, getExpectedWorkflowTypes, realmReadyTimeoutMs, this.#maxProtocolMessageBytes);
+    this.#faultHandler = new WorkerFaultHandler({
+      ownership: this.#ownership,
+      checkpointResumeState: this.#checkpointResumeState,
+      turnWatchdog: this.#turnWatchdog,
+      forwardedLogGate: this.#forwardedLogGate,
+      realmReadiness: this.#realmReadiness,
+      workerListeners: this.#workerListeners,
+      protocolGuard: this.#protocolGuard,
+      pool: this.#pool,
+      emit: (message) => {
+        this.#emit(message);
+      }
+    });
     this.#dispatcher = new WorkerExecutionDispatcher({
       pool: this.#pool,
       ownership: this.#ownership,
       isDisposed: () => this.#disposed,
       requireProtocolVersion: () => this.#requireProtocolVersion,
-      validateHostToWorkerMessage: (workflowId, message, worker) => this.#assertHostToWorkerMessageWithinLimit(workflowId, message, worker),
+      validateHostToWorkerMessage: (workflowId, message, worker) => this.#faultHandler.assertHostToWorkerMessageWithinLimit(workflowId, message, worker),
       attachWorkerListeners: (worker) => {
         this.#attachWorkerListeners(worker);
       },
       detachWorkerListenersIfIdle: (worker) => {
         this.#detachWorkerListenersIfIdle(worker);
       },
+      ensureRealmReady: (worker, workflowId) => this.#ensureRealmReady(worker, workflowId),
       beginTurn: (worker, workflowId, turnId, kind) => {
         this.#turnWatchdog.begin(worker, workflowId, turnId, kind);
       },
@@ -78,7 +103,7 @@ export class WorkerExecutionStrategy {
         this.#turnWatchdog.clear(worker);
       },
       discardWorkerAndFailWorkflows: (worker, discardOptions) => {
-        this.#discardWorkerAndFailWorkflows(worker, discardOptions);
+        this.#faultHandler.discardWorkerAndFailWorkflows(worker, discardOptions);
       },
       emit: (message) => {
         this.#emit(message);
@@ -108,7 +133,7 @@ export class WorkerExecutionStrategy {
     this.#ownership.resetWorkflow(parameters.workflowId);
     this.#checkpointResumeState.resetWorkflow(parameters.workflowId);
     const message = buildRunMessage(parameters, this.#inboundMessageContext());
-    if (!this.#assertHostToWorkerMessageWithinLimit(parameters.workflowId, message))
+    if (!this.#faultHandler.assertHostToWorkerMessageWithinLimit(parameters.workflowId, message))
       return;
     this.#dispatcher.acquireAndSend(parameters.workflowId, message);
   }
@@ -135,6 +160,23 @@ export class WorkerExecutionStrategy {
         error: `No worker assigned for workflow: ${parameters.workflowId}`
       });
   }
+  async#ensureRealmReady(worker, workflowId) {
+    if (!this.#realmReadiness)
+      return !0;
+    if (this.#realmReadiness.isReady(worker))
+      return !0;
+    const outcome = await this.#realmReadiness.waitForReady(worker);
+    if (outcome.ok)
+      return !0;
+    this.#faultHandler.discardWorkerAndFailWorkflows(worker, {
+      targetWorkflowId: workflowId,
+      targetCategory: outcome.failureCategory,
+      targetError: outcome.error,
+      otherCategory: "system",
+      otherError: `Worker discarded after realm-ready handshake failed: ${outcome.error}`
+    });
+    return !1;
+  }
   #inboundMessageContext() {
     return {
       turnId: this.#nextTurnId++,
@@ -147,7 +189,7 @@ export class WorkerExecutionStrategy {
     if (worker) {
       this.#ownership.markCancelled(workflowId);
       if (this.#discardOnCancel) {
-        this.#discardWorkerAndFailWorkflows(worker, {
+        this.#faultHandler.discardWorkerAndFailWorkflows(worker, {
           targetWorkflowId: workflowId,
           skipTarget: !0,
           otherCategory: "system",
@@ -171,7 +213,7 @@ export class WorkerExecutionStrategy {
     this.#ownership.markCancelled(workflowId);
     this.#ownership.deleteParked(workflowId);
     if (this.#discardOnCancel) {
-      this.#discardWorkerAndFailWorkflows(parkedWorker, {
+      this.#faultHandler.discardWorkerAndFailWorkflows(parkedWorker, {
         targetWorkflowId: workflowId,
         skipTarget: !0,
         otherCategory: "system",
@@ -197,6 +239,7 @@ export class WorkerExecutionStrategy {
       this.#broadcastChannel.close();
     }
     this.#turnWatchdog.clearAll();
+    this.#realmReadiness?.clear();
     const activeWorkflowIds = this.#ownership.activeWorkflowIds();
     for (const workflowId of activeWorkflowIds)
       this.#releaseActiveWorker(workflowId);
@@ -206,13 +249,18 @@ export class WorkerExecutionStrategy {
     this.#messageHandler = null;
   }
   async#handleWorkerMessage(worker, message) {
+    if (isWorkerRealmReadyMessage(message)) {
+      if (this.#realmReadiness)
+        await this.#realmReadiness.noteReadyMessage(worker, message);
+      return;
+    }
     if (isWorkerLogMessage(message)) {
       const owns = (id) => this.#ownership.getTargetWorker(id) === worker, abuseDiscard = this.#forwardedLogGate.handle(worker, message, owns);
       if (abuseDiscard)
-        this.#discardWorkerAndFailWorkflows(worker, abuseDiscard);
+        this.#faultHandler.discardWorkerAndFailWorkflows(worker, abuseDiscard);
       return;
     }
-    if (!this.#acceptWorkerMessage(worker, message))
+    if (!this.#faultHandler.acceptWorkerMessage(worker, message))
       return;
     this.#turnWatchdog.clear(worker);
     const resumeVersionBeforeCheckpointHandling = this.#checkpointResumeState.beginCheckpointHandling(message), emitResult = emitWorkerMessageToEngine(this.#messageHandler, message), handlerFailed = emitResult instanceof Promise ? await emitResult : emitResult;
@@ -244,14 +292,6 @@ export class WorkerExecutionStrategy {
     if (this.#ownership.parkActive(message.workflowId, worker))
       this.#pool.release(worker);
   }
-  #handleWorkerError(worker, errorEvent) {
-    this.#discardWorkerAndFailWorkflows(worker, {
-      targetCategory: "system",
-      targetError: `Worker crashed: ${errorEvent.message ?? "unknown error"}`,
-      otherCategory: "system",
-      otherError: `Worker crashed: ${errorEvent.message ?? "unknown error"}`
-    });
-  }
   #releaseActiveWorker(workflowId) {
     const worker = this.#ownership.releaseActive(workflowId);
     if (worker) {
@@ -266,10 +306,10 @@ export class WorkerExecutionStrategy {
         this.#handleWorkerMessage(worker, message).catch(() => {});
       },
       error: (errorEvent) => {
-        this.#handleWorkerError(worker, errorEvent);
+        this.#faultHandler.handleWorkerError(worker, errorEvent);
       },
       messageerror: () => {
-        this.#discardWorkerAndFailWorkflows(worker, {
+        this.#faultHandler.discardWorkerAndFailWorkflows(worker, {
           targetCategory: "system",
           targetError: "Worker messageerror event",
           otherCategory: "system",
@@ -281,75 +321,6 @@ export class WorkerExecutionStrategy {
   #detachWorkerListenersIfIdle(worker) {
     this.#workerListeners.detachIfIdle(worker, (candidate) => this.#ownership.workerIsIdle(candidate));
   }
-  #assertHostToWorkerMessageWithinLimit(workflowId, message, worker) {
-    const failure = this.#protocolGuard.validateHostToWorkerMessage(message);
-    if (!failure)
-      return !0;
-    if (worker) {
-      this.#discardWorkerAndFailWorkflows(worker, {
-        targetWorkflowId: workflowId,
-        targetCategory: failure.failureCategory,
-        targetError: failure.error,
-        otherCategory: "system",
-        otherError: `Worker discarded after protocol send failure for workflow: ${workflowId}`
-      });
-      return !1;
-    }
-    this.#emit({
-      type: "failed",
-      workflowId,
-      error: failure.error,
-      failureCategory: failure.failureCategory
-    });
-    return !1;
-  }
-  #acceptWorkerMessage(worker, message) {
-    const result = this.#protocolGuard.acceptWorkerMessage(worker, message);
-    if (result.accepted)
-      return !0;
-    this.#discardWorkerAndFailWorkflows(worker, {
-      ...result.failure.targetWorkflowId === void 0 ? {} : { targetWorkflowId: result.failure.targetWorkflowId },
-      targetCategory: result.failure.failureCategory,
-      targetError: result.failure.error,
-      otherCategory: "system",
-      otherError: result.failure.otherError
-    });
-    return !1;
-  }
-  #handleTurnTimeout(turn) {
-    this.#discardWorkerAndFailWorkflows(turn.worker, {
-      targetWorkflowId: turn.workflowId,
-      targetCategory: "timeout",
-      targetError: `Worker workflow turn timed out after ${turn.timeoutMs}ms`,
-      otherCategory: "timeout",
-      otherError: `Worker discarded after workflow turn timed out: ${turn.workflowId}`
-    });
-  }
-  #discardWorkerAndFailWorkflows(worker, options) {
-    const workflowIds = this.#ownership.workflowIdsForWorker(worker);
-    if (workflowIds.length === 0) {
-      this.#turnWatchdog.clear(worker);
-      this.#forwardedLogGate.forget(worker);
-      return;
-    }
-    for (const workflowId of workflowIds) {
-      const isTarget = workflowId === options.targetWorkflowId;
-      this.#ownership.forgetWorkflow(workflowId);
-      this.#checkpointResumeState.forgetWorkflowIfClosed(workflowId, !0);
-      if (isTarget && options.skipTarget)
-        continue;
-      this.#emit({
-        type: "failed",
-        workflowId,
-        error: isTarget ? options.targetError ?? options.otherError : options.otherError,
-        failureCategory: isTarget ? options.targetCategory ?? options.otherCategory : options.otherCategory
-      });
-    }
-    this.#turnWatchdog.clear(worker);
-    this.#forwardedLogGate.forget(worker);
-    this.#workerListeners.detach(worker);
-    this.#pool.discard(worker);
-  }
   #handleBroadcastMessage(data) {
     if (data.type === "signal:received" && typeof data.workflowId === "string") {
       const targetWorker = this.#ownership.getTargetWorker(data.workflowId);
@@ -362,4 +333,15 @@ export class WorkerExecutionStrategy {
     if (result instanceof Promise)
       result.catch(() => {});
   }
+  static #buildRealmReadiness(requireRealmReady, getExpectedWorkflowTypes, timeoutMs, maxProtocolMessageBytes) {
+    if (!requireRealmReady)
+      return null;
+    if (!getExpectedWorkflowTypes)
+      throw Error("WorkerExecutionStrategyOptions.getExpectedWorkflowTypes is required when requireRealmReady is true");
+    return new WorkerRealmReadiness({
+      getExpectedWorkflowTypes,
+      timeoutMs,
+      maxProtocolMessageBytes
+    });
+  }
 }

package/dist/core/worker-fault-handling.d.ts

@@ -0,0 +1,45 @@
+import type { WorkerPool } from '../workers/pool.ts';
+import type { FailureCategory, WorkerInboundMessage, WorkerOutboundMessage } from './types.ts';
+import type { WorkerCheckpointResumeState } from './worker-checkpoint-resume-state.ts';
+import type { WorkerExecutionOwnership } from './worker-execution-ownership.ts';
+import type { WorkerListenerRegistry } from './worker-listener-registry.ts';
+import type { ForwardedLogGate } from './worker-log-abuse-counter.ts';
+import type { WorkerProtocolGuard } from './worker-protocol-guard.ts';
+import type { WorkerRealmReadiness } from './worker-realm-readiness.ts';
+import type { WorkerTurnState, WorkerTurnWatchdog } from './worker-turn-watchdog.ts';
+export interface WorkerFaultHandlerDependencies {
+    ownership: WorkerExecutionOwnership;
+    checkpointResumeState: WorkerCheckpointResumeState;
+    turnWatchdog: WorkerTurnWatchdog;
+    forwardedLogGate: ForwardedLogGate;
+    realmReadiness: WorkerRealmReadiness | null;
+    workerListeners: WorkerListenerRegistry;
+    protocolGuard: WorkerProtocolGuard;
+    pool: WorkerPool;
+    emit: (message: WorkerOutboundMessage) => void;
+}
+export interface WorkerDiscardOptions {
+    targetWorkflowId?: string;
+    targetCategory?: FailureCategory;
+    targetError?: string;
+    skipTarget?: boolean;
+    otherCategory: FailureCategory;
+    otherError: string;
+}
+/**
+ * Owns every path that ends in a worker being discarded and its owned
+ * workflows failed: protocol violations, turn timeouts, worker crashes, and
+ * (WFT-28) realm-ready handshake failures. Extracted from
+ * {@link WorkerExecutionStrategy} to keep that file under the repository's
+ * file-size ceiling; every method here previously lived as a private method
+ * on that class and is unchanged in behavior.
+ */
+export declare class WorkerFaultHandler {
+    #private;
+    constructor(dependencies: WorkerFaultHandlerDependencies);
+    assertHostToWorkerMessageWithinLimit(workflowId: string, message: WorkerInboundMessage, worker?: Worker): boolean;
+    acceptWorkerMessage(worker: Worker, message: unknown): message is WorkerOutboundMessage;
+    handleTurnTimeout(turn: WorkerTurnState): void;
+    handleWorkerError(worker: Worker, errorEvent: ErrorEvent): void;
+    discardWorkerAndFailWorkflows(worker: Worker, options: WorkerDiscardOptions): void;
+}

package/dist/core/worker-fault-handling.js

@@ -0,0 +1,88 @@
+export class WorkerFaultHandler {
+  #dependencies;
+  constructor(dependencies) {
+    this.#dependencies = dependencies;
+  }
+  assertHostToWorkerMessageWithinLimit(workflowId, message, worker) {
+    const failure = this.#dependencies.protocolGuard.validateHostToWorkerMessage(message);
+    if (!failure)
+      return !0;
+    if (worker) {
+      this.discardWorkerAndFailWorkflows(worker, {
+        targetWorkflowId: workflowId,
+        targetCategory: failure.failureCategory,
+        targetError: failure.error,
+        otherCategory: "system",
+        otherError: `Worker discarded after protocol send failure for workflow: ${workflowId}`
+      });
+      return !1;
+    }
+    this.#dependencies.emit({
+      type: "failed",
+      workflowId,
+      error: failure.error,
+      failureCategory: failure.failureCategory
+    });
+    return !1;
+  }
+  acceptWorkerMessage(worker, message) {
+    const result = this.#dependencies.protocolGuard.acceptWorkerMessage(worker, message);
+    if (result.accepted)
+      return !0;
+    this.discardWorkerAndFailWorkflows(worker, {
+      ...result.failure.targetWorkflowId === void 0 ? {} : { targetWorkflowId: result.failure.targetWorkflowId },
+      targetCategory: result.failure.failureCategory,
+      targetError: result.failure.error,
+      otherCategory: "system",
+      otherError: result.failure.otherError
+    });
+    return !1;
+  }
+  handleTurnTimeout(turn) {
+    this.discardWorkerAndFailWorkflows(turn.worker, {
+      targetWorkflowId: turn.workflowId,
+      targetCategory: "timeout",
+      targetError: `Worker workflow turn timed out after ${turn.timeoutMs}ms`,
+      otherCategory: "timeout",
+      otherError: `Worker discarded after workflow turn timed out: ${turn.workflowId}`
+    });
+  }
+  handleWorkerError(worker, errorEvent) {
+    this.discardWorkerAndFailWorkflows(worker, {
+      targetCategory: "system",
+      targetError: `Worker crashed: ${errorEvent.message ?? "unknown error"}`,
+      otherCategory: "system",
+      otherError: `Worker crashed: ${errorEvent.message ?? "unknown error"}`
+    });
+  }
+  discardWorkerAndFailWorkflows(worker, options) {
+    const { ownership } = this.#dependencies, workflowIds = ownership.workflowIdsForWorker(worker);
+    if (workflowIds.length === 0) {
+      this.#clearWorkerState(worker);
+      return;
+    }
+    for (const workflowId of workflowIds)
+      this.#failOwnedWorkflow(workflowId, workflowId === options.targetWorkflowId, options);
+    this.#clearWorkerState(worker);
+    this.#dependencies.workerListeners.detach(worker);
+    this.#dependencies.pool.discard(worker);
+  }
+  #failOwnedWorkflow(workflowId, isTarget, options) {
+    const { ownership, checkpointResumeState } = this.#dependencies;
+    ownership.forgetWorkflow(workflowId);
+    checkpointResumeState.forgetWorkflowIfClosed(workflowId, !0);
+    if (isTarget && options.skipTarget)
+      return;
+    this.#dependencies.emit({
+      type: "failed",
+      workflowId,
+      error: isTarget ? options.targetError ?? options.otherError : options.otherError,
+      failureCategory: isTarget ? options.targetCategory ?? options.otherCategory : options.otherCategory
+    });
+  }
+  #clearWorkerState(worker) {
+    this.#dependencies.turnWatchdog.clear(worker);
+    this.#dependencies.forwardedLogGate.forget(worker);
+    this.#dependencies.realmReadiness?.forget(worker);
+  }
+}

package/dist/core/worker-protocol.d.ts

@@ -2,10 +2,27 @@ import type { ContextOperationRequest } from './context.ts';
 import type { FailureCategory, OperationRequest, WorkerOutboundMessage } from './types.ts';
 import { type WorkerReplayOperationSignature } from './types/checkpoint.ts';
 export { WORKER_REPLAY_SIGNATURE_FORMAT, type WorkerReplayOperationSignature, } from './types/checkpoint.ts';
-export declare const WORKER_PROTOCOL_VERSION = 1;
+/**
+ * Bumped 1 -> 2 for the realm-ready handshake (WFT-28): a worker realm must
+ * now send a `ready` message before its first turn, a required pre-turn
+ * message the wire semantics didn't previously have. Host and worker are
+ * always built from the same package version — there is no independent peer
+ * to stay backward compatible with — so this is a clean-break bump, the same
+ * reasoning the RemoteWorker protocol v2 -> v3 bump used.
+ */
+export declare const WORKER_PROTOCOL_VERSION = 2;
 export declare const DEFAULT_WORKER_TURN_TIMEOUT_MS = 1000;
 export declare const DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES = 1048576;
 export declare const MIN_WORKER_PROTOCOL_MESSAGE_BYTES = 4096;
+/**
+ * Default bound (ms) on how long the host waits for a freshly acquired
+ * worker's `ready` handshake message before discarding it (WFT-28). Worker boot
+ * is module load plus evaluation with no I/O, but a cold Bun Worker spinning
+ * up a large bundled module graph can take meaningfully longer than a single
+ * workflow turn, so this is deliberately more generous than
+ * {@link DEFAULT_WORKER_TURN_TIMEOUT_MS}.
+ */
+export declare const DEFAULT_WORKER_REALM_READY_TIMEOUT_MS = 5000;
 /**
  * Default fixed-window length (ms) for the forwarded-log flood budget (#545). Paired
  * with {@link DEFAULT_FORWARDED_LOG_FLOOD_THRESHOLD} over this window.

package/dist/core/worker-protocol.js

@@ -7,7 +7,7 @@ import { isValidWorkerLogRecord } from "./worker-protocol-log.js";
 export {
   WORKER_REPLAY_SIGNATURE_FORMAT
 } from "./types/checkpoint.js";
-export const WORKER_PROTOCOL_VERSION = 1, DEFAULT_WORKER_TURN_TIMEOUT_MS = 1000, DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES = 1048576, MIN_WORKER_PROTOCOL_MESSAGE_BYTES = 4096, DEFAULT_FORWARDED_LOG_FLOOD_WINDOW_MS = 60000, DEFAULT_FORWARDED_LOG_FLOOD_THRESHOLD = 5000, FORWARDED_LOG_STRIKE_THRESHOLD = 5;
+export const WORKER_PROTOCOL_VERSION = 2, DEFAULT_WORKER_TURN_TIMEOUT_MS = 1000, DEFAULT_WORKER_PROTOCOL_MESSAGE_BYTES = 1048576, MIN_WORKER_PROTOCOL_MESSAGE_BYTES = 4096, DEFAULT_WORKER_REALM_READY_TIMEOUT_MS = 5000, DEFAULT_FORWARDED_LOG_FLOOD_WINDOW_MS = 60000, DEFAULT_FORWARDED_LOG_FLOOD_THRESHOLD = 5000, FORWARDED_LOG_STRIKE_THRESHOLD = 5;
 const BINARY_MARKER = "__weftBinaryBytes", DATE_MARKER = "__weftDate", ERROR_MARKER = "__weftError", MAP_MARKER = "__weftMap", SET_MARKER = "__weftSet", MAX_BOUNDED_ERROR_LENGTH = 512, WORKER_SIGNATURE_EXCLUDED_FIELDS = new Set([
   "attempt",
   "callerStack",

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;
+}