@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -1,11 +1,13 @@
 import type { AlertStateSnapshot } from '../../alerting/types.ts';
 import { type Storage as WeftStorage } from '../../storage/interface.ts';
 import { type ActivityMetadata, type ActivityRegistrationOptions, type RegisteredActivityFunction } from '../activity-registry.ts';
+import type { WorkflowRevisionRecord } from '../catalog/index.ts';
 import type { StoredStreamChunk } from '../context.ts';
 import type { TypedEventTarget, WeftEventMap } from '../events.ts';
 import type { Interceptor } from '../interceptor.ts';
 import { type ReviewRequest } from '../review/index.ts';
 import { Scheduler } from '../scheduler.ts';
+import type { WorkflowSourceHandle } from '../source/index.ts';
 import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PendingAsyncActivityListOptions, type PendingAsyncActivityPage, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type ScheduleUpdateOptions, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOrSignalOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowFinalizerStatus, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowScheduleProvenance, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
 import type { TimerEntry } from '../types/checkpoint.ts';
 import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
@@ -14,29 +16,38 @@ import { type EmptyActivityDefinitions, type EmptyWorkflowDefinitions, type Know
 import { type ActivityDefinitionName, type EngineCreateOptions, type EngineCreateWorkflowRegistry, type RegisteredActivityDefinitionExecute, type UnknownWorkflowNameWhenDefaultRegistryIsEmpty } from './engine-create-types.ts';
 import type { EngineConstructorOptions } from './engine-internal-types.ts';
 import type { EngineStateNamespace } from './engine-state-namespace.ts';
+import { type EngineWorkflowsNamespace } from './engine-workflows-namespace.ts';
 import { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 import { ENGINE_LEASE_LOST_WARNING_NAME } from './lease-deposition.ts';
 import type { EngineLeaseHealth } from './lease-health.ts';
 import { type RecoverAllOptions, type StartOrSignalResult } from './lifecycle.ts';
 import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
 import { ScheduleHandle } from './schedule-handle.ts';
+import { type ResolveWorkflowSourceOptions } from './source-resolution.ts';
 import { type WorkflowFeedListener, type WorkflowFeedRecord, type WorkflowFeedSelector } from './workflow-feed.ts';
+export type { WorkflowRevisionReferenceCounts } from '../catalog/index.ts';
 export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, } from './activity-reconciliation.ts';
 export { AsyncActivityTokenNotFoundError } from './async-activity-completion.ts';
 export type { PendingAsyncActivity } from './async-activity-records.ts';
+export { getWorkflowRevisionDiagnostics, removeWorkflowRevision, type WorkflowCatalogRemovalResult, type WorkflowRevisionDiagnostics, } from './catalog-removal.ts';
+export { DynamicWorkflowSourceUnavailableError, WorkflowSourceNotRegisteredError, } from './dynamic-source-errors.ts';
 export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
 export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposalError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataCorruptError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
+export { getWorkflowCatalog } from './internals.ts';
 export { WeftWorkflowClaimLostWarning, WeftWorkflowWakeDiscardedWarning, WORKFLOW_CLAIM_LOST_WARNING_NAME, WORKFLOW_WAKE_DISCARDED_WARNING_NAME, } from './lease-deposition.ts';
 export type { WorkflowWakeKind } from './lease-deposition.ts';
 export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, OwnershipModeMismatchError, WorkflowClaimUnavailableError, } from './lease-errors.ts';
 export type { EngineLeaseHealth, LeaseLostReason } from './lease-health.ts';
 export type { RecoverAllOptions, RecoveredWorkflowInfo } from './lifecycle.ts';
+export { WorkflowRevisionUnavailableError } from './revision-errors.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
+export type { ResolveWorkflowSourceOptions } from './source-resolution.ts';
 export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
 export type { EngineCreateOptions } from './engine-create-types.ts';
 export { clearEngineLeakWarningTokenForTesting, getEngineLeakCollectionCountForTesting, hasEngineLeakWarningTokenForTesting, setEngineLeakWarningOverrideForTesting, setNextEngineLeakWarningTokenForTesting, shouldEmitEngineLeakWarningForTesting, } from './engine-leak-warnings.ts';
 export type { EngineStateNamespace } from './engine-state-namespace.ts';
+export type { ActivateWorkflowRevisionOptions, EngineWorkflowsNamespace, } from './engine-workflows-namespace.ts';
 export { assertCompatiblePersistedDataVersion };
 export declare const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING: unique symbol;
 export declare const ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING: unique symbol;
