@lostgradient/weft 0.24.0 → 0.24.2

package/dist/core/engine/engine-internal-types.d.ts

@@ -3,6 +3,20 @@ import type { ConstraintDefinition } from '../constraint.ts';
 import type { ExecutionStrategy } from '../execution-strategy.ts';
 import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
 import type { AnyActivityDefinition, ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, QueryDefinition, SearchAttributeSchema, SignalDefinition, UpdateDefinition, WorkflowConcurrencyOptions, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
+/**
+ * The identity a running workflow instance was launched under, cached by
+ * `EngineInternals.workflowTypeByWorkflowId` for the lifetime of its
+ * execution (WFT-19). `revision` is the exact `WorkflowState.revision` this
+ * instance is pinned to (WFT-17) — `undefined` for an eager registration or
+ * a legacy (pre-pinning) record — so a process-local lookup keyed by
+ * `workflowId` can resolve THIS instance's own dynamic-source revision
+ * rather than falling back to whichever revision this process resolved
+ * last.
+ */
+export type WorkflowExecutionIdentity = {
+    type: string;
+    revision: string | undefined;
+};
 export interface RegistrationEntry {
     handler: WorkflowFunction;
     version: string;
@@ -103,6 +117,8 @@ export type QueuedInlineWorkflowExecutionStart = {
     nestingDepth: number;
     executionDeadline: number | undefined;
     executionStateOwnerId: string;
+    /** The exact revision this queued start is pinned to (WFT-17/WFT-19). */
+    revision: string | undefined;
     /**
      * Liveness callback invoked once this queued start has actually begun
      * executing (its generator has been driven). Set only for `defer: false`

package/dist/core/engine/engine-workflows-namespace.d.ts

@@ -33,6 +33,7 @@ import { type WorkflowCatalogActivationResult, type WorkflowCatalogActivePointer
 import type { WorkflowCompatibilityPolicy } from '../contract/compatibility.ts';
 import type { WorkflowRevisionManifest } from '../contract/types.ts';
 import type { Engine } from './index.ts';
+import { type ResolveWorkflowSourceOptions } from './source-resolution.ts';
 /**
  * Options accepted by {@link EngineWorkflowsNamespace.activate}.
  *
@@ -125,6 +126,15 @@ export interface EngineWorkflowsNamespace {
     getRevision(name: string, revision: string): Promise<WorkflowRevisionRecord | null>;
     /** Every installed revision of `name`, sorted deterministically by revision. */
     listRevisions(name: string): Promise<readonly WorkflowRevisionRecord[]>;
+    /**
+     * Load, validate, and install one dynamic workflow source revision
+     * previously recorded via `engine.registerSource()` (WFT-15/16). A thin,
+     * documented alias for `engine.resolveWorkflowSource()` — identical
+     * single-flight, cancellation, and error contract — offered here so
+     * deployment tooling that already reaches for `engine.workflows.*` for
+     * every other catalog operation does not need a second entry point.
+     */
+    preload(name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;
 }
 /** Build the `engine.workflows` namespace object for `engine`. */
 export declare function createEngineWorkflowsNamespace(engine: Engine): EngineWorkflowsNamespace;

package/dist/core/engine/engine-workflows-namespace.js

@@ -8,6 +8,7 @@ import {
   isWorkflowCatalogReady
 } from "./catalog-readiness.js";
 import { WorkflowNotRegisteredError } from "./errors.js";
+import { resolveWorkflowSource } from "./source-resolution.js";
 async function ensureCatalogReady(engine) {
   if (!isWorkflowCatalogReady(engine))
     await ensureWorkflowCatalogReady(engine);
@@ -44,6 +45,7 @@ export function createEngineWorkflowsNamespace(engine) {
     activate: (name, revision, options) => activateWorkflowRevision(engine, name, revision, options),
     getActive: (name) => getActiveWorkflowRevision(engine, name),
     getRevision: (name, revision) => getInstalledWorkflowRevision(engine, name, revision),
-    listRevisions: (name) => listInstalledWorkflowRevisions(engine, name)
+    listRevisions: (name) => listInstalledWorkflowRevisions(engine, name),
+    preload: (name, revision, options) => resolveWorkflowSource(engine, name, revision, options)
   };
 }

package/dist/core/engine/generation-codec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure codec for the durable per-workflow-id generation counter
+ * (`wf-gen:<id>`, WFT-153).
+ *
+ * Reuses `lease-codec.ts`'s `encodeEpoch`/`decodeEpoch` under
+ * generation-specific names rather than reimplementing them: both are
+ * permanently-retained monotonic uint64 counters minted the same way
+ * (`(observed ?? 0) + 1`, never a literal), so sharing one encoder/decoder
+ * keeps their on-disk representation byte-identical and their validity range
+ * ([1, MAX_SAFE_INTEGER)) — fail-closed on corruption — in lockstep by
+ * construction rather than by convention.
+ *
+ * @module core/engine/generation-codec
+ */
+import { decodeEpoch, encodeEpoch } from './lease-codec.ts';
+/** Encode an 8-byte big-endian uint64 generation. See `lease-codec.ts#encodeEpoch`. */
+export declare const encodeGeneration: typeof encodeEpoch;
+/**
+ * Decode an 8-byte big-endian uint64 generation, or `null` when the stored
+ * value is not a usable generation. See `lease-codec.ts#decodeEpoch`.
+ */
+export declare const decodeGeneration: typeof decodeEpoch;

package/dist/core/engine/generation-codec.js

@@ -0,0 +1,2 @@
+import { decodeEpoch, encodeEpoch } from "./lease-codec.js";
+export const encodeGeneration = encodeEpoch, decodeGeneration = decodeEpoch;

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

@@ -30,6 +30,7 @@ export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictEr
 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';
@@ -39,6 +40,7 @@ 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';
@@ -299,11 +301,15 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     getActivityDefinition(name: string): ActivityMetadata | undefined;
     listActivityDefinitions(): ActivityMetadata[];
     /**
-     * Resolve one activity's catalog metadata the same way dispatch resolves
-     * it for a running workflow of this type: the workflow's per-workflow
-     * `.activities({...})` registry first, falling back to the global registry
-     * — see `activity-resolution.ts`'s `resolveActivityViaRegistries`. Build
-     * tooling (`buildWorkerManifestFromRegistry`) uses this so a workflow-scoped
+     * 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.
      */
@@ -318,11 +324,13 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
      *
      * 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 per-workflow registry itself
-     * declares — activities a workflow reaches solely through the global
-     * registry are deliberately excluded, since those are not part of what
-     * `.activities({...})` scoped to this workflow. Build tooling that needs a
-     * workflow's full scoped-activity contract set (`buildRegistrySnapshot`,
+     * 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.
      */

package/dist/core/engine/index.js

@@ -66,6 +66,10 @@ import {
   typedEngineView
 } from "./construction.js";
 import { disposeEngine } from "./disposal.js";
+import {
+  canResolveRevisionLocally,
+  getResolvedDynamicRegistration
+} from "./dynamic-source-execution.js";
 import {
   consumeNextEngineLeakWarningTokenForTesting,
   engineCleanupIntervalFinalizer
@@ -175,6 +179,7 @@ import { registerSource as registerWorkflowSource } from "./source-registration.
 import {
   resolveWorkflowSource as resolveWorkflowSourceImpl
 } from "./source-resolution.js";
+import { createWorkflowSourceRuntimeState } from "./source-runtime-state.js";
 import {
   loadScheduleState,
   loadWorkflowState,
@@ -216,6 +221,10 @@ export {
   getWorkflowRevisionDiagnostics,
   removeWorkflowRevision
 } from "./catalog-removal.js";
+export {
+  DynamicWorkflowSourceUnavailableError,
+  WorkflowSourceNotRegisteredError
+} from "./dynamic-source-errors.js";
 export {
   ActivityResolutionError,
   BulkDeleteRequiresTerminalWorkflowsError,
@@ -250,6 +259,7 @@ export {
   OwnershipModeMismatchError,
   WorkflowClaimUnavailableError
 } from "./lease-errors.js";
+export { WorkflowRevisionUnavailableError } from "./revision-errors.js";
 export { ScheduleHandle } from "./schedule-handle.js";
 export {
   clearEngineLeakWarningTokenForTesting,
@@ -270,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 }
   });
 }
 
@@ -318,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),
@@ -445,10 +459,7 @@ export class Engine extends EventTarget {
     getInternals(this).catalogDrainPromise = null;
     getInternals(this).registeredCatalogRevisions = new Map;
     getInternals(this).inFlightStartsByRevision = new Map;
-    getInternals(this).workflowSourcesByName = new Map;
-    getInternals(this).sourceResolutionsInFlight = new Map;
-    getInternals(this).sourceResolutionWaiterControllers = new Set;
-    getInternals(this).resolvedWorkflowSources = new Map;
+    getInternals(this).sources = createWorkflowSourceRuntimeState();
     this.#ensureRetentionSweepInterval();
     this.#startSecondInstanceDetection();
   }
@@ -539,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);
@@ -836,7 +847,7 @@ export class Engine extends EventTarget {
     return cancelAllWorkflows(getInternals(this), filter, options);
   }
   async retryFailedAll(filter, options) {
-    return retryFailedAllWorkflows(getInternals(this), filter, options);
+    return retryFailedAllWorkflows(getInternals(this), filter, options, this.#createLifecycleCallbacks());
   }
   async signalAll(filter, name, payloadOrOptions, options) {
     if (options === void 0)
@@ -1143,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;
@@ -1161,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

@@ -29,18 +29,19 @@ import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
 import type { ComposedActivityInterceptor, ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
 import type { HumanReviewResult, ReviewCoordinator } from '../review/index.ts';
 import type { Scheduler } from '../scheduler.ts';
-import type { Checkpoint, StartWorkflowOptions, WorkflowDefinition } from '../types.ts';
+import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
 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';
@@ -58,12 +59,6 @@ export type DurableInlineOperation = {
 type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine & {
     start(type: string, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
 };
-type SourceHandle = import('../source/index.ts').WorkflowSourceHandle;
-type CatalogRevisionRecord = import('../catalog/index.ts').WorkflowRevisionRecord;
-type ResolvedSource = {
-    definition: WorkflowDefinition;
-    activityRegistry: ActivityRegistry;
-};
 export interface EngineInternals {
     engine: EngineRuntime;
     storage: WeftStorage;
@@ -155,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>;
     /**
@@ -175,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;
@@ -409,14 +405,14 @@ export interface EngineInternals {
     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): `registerSource()` candidates, keyed name then revision. Registering never invokes the loader. Process-local, never persisted. */
-    workflowSourcesByName: Map<string, Map<string, SourceHandle>>;
-    /** In-flight `resolveWorkflowSource` single-flight load per `(name, revision)`. Self-removes on settle via a `catalogDrainPromise`-style identity guard. */
-    sourceResolutionsInFlight: Map<string, Map<string, Promise<CatalogRevisionRecord>>>;
-    /** Per-caller `AbortController`s from in-flight `resolveWorkflowSource()` calls; disposal aborts every waiter without touching the shared load (mirrors `pendingWebhooks`). */
-    sourceResolutionWaiterControllers: Set<AbortController>;
-    /** A successful `resolveWorkflowSource()`'s live definition, keyed name then revision. Unread this batch — WFT-15's job. */
-    resolvedWorkflowSources: Map<string, Map<string, ResolvedSource>>;
+    /**
+     * 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

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

package/dist/core/engine/lifecycle/delayed-start-registration.d.ts

@@ -0,0 +1,30 @@
+import type { TimerEntry } from '../../types.ts';
+import type { ExecutableRegistration } from '../dynamic-source-execution.ts';
+import type { EngineInternals } from '../internals.ts';
+import type { TimeOperationCallbacks } from '../operations-time.ts';
+/**
+ * Resolve `type`'s registration for a delayed-start fire, failing the
+ * workflow (via `callbacks.failWorkflow`) and returning `null` on any
+ * resolution error instead of throwing. ADR 0002: acquires this workflow's
+ * claim standalone + hydrates cleanup tracking BEFORE failing — the
+ * happy-path pending→running fold later in `startDelayedWorkflow` would
+ * otherwise establish both.
+ *
+ * Resolved against `revision` — the pending run's own persisted
+ * `WorkflowState.revision` (WFT-17), `undefined` for a legacy record —
+ * never the catalog's active pointer, so a delayed-start fire honors the
+ * exact revision this run was created against, matching
+ * `resumeWorkflowFromStorage()`'s use of the same resolver.
+ *
+ * Returns the FULL `{ entry, revision }` pair, not just `entry` — mirroring
+ * `resolveExecutableRegistrationOrRenamedNotFound()`'s shape used by
+ * `resume.ts`/`transition.ts`. For a legacy, pre-revision-pinning pending
+ * record with exactly one registered `registerSource()` candidate, the
+ * resolver can unambiguously resolve that candidate even though the input
+ * `revision` was `undefined` — the caller MUST thread this returned
+ * `revision` (not the input `revision` or the persisted state's own,
+ * still-`undefined` `revision`) through the pending→running transition and
+ * into `beginWorkflowExecution`, or the per-instance identity cache ends up
+ * stamped with the wrong (missing) revision (WFT-19 review round 7).
+ */
+export declare function resolveDelayedStartRegistrationOrFail(internals: EngineInternals, entry: TimerEntry, type: string, revision: string | undefined, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'resolveExecutableRegistrationForRevision'>): Promise<ExecutableRegistration | null>;

package/dist/core/engine/lifecycle/delayed-start-registration.js

@@ -0,0 +1,11 @@
+import { ensureDelayedStartClaimAndCleanupBeforeFailure } from "./standalone-claim-acquire.js";
+export async function resolveDelayedStartRegistrationOrFail(internals, entry, type, revision, callbacks) {
+  try {
+    return await callbacks.resolveExecutableRegistrationForRevision(type, revision);
+  } catch (error) {
+    await ensureDelayedStartClaimAndCleanupBeforeFailure(internals, entry.workflowId);
+    const asError = error instanceof Error ? error : Error(String(error));
+    await callbacks.failWorkflow(entry.workflowId, asError);
+    return null;
+  }
+}

package/dist/core/engine/lifecycle/fork-helpers.d.ts

@@ -5,5 +5,37 @@ import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
 export declare function createForkLineage(_internals: EngineInternals, sourceWorkflowId: string, checkpoint: Checkpoint, _callbacks: LifecycleCallbacks): ForkLineage;
 export declare function buildForkSearchAttributes(_internals: EngineInternals, checkpoint: Checkpoint, lineage: ForkLineage, _callbacks: LifecycleCallbacks): Record<string, SearchAttributeValue>;
-export declare function createForkedWorkflowState(_internals: EngineInternals, workflowId: string, sourceState: WorkflowState, versionTuple: WorkflowVersionTuple, lineage: ForkLineage, forkedAt: number, _callbacks: LifecycleCallbacks): WorkflowState;
+export declare function createForkedWorkflowState(_internals: EngineInternals, workflowId: string, sourceState: WorkflowState, versionTuple: WorkflowVersionTuple, lineage: ForkLineage, forkedAt: number, _callbacks: LifecycleCallbacks, 
+/**
+ * `fork()`'s own resolver-returned revision — used to fill in the fork's
+ * persisted `revision` ONLY when `sourceState.revision` is itself
+ * `undefined` (WFT-19 review round 6, Codex, P1). Never overrides an
+ * already-defined `sourceState.revision`: `resolveExecutableRegistrationForRevision()`
+ * ALWAYS returns `revision: undefined` for an eager registration (eager
+ * has no ambiguity to resolve against — see `canResolveRevisionLocally`'s
+ * doc), even though the eager source run's own `sourceState.revision` is
+ * a real, independently-meaningful value (`resolveCachedStartRevision()`'s
+ * `registeredCatalogRevisions` fallback stamps it at ordinary start time,
+ * for every registration kind). Blindly preferring `resolvedRevision`
+ * here would have dropped that real value for every eager-type fork —
+ * caught by `tests/replay-fixtures/fork-from-checkpoint.json`'s golden
+ * byte comparison. For a legacy (pre-revision-pinning) source run on a
+ * dynamic-source type with exactly one registered candidate,
+ * `sourceState.revision` genuinely IS `undefined` even though the
+ * resolver resolved — and the fork launches against — that sole
+ * candidate's code; `sourceState.revision ?? resolvedRevision` falls
+ * through to the resolver's answer only in that case. Stamping the fork's
+ * persisted `revision` with the raw `undefined` legacy pin (as this
+ * function did before this fix existed) left the fork durably unpinned:
+ * it would run correctly until the next restart, but a fresh-process
+ * `recoverAll()` after a second candidate is later registered would
+ * classify the fork `legacy-ambiguous` and refuse to resume it, even
+ * though the fork's own resolver already knew exactly which revision it
+ * belonged to at creation time. Mirrors the identical fix already applied
+ * to the process-local identity cache in `checkpoint-launch.ts`'s
+ * `launchWorkflowFromCheckpoint()` (WFT-19 review round 5) — that fix
+ * closed the in-memory gap; this one closes the matching durable-state
+ * gap the same bug left behind, for the one case it actually applies to.
+ */
+resolvedRevision: string | undefined): WorkflowState;
 export declare function buildForkBatchOperations(_internals: EngineInternals, workflowId: string, state: WorkflowState, checkpoint: Checkpoint, serializedCheckpoint: Uint8Array, workflowStartHeaders: Map<string, string> | undefined, _callbacks: LifecycleCallbacks): BatchOperation[];

package/dist/core/engine/lifecycle/fork-helpers.js

@@ -16,7 +16,8 @@ export function buildForkSearchAttributes(_internals, checkpoint, lineage, _call
     [FORK_LINEAGE_ATTRIBUTE]: lineage.workflowId
   };
 }
-export function createForkedWorkflowState(_internals, workflowId, sourceState, versionTuple, lineage, forkedAt, _callbacks) {
+export function createForkedWorkflowState(_internals, workflowId, sourceState, versionTuple, lineage, forkedAt, _callbacks, resolvedRevision) {
+  const forkRevision = sourceState.revision ?? resolvedRevision;
   return {
     id: workflowId,
     type: sourceState.type,
@@ -24,6 +25,7 @@ export function createForkedWorkflowState(_internals, workflowId, sourceState, v
     input: sourceState.input,
     workflowExecutionToken: crypto.randomUUID(),
     versionTuple,
+    ...forkRevision !== void 0 && { revision: forkRevision },
     executionStateOwnerId: workflowId,
     createdAt: forkedAt,
     startedAt: forkedAt,

package/dist/core/engine/lifecycle/recovery-isolation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `recoverAll()`'s per-entry error isolation — split out of `transition.ts`,
+ * which has no headroom under this repository's 500-line implementation-file
+ * ceiling for the WFT-134 claim-release wrapping `recoverEntryOrIsolateFailure`
+ * needed (mirrors `resume-body.ts`'s same split). This file's own job is just
+ * the branch-matching: given the error `resume()` rejected with, either
+ * isolate it to just this workflow (returning `null`) or rethrow it.
+ *
+ * @module core/engine/lifecycle/recovery-isolation
+ */
+import type { WorkflowHandle } from '../handles.ts';
+import type { LifecycleCallbacks, RecoverAllOptions } from './shared.ts';
+/**
+ * Isolate one `recoverAll()` entry's failure to just this workflow when it
+ * matches a known-recoverable error, committing the matching `failWorkflowForXxx`
+ * fenced write; rethrows anything else, including an opted-in
+ * `VersionMismatchError` throw. See `transition.ts`'s `recoverEntryOrIsolateFailure`
+ * for the caller-side claim-release wrapping around this.
+ */
+export declare function isolateRecoveryFailure(workflowId: string, callbacks: LifecycleCallbacks, options: RecoverAllOptions | undefined, error: unknown): Promise<WorkflowHandle | null>;