@lostgradient/weft 0.18.0 → 0.20.0

package/dist/cli/generated/operation-client.generated.d.ts

@@ -1,7 +1,7 @@
 import { type CatalogWeftClient, type WeftClientConnection } from '../operation-client-runtime.ts';
-export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type CatalogOperationName = (typeof CATALOG_OPERATION_NAMES)[number];
-export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.drain", "weft.workers.list", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type ClientOperationName = (typeof CLIENT_OPERATION_NAMES)[number];
 export declare const CLIENT_REST_OPERATION_BINDINGS: {
     readonly 'weft.tasks.diagnostics.deadletters.clear': {
@@ -304,7 +304,7 @@ export type ClientOperationTypes = {
                 readonly executionLatencyMs?: number;
                 readonly heartbeatAgeMs?: number;
                 readonly kind: 'stuck-queued' | 'stale-inflight' | 'retry-storm' | 'all-workers-at-capacity' | 'dead-lettered';
-                readonly lastRequeueReason?: 'visibility-timeout' | 'worker-disconnect';
+                readonly lastRequeueReason?: string;
                 readonly operationId?: string;
                 readonly queue?: string;
                 readonly queueLatencyMs?: number;
@@ -335,7 +335,14 @@ export type ClientOperationTypes = {
         readonly output: {
             readonly ok: boolean;
         };
-        readonly faults: never;
+        readonly faults: 'NotFound';
+    };
+    'weft.tasks.get': {
+        readonly input: {
+            readonly operationId: string;
+        };
+        readonly output: unknown;
+        readonly faults: 'NotFound';
     };
     'weft.updates.result.get': {
         readonly input: {
@@ -359,6 +366,15 @@ export type ClientOperationTypes = {
         readonly output: unknown;
         readonly faults: never;
     };
+    'weft.workers.diagnostics': {
+        readonly input: {
+            readonly workerId: string;
+        };
+        readonly output: {
+            readonly worker: unknown;
+        };
+        readonly faults: never;
+    };
     'weft.workers.drain': {
         readonly input: {
             readonly reason?: string;
@@ -376,7 +392,6 @@ export type ClientOperationTypes = {
                 readonly deploymentName: unknown;
                 readonly drainedWorkers: number;
                 readonly drainingWorkers: number;
-                readonly gitSha: unknown;
                 readonly health: 'active' | 'draining' | 'drained';
                 readonly inFlight: number;
                 readonly oldestStartedAt: unknown;
@@ -391,7 +406,6 @@ export type ClientOperationTypes = {
                 readonly concurrency: number;
                 readonly connectedAt: number;
                 readonly deploymentName?: string;
-                readonly gitSha?: string;
                 readonly health: 'active' | 'draining' | 'drained';
                 readonly heartbeatAgeMs: number;
                 readonly id: string;
@@ -405,6 +419,23 @@ export type ClientOperationTypes = {
         };
         readonly faults: never;
     };
+    'weft.workers.rejections': {
+        readonly input: {
+            readonly limit: number;
+        };
+        readonly output: {
+            readonly items: ReadonlyArray<{
+                readonly buildId?: string;
+                readonly code: 'invalid_registration' | 'unsupported_protocol_version' | 'deployment_conflict' | 'registration_rejected';
+                readonly deploymentName?: string;
+                readonly queue?: string;
+                readonly rejectedAt: number;
+                readonly workerId?: string;
+            }>;
+            readonly limit: number;
+        };
+        readonly faults: never;
+    };
     'weft.workers.resume': {
         readonly input: {
             readonly workerId: string;

package/dist/cli/generated/operation-client.generated.js

@@ -25,11 +25,14 @@ export const CATALOG_OPERATION_NAMES = [
   "weft.system.registry",
   "weft.task.queues.list",
   "weft.tasks.diagnostics",
+  "weft.tasks.get",
   "weft.updates.result.get",
   "weft.worker.deployments.drain",
   "weft.worker.deployments.resume",
+  "weft.workers.diagnostics",
   "weft.workers.drain",
   "weft.workers.list",
+  "weft.workers.rejections",
   "weft.workers.resume",
   "weft.workflows.activities.pending.list",
   "weft.workflows.aggregate",
@@ -88,11 +91,14 @@ export const CATALOG_OPERATION_NAMES = [
   "weft.task.queues.list",
   "weft.tasks.diagnostics",
   "weft.tasks.diagnostics.deadletters.clear",
+  "weft.tasks.get",
   "weft.updates.result.get",
   "weft.worker.deployments.drain",
   "weft.worker.deployments.resume",
+  "weft.workers.diagnostics",
   "weft.workers.drain",
   "weft.workers.list",
+  "weft.workers.rejections",
   "weft.workers.resume",
   "weft.workflows.activities.pending.list",
   "weft.workflows.aggregate",

package/dist/core/context/child-workflow-pipe.d.ts

@@ -9,7 +9,7 @@ export declare function normalizePipeStage(internals: ContextInternals, stage: W
 export declare function resolveChildWorkflowTarget<TInput = unknown, TOutput = unknown>(internals: ContextInternals, target: ChildWorkflowTarget<TInput, TOutput>): string;
 export declare function resolveMapConcurrency(totalItems: number, requestedConcurrency: number | undefined): number;
 export declare function createCompositionToken(internals: ContextInternals, kind: 'map' | 'pipe' | 'reduce'): string;
-export declare function createCompositionChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options?: AwaitChildWorkflowOptions | undefined): AwaitChildWorkflowOptions;
+export declare function createCompositionChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options?: AwaitChildWorkflowOptions): AwaitChildWorkflowOptions;
 export declare function createReduceChildWorkflowOptions(internals: ContextInternals, token: string, index: number, options: WorkflowReduceOptions | undefined): AwaitChildWorkflowOptions;
 export declare function primeParallelOperations(operations: Generator<ContextOperationRequest, unknown, unknown>[]): ContextOperationRequest[];
 export declare function startChild<TResult = unknown>(context: Context, internals: ContextInternals, workflowType: string, input: unknown, options?: ChildWorkflowOptions): Generator<ContextOperationRequest, TResult | ChildWorkflowHandle<TResult>, unknown>;

package/dist/core/context/child-workflow-pipe.js

@@ -27,7 +27,7 @@ export function resolveMapConcurrency(totalItems, requestedConcurrency) {
 export function createCompositionToken(internals, kind) {
   return `${kind}:${internals.stepIndex}`;
 }
-export function createCompositionChildWorkflowOptions(internals, token, index, options = void 0) {
+export function createCompositionChildWorkflowOptions(internals, token, index, options) {
   assertCompositionAwaitsChildWorkflow(options);
   if (options?.id !== void 0)
     return options;

package/dist/core/engine/construction.d.ts

@@ -51,6 +51,8 @@ export declare function createExecutionStrategyBundle(parameters: {
     development: boolean;
     broadcastEvents: boolean;
     getRegistration: (workflowType: string) => RegistrationEntry | undefined;
+    /** Live accessor for registered workflow type names (WFT-28); registrations are still empty here. */
+    listRegisteredWorkflowTypes: () => Iterable<string>;
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;
     resolveWorkflowType: (target: string | Function) => string;
     registerCancelHandler?: (workflowId: string, handler: () => Promise<void> | void) => () => void;

package/dist/core/engine/construction.js

@@ -187,6 +187,7 @@ export function createExecutionStrategyBundle(parameters) {
     development,
     broadcastEvents,
     getRegistration,
+    listRegisteredWorkflowTypes,
     getComposedWorkflowInterceptor,
     resolveWorkflowType,
     registerCancelHandler,
@@ -203,6 +204,8 @@ export function createExecutionStrategyBundle(parameters) {
       broadcastEvents,
       requireProtocolVersion: workerExecutionConfiguration.requireProtocolVersion,
       discardOnCancel: workerExecutionConfiguration.discardOnCancel,
+      requireRealmReady: !0,
+      getExpectedWorkflowTypes: () => [...listRegisteredWorkflowTypes()],
       workflowTurnTimeoutMs: workerExecutionConfiguration.workflowTurnTimeoutMs,
       maxProtocolMessageBytes: workerExecutionConfiguration.maxProtocolMessageBytes,
       getNow,

package/dist/core/engine/index.js

@@ -280,6 +280,7 @@ export class Engine extends EventTarget {
       development: resolvedOptions.development,
       broadcastEvents: resolvedOptions.broadcastEvents,
       getRegistration: getInternals(this).registrations.get.bind(getInternals(this).registrations),
+      listRegisteredWorkflowTypes: () => getInternals(this).registrations.keys(),
       getComposedWorkflowInterceptor: () => getComposedWorkflowInterceptor(getInternals(this)),
       resolveWorkflowType: this.#resolveWorkflowTypeTarget.bind(this),
       registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler),

package/dist/core/engine/listing.d.ts

@@ -3,6 +3,7 @@ import type { EngineInternals } from './internals.ts';
 export declare const BULK_OPERATION_BATCH_SIZE = 1000;
 /** List workflow summaries that match a filter, using indexes when available. */
 export declare function list(internals: EngineInternals, filter?: ListFilter, options?: ListOptions): Promise<PaginatedResult<WorkflowSummary>>;
+export declare function assertWorkflowListScanWithinCap(scannedRows: number): void;
 /** Stream decoded workflow states that match a list filter. */
 export declare function streamWorkflowStates(internals: EngineInternals, filter?: ListFilter): AsyncGenerator<WorkflowState>;
 /** Stream decoded workflow states in fixed-size batches for bulk operations. */

package/dist/core/engine/listing.js

@@ -25,8 +25,7 @@ export async function list(internals, filter, options) {
 }
 async function collectSummariesFromConstrainedIds(internals, constrainedIds, normalizedFilter, normalizedTagFilters, options) {
   const orderedIds = [...constrainedIds];
-  if (orderedIds.length > MAX_LIST_SCAN_ROWS)
-    throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+  assertWorkflowListScanWithinCap(orderedIds.length);
   const items = [];
   for (let start = 0;start < orderedIds.length; start += CONSTRAINED_ID_CHUNK_SIZE) {
     const chunkIds = orderedIds.slice(start, start + CONSTRAINED_ID_CHUNK_SIZE), chunkBytes = await Promise.all(chunkIds.map((workflowId) => internals.storage.get(KEYS.workflow(workflowId)))), searchAttributesByWorkflowId = await readSearchAttributesForStates(internals, chunkBytes, normalizedFilter), matchingStates = [];
@@ -49,8 +48,7 @@ async function collectSummariesFromFullScan(internals, normalizedFilter, normali
     if (!isTopLevelWorkflowStateKey(key))
       continue;
     scanned += 1;
-    if (scanned > MAX_LIST_SCAN_ROWS)
-      throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+    assertWorkflowListScanWithinCap(scanned);
     const state = decodeWorkflowState(value), searchAttributes = await readSearchAttributesForFilter(internals, state.id, normalizedFilter);
     if (!matchesListFilter(state, normalizedFilter, null, normalizedTagFilters, searchAttributes))
       continue;
@@ -59,6 +57,10 @@ async function collectSummariesFromFullScan(internals, normalizedFilter, normali
   }
   return items;
 }
+export function assertWorkflowListScanWithinCap(scannedRows) {
+  if (scannedRows > MAX_LIST_SCAN_ROWS)
+    throw new WorkflowListScanCapExceededError(MAX_LIST_SCAN_ROWS);
+}
 async function summariesFromStates(internals, states, options) {
   const attributeBytesByWorkflowId = new Map;
   await Promise.all(states.map(async (state) => {

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