@@ -172,6 +183,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     removeEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
     removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     get state(): EngineStateNamespace;
+    get workflows(): EngineWorkflowsNamespace;
     /** Return detached snapshots of the alert rules that are currently firing. */
     getActiveAlerts(): readonly AlertStateSnapshot[];
     /**
@@ -212,6 +224,50 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
         readonly execute: RegisteredActivityDefinitionExecute<TActivities, TName>;
     }): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
     register<TDefinition extends AnyActivityDefinition>(definition: ActivityDefinitionName<TDefinition> extends Extract<keyof TActivities, string> ? never : TDefinition): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
+    /**
+     * Record `source` as a lazily-resolvable dynamic workflow source
+     * (WFT-13/14): synchronous, and it never invokes `source.load` — it only
+     * records a catalog candidate keyed `(source.descriptor.name,
+     * source.descriptor.revision)`. Call `resolveWorkflowSource()` to
+     * actually load, validate, and install it. A workflow name may not be
+     * both eagerly registered (`engine.register()`) and a dynamic source;
+     * registering the identical `source` reference twice for the same
+     * `(name, revision)` is idempotent.
+     *
+     * @example
+     * ```ts
+     * import { Engine, workflowSource } from '@lostgradient/weft';
+     *
+     * declare const loadCheckout: () => Promise<{
+     *   checkout: import('@lostgradient/weft').WorkflowDefinition<unknown, unknown, 'checkout'>;
+     * }>;
+     * const engine = new Engine();
+     * engine.registerSource(
+     *   workflowSource(
+     *     { name: 'checkout', location: './checkout.ts', exportName: 'checkout', revision: 'r1' },
+     *     loadCheckout,
+     *   ),
+     * );
+     * ```
+     */
+    registerSource(source: WorkflowSourceHandle): void;
+    /**
+     * Load, validate, and install one dynamic workflow source revision
+     * previously recorded via {@link Engine.registerSource}. Single-flight
+     * per `(name, revision)`: concurrent callers for the same key share one
+     * loader invocation. Does not wire `engine.start()` or recovery to await
+     * resolution — that is a later batch's job (WFT-15).
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * declare const engine: Engine;
+     * const record = await engine.resolveWorkflowSource('checkout', 'r1');
+     * console.log(record.manifest.revision);
+     * ```
+     */
+    resolveWorkflowSource(name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;
     /**
      * Register every workflow from an object map at once and return a typed
      * engine view that exposes the newly added workflow names.
@@ -244,6 +300,41 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     listWorkflowDefinitions(): RegisteredWorkflowDefinition[];
     getActivityDefinition(name: string): ActivityMetadata | undefined;
     listActivityDefinitions(): ActivityMetadata[];
+    /**
+     * Resolve one activity's catalog metadata against the EAGER per-workflow
+     * `.activities({...})` registry only, falling back to the global registry
+     * — never a `registerSource()`-registered type's dynamic-source revision,
+     * resolved or not (WFT-19: `internals.activityRegistriesByWorkflow` is
+     * eager-only as of this batch; a dynamic-source workflow's own activity
+     * dispatch resolves via the running instance's exact `(type, revision)`
+     * pin instead, in `activity-resolution.ts`, which this synchronous,
+     * type-only accessor has no instance to pin against). Build tooling
+     * (`buildWorkerManifestFromRegistry`) uses this so a workflow-scoped
+     * activity's schema, not a same-named global activity's, feeds its
+     * `contractHash` when both are registered.
+     */
+    getWorkflowActivityDefinition(workflowType: string, activityName: string): ActivityMetadata | undefined;
+    /**
+     * List every activity definition registered on this workflow's own
+     * per-workflow `.activities({...})` registry — name, schema, description,
+     * tags, retry/timeout metadata, never a handler function. Returns an
+     * empty array for a workflow with no `.activities({...})` step (including
+     * an unknown `workflowType`), never `undefined`, so a caller can fold the
+     * result straight into a contract without an existence check first.
+     *
+     * Companion to {@link getWorkflowActivityDefinition}: that resolves one
+     * activity by name with the per-workflow-first, global-fallback dispatch
+     * order; this enumerates only the names the EAGER per-workflow registry
+     * itself declares — activities a workflow reaches solely through the
+     * global registry are deliberately excluded, and so (as of WFT-19) is
+     * every `registerSource()`-registered type regardless of whether a
+     * revision has been resolved (see {@link getWorkflowActivityDefinition}'s
+     * doc). Build tooling that needs a workflow's full scoped-activity
+     * contract set (`buildRegistrySnapshot`,
+     * `worker/manifest/registry-contract-builder.ts`) uses this instead of
+     * reaching into engine internals directly.
+     */
+    listWorkflowActivityDefinitions(workflowType: string): ActivityMetadata[];
     start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartWorkflowOptions<WorkflowServices<TWorkflows, TName>>): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
     start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
     /**

package/dist/core/engine/index.js

@@ -47,6 +47,7 @@ import {
   createUpdateCallbacks as createUpdateCallbacksForEngine
 } from "./callback-creators.js";
 import { registerCancelHandler } from "./cancel-handlers.js";
+import { ensureWorkflowCatalogReady, isWorkflowCatalogReady } from "./catalog-readiness.js";
 import {
   getCheckpointAt as getCheckpointStateAt,
   getEvents as getWorkflowEvents,
@@ -65,6 +66,10 @@ import {
   typedEngineView
 } from "./construction.js";
 import { disposeEngine } from "./disposal.js";
+import {
+  canResolveRevisionLocally,
+  getResolvedDynamicRegistration
+} from "./dynamic-source-execution.js";
 import {
   consumeNextEngineLeakWarningTokenForTesting,
   engineCleanupIntervalFinalizer
@@ -78,6 +83,9 @@ import {
   shouldStartEngineScheduler,
   validateEngineCreateBackgroundTaskOptions
 } from "./engine-runtime-helpers.js";
+import {
+  createEngineWorkflowsNamespace
+} from "./engine-workflows-namespace.js";
 import {
   EngineCreateNameMismatchError,
   EngineDisposalError,
@@ -167,6 +175,11 @@ import {
   releaseSignalWaiter,
   signal as signalWorkflow
 } from "./signals.js";
+import { registerSource as registerWorkflowSource } from "./source-registration.js";
+import {
+  resolveWorkflowSource as resolveWorkflowSourceImpl
+} from "./source-resolution.js";
+import { createWorkflowSourceRuntimeState } from "./source-runtime-state.js";
 import {
   loadScheduleState,
   loadWorkflowState,
@@ -204,6 +217,14 @@ export {
   ActivityReconciliationIndeterminateError
 } from "./activity-reconciliation.js";
 export { AsyncActivityTokenNotFoundError } from "./async-activity-completion.js";
+export {
+  getWorkflowRevisionDiagnostics,
+  removeWorkflowRevision
+} from "./catalog-removal.js";
+export {
+  DynamicWorkflowSourceUnavailableError,
+  WorkflowSourceNotRegisteredError
+} from "./dynamic-source-errors.js";
 export {
   ActivityResolutionError,
   BulkDeleteRequiresTerminalWorkflowsError,
@@ -224,6 +245,7 @@ export {
   WorkflowTypeNotRegisteredForRecoveryError
 } from "./errors.js";
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
+export { getWorkflowCatalog } from "./internals.js";
 export {
   WeftWorkflowClaimLostWarning,
   WeftWorkflowWakeDiscardedWarning,
@@ -237,6 +259,7 @@ export {
   OwnershipModeMismatchError,
   WorkflowClaimUnavailableError
 } from "./lease-errors.js";
+export { WorkflowRevisionUnavailableError } from "./revision-errors.js";
 export { ScheduleHandle } from "./schedule-handle.js";
 export {
   clearEngineLeakWarningTokenForTesting,
@@ -257,7 +280,8 @@ function scheduleDefinitionFromInternals(internals, definition) {
     ...definition.description !== void 0 && { description: definition.description },
     ...definition.overlapPolicy !== void 0 && { overlap: definition.overlapPolicy },
     ...definition.backfill !== void 0 && { backfill: definition.backfill },
-    ...definition.jitter !== void 0 && { jitter: definition.jitter }
+    ...definition.jitter !== void 0 && { jitter: definition.jitter },
+    ...definition.revisionPolicy !== void 0 && { revisionPolicy: definition.revisionPolicy }
   });
 }
 
@@ -282,6 +306,8 @@ export class Engine extends EventTarget {
       }
       await engine.#bootstrapOwnershipIfConfigured();
       await engine.#acquireLeaseIfConfigured();
+      if (!isWorkflowCatalogReady(engine))
+        await ensureWorkflowCatalogReady(engine);
       if (options.recover !== !1)
         await engine.recoverAll(options.acknowledgeUnknownWorkflowTypes !== void 0 ? { acknowledgeUnknownWorkflowTypes: options.acknowledgeUnknownWorkflowTypes } : {});
       if (shouldStartEngineScheduler(options, getInternals(engine).options.backgroundTaskMode))
@@ -303,8 +329,11 @@ export class Engine extends EventTarget {
       maxNestingDepth: resolvedOptions.maxNestingDepth,
       development: resolvedOptions.development,
       broadcastEvents: resolvedOptions.broadcastEvents,
-      getRegistration: getInternals(this).registrations.get.bind(getInternals(this).registrations),
-      listRegisteredWorkflowTypes: () => getInternals(this).registrations.keys(),
+      getRegistration: (workflowType, workflowId) => getResolvedDynamicRegistration(getInternals(this), workflowType, getInternals(this).workflowTypeByWorkflowId.get(workflowId)?.revision),
+      listRegisteredWorkflowTypes: () => new Set([
+        ...getInternals(this).registrations.keys(),
+        ...getInternals(this).sources.lastResolvedRevisionByName.keys()
+      ]).values(),
       getComposedWorkflowInterceptor: () => getComposedWorkflowInterceptor(getInternals(this)),
       resolveWorkflowType: this.#resolveWorkflowTypeTarget.bind(this),
       registerCancelHandler: (workflowId, handler) => registerCancelHandler(getInternals(this), workflowId, handler),
@@ -424,6 +453,13 @@ export class Engine extends EventTarget {
     getInternals(this).activityWorkerDispatcher = createActivityWorkerDispatcher(options?.activityExecution);
     getInternals(this).strategy.onMessage(this.#handleStrategyMessage.bind(this));
     getInternals(this).alertManager = options?.alerts ? new AlertManager(this, options.alerts, getNow, resolvedOptions.backgroundTaskMode === "automatic") : null;
+    getInternals(this).workflowCatalog = null;
+    getInternals(this).pendingCatalogInstalls = [];
+    getInternals(this).catalogRestored = !1;
+    getInternals(this).catalogDrainPromise = null;
+    getInternals(this).registeredCatalogRevisions = new Map;
+    getInternals(this).inFlightStartsByRevision = new Map;
+    getInternals(this).sources = createWorkflowSourceRuntimeState();
     this.#ensureRetentionSweepInterval();
     this.#startSecondInstanceDetection();
   }
@@ -514,7 +550,7 @@ export class Engine extends EventTarget {
         getNow: internals.options.getNow,
         claimTtlMs: internals.options.workflowClaimTtlMs,
         claimRenewIntervalMs: internals.options.workflowClaimRenewIntervalMs,
-        isWorkflowTypeRegistered: (workflowType) => internals.workflowDefinitionsByName.has(workflowType),
+        isWorkflowTypeRegistered: (workflowType, revision) => canResolveRevisionLocally(internals, workflowType, revision),
         onWorkflowClaimReclaimed: async (workflowId) => {
           internals.inlineStrategy?.evictContextForReclaim(workflowId);
           internals.deliveredPendingUpdateIds.delete(workflowId);
@@ -675,6 +711,9 @@ export class Engine extends EventTarget {
       workflow: (workflowType, key, options) => new AtomicState(storage, KEYS.stateWorkflow(workflowType, key), options)
     };
   }
+  get workflows() {
+    return createEngineWorkflowsNamespace(this);
+  }
   getActiveAlerts() {
     return getInternals(this).alertManager?.activeStates ?? [];
   }
@@ -692,6 +731,12 @@ export class Engine extends EventTarget {
     registerWorkflow(getInternals(this), definition, this.#createRegistrationCallbacks());
     return typedEngineView(this);
   }
+  registerSource(source) {
+    registerWorkflowSource(getInternals(this), source);
+  }
+  async resolveWorkflowSource(name, revision, options) {
+    return resolveWorkflowSourceImpl(this, name, revision, options);
+  }
   registerWorkflows(workflows) {
     for (const [name, definition] of Object.entries(workflows)) {
       if (name !== definition.name)
@@ -730,14 +775,25 @@ export class Engine extends EventTarget {
   listActivityDefinitions() {
     return getInternals(this).activityRegistry.listDefinitions();
   }
+  getWorkflowActivityDefinition(workflowType, activityName) {
+    const internals = getInternals(this);
+    return internals.activityRegistriesByWorkflow.get(workflowType)?.getDefinition(activityName) ?? internals.activityRegistry.getDefinition(activityName);
+  }
+  listWorkflowActivityDefinitions(workflowType) {
+    return getInternals(this).activityRegistriesByWorkflow.get(workflowType)?.listDefinitions() ?? [];
+  }
   async start(type, input, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     if (options?.idempotencyKey !== void 0)
       return startWithIdempotencyFromLifecycle(getInternals(this), type, input, options, this.#createLifecycleCallbacks());
     return startWorkflowFromLifecycle(getInternals(this), type, input, options, void 0, this.#createLifecycleCallbacks());
   }
   async startOrSignal(type, input, signal, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return startOrSignalFromLifecycle(getInternals(this), type, input, signal, options, this.#createStartOrSignalCallbacks());
   }
   #createStartOrSignalCallbacks() {
@@ -810,6 +866,8 @@ export class Engine extends EventTarget {
   async schedule(typeOrDefinition, input, spec, options) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     if (typeof typeOrDefinition === "object")
       return scheduleDefinitionFromInternals(internals, typeOrDefinition);
     if (spec === void 0)
@@ -826,21 +884,29 @@ export class Engine extends EventTarget {
   async pauseSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return pauseScheduleFromInternals(internals, scheduleId);
   }
   async resumeSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return resumeScheduleFromInternals(internals, scheduleId);
   }
   async cancelSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return cancelScheduleFromInternals(internals, scheduleId);
   }
   async updateSchedule(scheduleId, newSpec, options) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return updateScheduleFromInternals(internals, scheduleId, newSpec, options);
   }
   [HANDLE_RESULT_PROMISE](workflowId) {
@@ -906,10 +972,14 @@ export class Engine extends EventTarget {
   }
   async fork(sourceWorkflowId, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return forkFromLifecycle(getInternals(this), sourceWorkflowId, options, this.#createLifecycleCallbacks());
   }
   async resume(workflowId) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return resumeFromLifecycle(getInternals(this), workflowId, this.#createLifecycleCallbacks());
   }
   async recoverAll(options) {
@@ -917,6 +987,8 @@ export class Engine extends EventTarget {
     await this.#acquireLeaseIfConfigured();
     if (getInternals(this).disposed)
       throw new EngineDisposedError;
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     await recoverPendingAsyncActivities(getInternals(this));
     await recoverOrphanedScheduleTimers(getInternals(this));
     getInternals(this).onRecoveredWorkflowHook = options?.onRecoveredWorkflow;
@@ -1082,7 +1154,7 @@ export class Engine extends EventTarget {
     if (leaseManager !== null && leaseManager.currentEpochBytes() !== null)
       process.emitWarning("engine ownership lease disposed synchronously; lease release is fire-and-forget, so exiting before the release completes can make the next instance wait for leaseTtl. Use await engine.shutdown(), await using, or await engine[Symbol.asyncDispose]() for prompt rolling-deploy handoff.", ENGINE_LEASE_SYNCHRONOUS_DISPOSE_WARNING_NAME);
     const { registry: workflowClaimRegistry } = this.#detachWorkflowClaimOwnership();
-    disposeEngine(getInternals(this));
+    disposeEngine(getInternals(this), (event) => this.dispatchEvent(event));
     if (this.#synchronousDisposeResult === null)
       this.#synchronousDisposeResult = leaseManager?.release() ?? Promise.resolve(!0);
     this.#synchronousDisposeResult;
@@ -1100,7 +1172,7 @@ export class Engine extends EventTarget {
         drainFailure = { error };
       } finally {
         const { registry: workflowClaimRegistry } = this.#detachWorkflowClaimOwnership();
-        disposeEngine(getInternals(this));
+        disposeEngine(getInternals(this), (event) => this.dispatchEvent(event));
         await getInternals(this).inFlightLeaseAcquire?.catch(() => {});
         leaseReleased = await (this.#synchronousDisposeResult ?? leaseManager?.release() ?? Promise.resolve(!0));
         await this.#releaseWorkflowClaimsBestEffort(workflowClaimRegistry);

package/dist/core/engine/inline-launch-queue.js

@@ -99,7 +99,7 @@ async function startQueuedInlineWorkflowExecution(internals, start, callbacks, o
       return;
     internals.queuedInlineWorkflowStartIds.delete(start.workflowId);
     internals.engine.dispatchEvent(new WorkflowStartedEvent(start.workflowId, start.workflowType, start.input));
-    startWorkflowExecution(internals, start.workflowId, state.workflowExecutionToken, start.workflowType, start.input, start.checkpoint, start.nestingDepth, start.executionDeadline, start.executionStateOwnerId);
+    startWorkflowExecution(internals, start.workflowId, state.workflowExecutionToken, start.workflowType, state.revision, start.input, start.checkpoint, start.nestingDepth, start.executionDeadline, start.executionStateOwnerId);
     if (options?.abortStartedWorkflows === !0)
       internals.inlineStrategy?.abortWorkflowAdvanceForShutdown(start.workflowId);
     else

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

@@ -34,13 +34,14 @@ import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
 import type { RecoveredWorkflowInfo } from './lifecycle/shared.ts';
 import type { ActivityHeartbeatKey } from './activity-heartbeat-tracking.ts';
-import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter } from './engine-internal-types.ts';
+import type { PendingTimelineEntry, QueuedInlineWorkflowExecutionStart, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowExecutionIdentity, WorkflowResultWaiter } from './engine-internal-types.ts';
 import type { EngineCleanupIntervalDisposalTracker } from './engine-leak-warnings.ts';
 import type { WorkflowHandle, WorkflowHandleEngine } from './handles.ts';
 import type { WorkflowFeedListener } from './index.ts';
 import type { LeaseManager } from './lease-manager.ts';
 import type { ScheduleHandleEngine } from './schedule-handle.ts';
 import type { SecondInstanceDetector } from './second-instance-detector.ts';
+import type { WorkflowSourceRuntimeState } from './source-runtime-state.ts';
 import type { WorkflowClaimMetricsRecorder } from './workflow-claim-metrics.ts';
 import type { WorkflowClaimRegistry } from './workflow-claim-registry.ts';
 import type { WorkflowClaimRenewalTask } from './workflow-claim-renewal-task.ts';
@@ -149,15 +150,15 @@ export interface EngineInternals {
     /**
      * Per-workflow activity registries built from
      * `workflow({ name }).activities({ ... }).execute(...)`, indexed by workflow
-     * type. Activity lookup is per-activity: it consults the workflow's
-     * `activityRegistriesByWorkflow.get(type)` registry first and, for any activity
-     * that registry does not contain, falls back to the engine-wide
-     * {@link EngineInternals.activityRegistry}. Both sources are first-class — a
-     * workflow can resolve some activities from its own `activities(...)` map and
-     * others (shared/globally-registered) from the global registry, and a workflow
-     * with no per-workflow map resolves entirely from the global one. Each
-     * per-workflow registry is a defensive deep clone+freeze of the workflow's
-     * `activities` map so post-registration mutation cannot reach the engine.
+     * type. Lookup consults `activityRegistriesByWorkflow.get(type)` first,
+     * falling back to {@link EngineInternals.activityRegistry} for any activity
+     * that registry lacks. Each entry is a defensive deep clone+freeze of the
+     * workflow's `activities` map. EAGER-ONLY as of WFT-19: only `registration.ts`
+     * writes here (never a `registerSource()` load), so a dynamic-source type's
+     * per-revision activities resolve instead via
+     * `internals.sources.resolved.get(type)?.get(revision)?.activityRegistry`
+     * (`activity-resolution.ts`), keyed by the running instance's own pin —
+     * never this type-only map, which would clobber across revisions.
      */
     activityRegistriesByWorkflow: Map<string, ActivityRegistry>;
     /**
@@ -169,12 +170,13 @@ export interface EngineInternals {
      */
     workflowDefinitionsByName: Map<string, object>;
     /**
-     * In-memory cache of `workflowId -> workflowType` populated when a workflow
-     * starts executing (see lifecycle/start-exec.ts) and cleared on terminal
-     * cleanup. Lets the activity-dispatch hot path resolve the correct
-     * per-workflow registry synchronously without re-reading storage.
+     * In-memory cache of `workflowId -> {type, revision}`, populated whenever a
+     * workflow begins executing in THIS process (fresh start, delayed-start
+     * fire, resume, recovery, workflow-lease reclaim redrive — WFT-19) and
+     * cleared on terminal cleanup. Lets the activity-dispatch hot path, and any
+     * other lookup needing an instance's own exact pin, resolve synchronously.
      */
-    workflowTypeByWorkflowId: Map<string, string>;
+    workflowTypeByWorkflowId: Map<string, WorkflowExecutionIdentity>;
     activityWorkerDispatcher: ActivityWorkerDispatcher | null;
     checkpoints: Map<string, Checkpoint>;
     broadcastChannel: BroadcastChannel | null;
@@ -386,6 +388,31 @@ export interface EngineInternals {
     workflowVisibilityWatermarkExpiresAt: number | undefined;
     pendingTimelineEntries: Map<string, PendingTimelineEntry>;
     pendingAtomicWorkflowCommitSideEffects: Map<string, import('./checkpoint-side-effects.ts').AtomicWorkflowCommitSideEffects>;
+    /**
+     * The durable workflow catalog (WFT-9/WFT-10), `null` until
+     * {@link import('./catalog-readiness.ts').ensureWorkflowCatalogReady} first
+     * restores it from storage. Read via {@link getWorkflowCatalog}, never
+     * directly.
+     */
+    workflowCatalog: import('../catalog/index.ts').WorkflowCatalog | null;
+    /** Workflow names `commitWorkflowDefinition` (`registration.ts`) has queued for catalog install+activate since the last drain — `engine.register()` stays synchronous (it cannot itself build a manifest) and defers to the next `ensureWorkflowCatalogReady` call. */
+    pendingCatalogInstalls: string[];
+    /** Whether {@link workflowCatalog} has been restored from storage at least once. */
+    catalogRestored: boolean;
+    /** The in-flight catalog restore-and-drain, or `null` when none is running; concurrent `ensureWorkflowCatalogReady` callers await this same promise rather than racing a second restore/drain. */
+    catalogDrainPromise: Promise<void> | null;
+    /** Name -> revision this process's own register()-drain most recently activated (WFT-12, `catalog-readiness.ts`). Process-local, never persisted. */
+    registeredCatalogRevisions: Map<string, string>;
+    /** Name -> revision -> in-flight `startWorkflow` count (WFT-12, `lifecycle/start.ts`). Process-local, never persisted. */
+    inFlightStartsByRevision: Map<string, Map<string, number>>;
+    /**
+     * Dynamic workflow sources (WFT-13/14, WFT-15/16): candidates, in-flight
+     * single-flight loads, per-caller waiter controllers, locally-resolved
+     * definitions, and bounded per-`(name, revision)` diagnostics — see
+     * {@link import('./source-runtime-state.ts').WorkflowSourceRuntimeState}
+     * for the full field-by-field breakdown. Process-local, never persisted.
+     */
+    sources: WorkflowSourceRuntimeState;
 }
 /**
  * Set up an empty `EngineInternals` skeleton in the WeakMap. The Engine
@@ -406,4 +433,16 @@ export declare function initializeInternals(engine: EngineRuntime): void;
  * internals existing.
  */
 export declare function getInternals(engine: object): EngineInternals;
+/**
+ * Read an engine's durable workflow catalog. Throws when it has not been
+ * restored yet — every public entry point that can observe catalog state
+ * (`start`, `startOrSignal`, `schedule`/`pauseSchedule`/`resumeSchedule`/
+ * `cancelSchedule`/`updateSchedule`, `fork`, `resume`, `recoverAll`,
+ * `Engine.create`, and `buildRegistrySnapshot`) awaits
+ * `ensureWorkflowCatalogReady(engine)` first, which restores it. Calling
+ * this before that await boundary — for example from a pathological
+ * direct-internals test — is a programming error, not a recoverable runtime
+ * condition, so it fails loud rather than returning a placeholder catalog.
+ */
+export declare function getWorkflowCatalog(engine: object): import('../catalog/index.ts').WorkflowCatalog;
 export {};

package/dist/core/engine/internals.js

@@ -9,3 +9,9 @@ export function getInternals(engine) {
     throw Error("Engine internals not initialized \u2014 initializeInternals(this) was not called in the Engine constructor");
   return internals;
 }
+export function getWorkflowCatalog(engine) {
+  const internals = getInternals(engine);
+  if (internals.workflowCatalog === null)
+    throw Error("Workflow catalog not restored \u2014 ensureWorkflowCatalogReady(engine) was not awaited before " + "getWorkflowCatalog(engine) was called.");
+  return internals.workflowCatalog;
+}

package/dist/core/engine/lifecycle/checkpoint-launch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Launch a workflow run from an already-built `WorkflowState`/`Checkpoint`
+ * pair — the shared tail `fork()` (`transition.ts`) drives after planting a
+ * new run's durable records. Split out of `transition.ts`, which has no
+ * headroom under the repository's 500-line implementation-file ceiling for
+ * this logic inline.
+ *
+ * @module core/engine/lifecycle/checkpoint-launch
+ */
+import type { Checkpoint, WorkflowState } from '../../types.ts';
+import { type WorkflowHandle } from '../handles.ts';
+import type { EngineInternals } from '../internals.ts';
+import { type LifecycleCallbacks, type RegistrationEntry } from './shared.ts';
+export declare function launchWorkflowFromCheckpoint(internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, registration: RegistrationEntry, 
+/**
+ * The EXACT revision `registration` was resolved against — from the same
+ * `resolveExecutableRegistrationForRevision()` call that produced
+ * `registration`, threaded through explicitly rather than re-read off
+ * `state.revision` (WFT-19 review round 5, Codex, mirroring the identical
+ * fix in `lifecycle/resume.ts`). `fork()`'s own `forkState.revision` is
+ * now stamped with this same resolved value too (WFT-19 review round 6,
+ * Codex — `createForkedWorkflowState()`'s matching fix, so a legacy
+ * fork's durable pin agrees with this in-memory one), so `state.revision`
+ * and `resolvedRevision` coincide for every current caller; kept as an
+ * explicit parameter regardless, since this function's identity-cache
+ * write must never depend on that invariant holding at a future call
+ * site.
+ */
+resolvedRevision: string | undefined, callbacks: LifecycleCallbacks): WorkflowHandle;

package/dist/core/engine/lifecycle/checkpoint-launch.js

@@ -0,0 +1,75 @@
+import { serializeCheckpoint } from "../../checkpoint.js";
+import { Context, setContextWorkflowInterceptor } from "../../context.js";
+import { WorkflowStartedEvent } from "../../events.js";
+import { createCancelHandlerRegistration, resetCancelHandlers } from "../cancel-handlers.js";
+import { getWorkflowExecutionStartedAt } from "../handles.js";
+import { getComposedWorkflowInterceptor } from "../strategy-helpers.js";
+import { createWorkflowVersionTuple } from "./persist.js";
+import { createWorkflowHandle } from "./shared.js";
+function launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks) {
+  const inlineStrategy = internals.inlineStrategy;
+  if (!inlineStrategy)
+    throw Error("Inline workflow launch requested without an inline strategy.");
+  const accumulatedResults = new Map(checkpoint.accumulatedResults), workflowAbort = new AbortController;
+  resetCancelHandlers(internals, workflowId);
+  const context = new Context({
+    workflowId,
+    ...state.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: state.workflowExecutionToken
+    },
+    workflowType: state.type,
+    startedAt: getWorkflowExecutionStartedAt(state),
+    abortController: workflowAbort,
+    getNow: internals.options.getNow,
+    resolveWorkflowType: callbacks.resolveWorkflowTypeTarget,
+    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
+    accumulatedResults,
+    searchAttributes: checkpoint.searchAttributes,
+    registerCancelHandler: createCancelHandlerRegistration(internals, workflowId),
+    ...registration.searchAttributes && {
+      searchAttributeSchema: registration.searchAttributes
+    },
+    sleepReferenceTime: checkpoint.createdAt,
+    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline },
+    ...internals.options.onLog != null && { logSink: internals.options.onLog }
+  });
+  setContextWorkflowInterceptor(context, getComposedWorkflowInterceptor(internals));
+  if (internals.options.development)
+    context.explain(!0);
+  const generator = registration.handler(context, state.input);
+  inlineStrategy.adoptWorkflow(workflowId, generator, context, workflowAbort);
+  inlineStrategy.continueWorkflow(workflowId, void 0);
+  callbacks.swallowPromiseRejection(callbacks.processPendingUpdatesAfterInlineAdvance(workflowId));
+}
+function launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint) {
+  const serialized = serializeCheckpoint(checkpoint);
+  internals.strategy.startWorkflow({
+    workflowId,
+    ...state.workflowExecutionToken !== void 0 && {
+      workflowExecutionToken: state.workflowExecutionToken
+    },
+    workflowType: state.type,
+    input: state.input,
+    checkpoint: serialized,
+    executionStateOwnerId: state.executionStateOwnerId ?? workflowId,
+    ...state.executionDeadline !== void 0 && { deadline: state.executionDeadline },
+    ...internals.workflowHeaders.has(workflowId) && {
+      headers: [...internals.workflowHeaders.get(workflowId)]
+    }
+  });
+}
+export function launchWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, resolvedRevision, callbacks) {
+  internals.workflowTypeByWorkflowId.set(workflowId, {
+    type: state.type,
+    revision: resolvedRevision
+  });
+  internals.checkpoints.set(workflowId, checkpoint);
+  internals.workflowVersionTuples.set(workflowId, createWorkflowVersionTuple(internals, registration, callbacks));
+  const handle = createWorkflowHandle(internals, workflowId, callbacks);
+  callbacks.dispatchEvent(new WorkflowStartedEvent(workflowId, state.type, state.input));
+  if (internals.inlineStrategy)
+    launchInlineWorkflowFromCheckpoint(internals, workflowId, state, checkpoint, registration, callbacks);
+  else
+    launchWorkerWorkflowFromCheckpoint(internals, workflowId, state, checkpoint);
+  return handle;
+}