@lostgradient/weft 0.24.0 → 0.24.1

package/dist/core/engine/catalog-tombstone-recovery.js

@@ -0,0 +1,39 @@
+import { KEYS } from "../../storage/interface.js";
+import { tryDecodeStorageKeyComponent } from "../../storage/key-encoding.js";
+import {
+  decodeCatalogEntryRecord,
+  finalizeCatalogTombstone,
+  restoreCatalogEntryFromTombstone
+} from "../catalog/index.js";
+import { countNonTerminalRunsForRevision } from "./nonterminal-revision-count.js";
+function splitCatalogTombstoneKey(key) {
+  const parts = key.split(":");
+  if (parts.length !== 3)
+    return null;
+  const name = tryDecodeStorageKeyComponent(parts[1] ?? ""), revision = tryDecodeStorageKeyComponent(parts[2] ?? "");
+  if (name === null || revision === null)
+    return null;
+  return { name, revision };
+}
+async function resolveCatalogTombstone(storage, name, revision, tombstoneBytes) {
+  if (await countNonTerminalRunsForRevision(storage, name, revision) > 0)
+    await restoreCatalogEntryFromTombstone(storage, name, revision, tombstoneBytes);
+  else
+    await finalizeCatalogTombstone(storage, name, revision, tombstoneBytes);
+}
+export async function resolveOrphanedCatalogTombstones(storage) {
+  for await (const [key, bytes] of storage.scan(KEYS.catalogTombstonePrefix())) {
+    const split = splitCatalogTombstoneKey(key);
+    if (split === null)
+      throw Error(`The store's catalog tombstone key ("${key}") does not match the expected catalog-tombstone:<name>:<revision> shape. Treating it as absent would risk silently abandoning an in-flight catalog removal, so this fails closed instead. Resolve by operator repair: inspect the stored bytes and, only if certain no removal is actually in flight, delete the key.`);
+    await decodeCatalogEntryRecord(key, bytes, split.name, split.revision);
+    await resolveCatalogTombstone(storage, split.name, split.revision, bytes);
+  }
+}
+export async function resolveCatalogTombstoneIfPresent(storage, name, revision) {
+  const tombstoneKey = KEYS.catalogTombstone(name, revision), tombstoneBytes = await storage.get(tombstoneKey);
+  if (tombstoneBytes === null)
+    return;
+  await decodeCatalogEntryRecord(tombstoneKey, tombstoneBytes, name, revision);
+  await resolveCatalogTombstone(storage, name, revision, tombstoneBytes);
+}

package/dist/core/engine/constraints.js

@@ -1,9 +1,13 @@
 import { ConstraintViolatedEvent } from "../events.js";
+import { getResolvedDynamicRegistration } from "./dynamic-source-execution.js";
+function resolveRunningInstanceRevision(internals, workflowId) {
+  return internals.workflowTypeByWorkflowId.get(workflowId)?.revision;
+}
 export async function evaluateConstraints(internals, workflowId, callbacks) {
   const context = internals.inlineStrategy?.getContext(workflowId);
   if (!context)
     return !1;
-  const constraints = internals.registrations.get(context.workflowType)?.constraints;
+  const revision = resolveRunningInstanceRevision(internals, workflowId), constraints = getResolvedDynamicRegistration(internals, context.workflowType, revision)?.constraints;
   if (!constraints || constraints.length === 0)
     return !1;
   const stateSnapshot = {

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

@@ -50,7 +50,7 @@ export declare function createExecutionStrategyBundle(parameters: {
     maxNestingDepth: number;
     development: boolean;
     broadcastEvents: boolean;
-    getRegistration: (workflowType: string) => RegistrationEntry | undefined;
+    getRegistration: (workflowType: string, workflowId: string) => RegistrationEntry | undefined;
     /** Live accessor for registered workflow type names (WFT-28); registrations are still empty here. */
     listRegisteredWorkflowTypes: () => Iterable<string>;
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;

package/dist/core/engine/decode-revision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Decoded-`revision` sanitization for {@link import('./validation.ts').decodeWorkflowState}.
+ * Split out of `validation.ts`, which has no headroom under the repository's
+ * 500-line implementation-file ceiling.
+ *
+ * @module core/engine/decode-revision
+ */
+import type { WorkflowState } from '../types.ts';
+/**
+ * Normalize a decoded `revision` that is present but not a non-empty,
+ * bounded string.
+ *
+ * Deliberately NEVER drops a present-but-malformed value to `undefined` —
+ * `revision` is engine-derived (never user-supplied at the API surface), so
+ * an invalid value here indicates storage corruption or tampering, and
+ * `undefined` is the SAME signal a genuinely missing `revision` carries
+ * (a legitimate pre-revision-pinning record). Recovery treats an
+ * `undefined` pin as unambiguous for an eager type or a dynamic source with
+ * at most one registered candidate — silently executing that sole
+ * candidate against a checkpoint whose true originating revision is
+ * actually unknown, rather than rejecting the damaged identity. Instead,
+ * a malformed value is replaced with a deterministic, distinctly-prefixed
+ * marker derived from the workflow id: still a valid, bounded `string`, but
+ * virtually guaranteed not to match any real registered candidate, so the
+ * ordinary `resolveExecutableRegistrationForRevision()` "not-registered"
+ * path rejects it explicitly (an `unavailable` recovery outcome, isolated
+ * to that one run) instead of silently downgrading it to "legacy."
+ *
+ * Only a genuinely absent `revision` (never persisted at all) returns
+ * early, unchanged, above.
+ */
+export declare function sanitizeDecodedRevision(state: WorkflowState): void;

package/dist/core/engine/decode-revision.js

@@ -0,0 +1,9 @@
+const MAX_WORKFLOW_REVISION_LENGTH = 512, CORRUPTED_WORKFLOW_REVISION_PREFIX = "weft:corrupted-revision:";
+export function sanitizeDecodedRevision(state) {
+  if (state.revision === void 0)
+    return;
+  if (typeof state.revision === "string" && state.revision.length > 0 && state.revision.length <= MAX_WORKFLOW_REVISION_LENGTH)
+    return;
+  console.warn(`[weft] Decoded workflow state for "${state.id}" has a malformed revision field; replacing it with a corruption marker so recovery rejects it explicitly as an unavailable pin, rather than silently treating this run as pre-revision-pinning. This usually indicates corruption or tampering of the storage record.`);
+  state.revision = `${CORRUPTED_WORKFLOW_REVISION_PREFIX}${state.id}`.slice(0, MAX_WORKFLOW_REVISION_LENGTH);
+}

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

@@ -4,6 +4,10 @@ import type { EngineInternals } from './internals.ts';
  * `Engine[Symbol.dispose]` — the operation order is correctness-sensitive
  * (abort before clearing waiters, dispose strategies before nulling them) and
  * is preserved exactly. `Engine[Symbol.dispose]` and `[Symbol.asyncDispose]`
- * both delegate here.
+ * both delegate here. `dispatchEvent` defaults to a no-op so every existing
+ * direct-internals test that calls this with one argument keeps compiling
+ * and running — only `Engine`'s own two call sites pass the real
+ * `engine.dispatchEvent` binding, which is what lets
+ * `disposeSourceResolutionState` fire `workflow-source:load-cancelled`.
  */
-export declare function disposeEngine(internals: EngineInternals): void;
+export declare function disposeEngine(internals: EngineInternals, dispatchEvent?: (event: Event) => void): void;

package/dist/core/engine/disposal.js

@@ -1,3 +1,4 @@
+import { WorkflowSourceLoadCancelledEvent } from "../events/workflow-source-events.js";
 import { disposeEngineCleanupInterval } from "./engine-runtime-helpers.js";
 import { EngineDisposedError } from "./errors.js";
 import { disposeQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
@@ -13,15 +14,29 @@ function clearPendingResultPollTimers(internals) {
     clearTimeout(timer);
   internals.pendingResultPollTimers.clear();
 }
-function disposeSourceResolutionState(internals) {
-  for (const controller of internals.sourceResolutionWaiterControllers)
+function rejectPendingResultResolvers(internals) {
+  for (const waiter of internals.resultResolvers.values())
+    waiter.reject(new EngineDisposedError);
+}
+function disposeSourceResolutionState(internals, dispatchEvent) {
+  for (const controller of internals.sources.waiterControllers)
     controller.abort(new EngineDisposedError);
-  internals.sourceResolutionWaiterControllers.clear();
-  internals.sourceResolutionsInFlight.clear();
-  internals.workflowSourcesByName.clear();
-  internals.resolvedWorkflowSources.clear();
+  const stillLoading = [];
+  for (const [name, byRevision] of internals.sources.diagnostics)
+    for (const [revision, entry] of byRevision)
+      if (entry.state === "loading")
+        stillLoading.push({ name, revision, kind: entry.kind });
+  internals.sources.waiterControllers.clear();
+  internals.sources.resolutionsInFlight.clear();
+  internals.sources.byName.clear();
+  internals.sources.resolved.clear();
+  internals.sources.waitersByKey.clear();
+  internals.sources.lastResolvedRevisionByName.clear();
+  internals.sources.diagnostics.clear();
+  for (const { name, revision, kind } of stillLoading)
+    dispatchEvent(new WorkflowSourceLoadCancelledEvent(name, revision, kind));
 }
-export function disposeEngine(internals) {
+export function disposeEngine(internals, dispatchEvent = () => {}) {
   internals.disposed = !0;
   internals.alertManager?.[Symbol.dispose]();
   internals.alertManager = null;
@@ -48,8 +63,7 @@ export function disposeEngine(internals) {
   disposeSecondInstanceDetection(internals);
   disposeLeaseManager(internals);
   internals.handleCache.clear();
-  for (const waiter of internals.resultResolvers.values())
-    waiter.reject(new EngineDisposedError);
+  rejectPendingResultResolvers(internals);
   rejectAllSleepTimerAcknowledgements(internals, new EngineDisposedError);
   internals.resultResolvers.clear();
   internals.updateWaiters.clear();
@@ -65,7 +79,7 @@ export function disposeEngine(internals) {
   for (const controller of internals.pendingWebhooks)
     controller.abort();
   internals.pendingWebhooks.clear();
-  disposeSourceResolutionState(internals);
+  disposeSourceResolutionState(internals, dispatchEvent);
   clearPendingResultPollTimers(internals);
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();

package/dist/core/engine/dynamic-source-errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Errors raised by the dynamic workflow source pipeline (WFT-15/16):
+ * {@link DynamicWorkflowSourceUnavailableError} at an execution entry point
+ * — `start`, `startOrSignal`, `schedule`, `fork`, `resume`, recovery, and
+ * bulk-retry — when a registered source's revision is ambiguous or its
+ * load fails; {@link WorkflowSourceNotRegisteredError} by
+ * `engine.resolveWorkflowSource()` / `engine.workflows.preload()` directly.
+ * Split out of `errors.ts`, which is at the repository's 500-line
+ * implementation-file ceiling with no headroom for two more documented
+ * classes; kept alongside `lease-errors.ts` and `source/errors.ts` as this
+ * file family's precedent for a domain-scoped errors module.
+ *
+ * @module core/engine/dynamic-source-errors
+ */
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown by `engine.resolveWorkflowSource()` (and its
+ * `engine.workflows.preload()` alias) when called against a specific
+ * `(name, revision)` that `registerSource()` never recorded — a
+ * programmer-error contract, not untrusted-input rejection. `revision` is
+ * therefore always defined in practice.
+ *
+ * This is a DIFFERENT case from a workflow `type` with no eager
+ * registration AND no dynamic source at all: every execution entry point
+ * (`start`, `startOrSignal`, `schedule`, `fork`, `resume`, recovery,
+ * bulk-retry) keeps throwing the pre-existing
+ * {@link WorkflowNotRegisteredError} for that case instead, preserving the
+ * fault classification and wire code callers already depended on before
+ * WFT-15/16 — see `dynamic-source-execution.ts`'s
+ * `resolveExecutableRegistration()`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceNotRegisteredError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.resolveWorkflowSource('checkout', 'r-never-registered');
+ * } catch (err) {
+ *   if (err instanceof WorkflowSourceNotRegisteredError) {
+ *     console.error('registerSource() it first:', err.workflowType, err.revision);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowSourceNotRegisteredError extends WeftError<'WorkflowSourceNotRegisteredError'> {
+    readonly workflowType: string;
+    readonly revision: string | undefined;
+    constructor(workflowType: string, revision?: string);
+}
+/**
+ * Thrown when a registered dynamic workflow source cannot be turned into an
+ * executable registration: either its load failed (`reason: 'load-failed'`,
+ * `cause` carries the underlying error) or which revision to resolve could
+ * not be determined (`reason: 'ambiguous-revision'` — two or more revisions
+ * are registered for `workflowType` and the catalog has no active pointer
+ * naming one of them). Recovery classifies the affected type `unavailable`:
+ * only its runs fail, with this error as the `system` failure cause;
+ * sibling types continue.
+ *
+ * @example
+ * ```ts
+ * import { Engine, DynamicWorkflowSourceUnavailableError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.start('checkout', { orderId: 'order-1' });
+ * } catch (err) {
+ *   if (err instanceof DynamicWorkflowSourceUnavailableError) {
+ *     console.error(err.workflowType, err.reason);
+ *   }
+ * }
+ * ```
+ */
+export declare class DynamicWorkflowSourceUnavailableError extends WeftError<'DynamicWorkflowSourceUnavailableError'> {
+    readonly workflowType: string;
+    readonly revision: string | undefined;
+    readonly reason: 'load-failed' | 'ambiguous-revision';
+    readonly cause: unknown;
+    constructor(workflowType: string, revision: string | undefined, reason: 'load-failed' | 'ambiguous-revision', cause?: unknown);
+}

package/dist/core/engine/dynamic-source-errors.js

@@ -0,0 +1,25 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowSourceNotRegisteredError extends WeftError {
+  workflowType;
+  revision;
+  constructor(workflowType, revision) {
+    super("WorkflowSourceNotRegisteredError", revision === void 0 ? `No workflow registered with name "${workflowType}"` : `resolveWorkflowSource("${workflowType}", "${revision}") was called before registerSource() ` + "registered this exact (name, revision) \u2014 call engine.registerSource() first.");
+    this.workflowType = workflowType;
+    this.revision = revision;
+  }
+}
+
+export class DynamicWorkflowSourceUnavailableError extends WeftError {
+  workflowType;
+  revision;
+  reason;
+  cause;
+  constructor(workflowType, revision, reason, cause) {
+    super("DynamicWorkflowSourceUnavailableError", reason === "ambiguous-revision" ? `Cannot resolve dynamic workflow source "${workflowType}": multiple revisions are registered and none is the catalog active revision. Activate one via engine.workflows.activate(), or register only one revision at a time.` : `Dynamic workflow source "${workflowType}"${revision === void 0 ? "" : ` revision "${revision}"`} failed to load: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.reason = reason;
+    this.cause = cause;
+  }
+}

package/dist/core/engine/dynamic-source-execution.d.ts

@@ -0,0 +1,173 @@
+/**
+ * `resolveExecutableRegistration()` — the single async helper every
+ * execution entry point that can launch or resume a workflow
+ * (`start`/`startOrSignal`/`schedule`/`fork`/`resume`/recovery/bulk-retry)
+ * funnels through to turn a workflow `type` into a `RegistrationEntry` it
+ * can actually run (WFT-15/16).
+ *
+ * Fast path: an eagerly `engine.register()`-ed type resolves synchronously
+ * from `internals.registrations` and never touches `internals.sources` —
+ * this is what makes "starting the eager workflow does not import the lazy
+ * module" true. Slow path: a `engine.registerSource()`-registered type is
+ * resolved via `resolveWorkflowSourceForExecution()`, which awaits the
+ * loader (single-flight, shared with any other concurrent caller for the
+ * same key) and installs the result durably before this returns — so no
+ * workflow handler ever runs while its definition is still a catalog
+ * candidate.
+ *
+ * @module core/engine/dynamic-source-execution
+ */
+import type { Engine } from './index.ts';
+import type { EngineInternals } from './internals.ts';
+type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+/** The outcome of {@link resolveExecutableRegistration}. */
+export type ExecutableRegistration = {
+    entry: RegistrationEntry;
+    /** The dynamic source revision resolved, or `undefined` for an eager registration. */
+    revision: string | undefined;
+};
+/**
+ * Turn workflow `type` into an executable {@link RegistrationEntry}, awaiting
+ * dynamic-source resolution when `type` is not eagerly registered. Throws
+ * {@link WorkflowNotRegisteredError} when `type` is neither an eager
+ * registration nor a registered source (the pre-existing error — see the
+ * call site below for why); {@link DynamicWorkflowSourceUnavailableError}
+ * when a registered source's target revision is ambiguous or its load
+ * fails; {@link EngineDisposedError} unwrapped when the engine is disposed
+ * during resolution.
+ */
+export declare function resolveExecutableRegistration(engine: Engine, internals: EngineInternals, type: string, onRevisionChosen?: (revision: string) => void): Promise<ExecutableRegistration>;
+/**
+ * The shared classification `resolveExecutableRegistrationForRevision()`'s
+ * throw-vs-proceed decision and the ADR-0002 workflow-lease reclaim-
+ * eligibility gate (`index.ts`'s `isWorkflowTypeRegistered`) both delegate
+ * to, so the two decisions can never drift out of sync — an engine that
+ * cannot locally resolve a run's exact pin must never win that run's claim
+ * either (see `workflow-claim-reclaim-target.ts`'s own doc for why that
+ * would strand the run under a permanently-failing `onReclaimed` drive).
+ *
+ * - An eager registration is always resolvable, regardless of `revision`
+ *   (eager has no ambiguity to pin against).
+ * - `type` with no eager registration and no registered source at all is
+ *   never resolvable.
+ * - A dynamic source with `revision === undefined` (legacy/pre-pinning) is
+ *   resolvable only when it has exactly one registered candidate —
+ *   unambiguous by construction. Two or more is ambiguous; zero is
+ *   impossible (an empty `byRevision` map does not exist — the type
+ *   wouldn't be in `sources.byName` at all).
+ * - A dynamic source with a defined `revision` is resolvable exactly when
+ *   that revision is among this process's currently registered candidates.
+ */
+export declare function canResolveRevisionLocally(internals: EngineInternals, type: string, revision: string | undefined): boolean;
+/**
+ * Resolve workflow `type` against its EXACT pinned `revision` — the
+ * `WorkflowState.revision` a run persisted at start (WFT-17) — instead of
+ * whichever revision the catalog currently considers active. This is the
+ * resolver `resumeWorkflowFromStorage()` (`lifecycle/resume.ts`) uses for
+ * EVERY resume (both `recoverAll()`'s batch and a standalone
+ * `engine.resume(id)`), so "recovery never falls back from a missing exact
+ * revision to the active revision" (WFT-17/WFT-18's acceptance criterion)
+ * holds uniformly, not just inside the batch preflight.
+ *
+ * Classification:
+ * - An eager registration is always resolved from `internals.registrations`
+ *   regardless of `revision` — eager has no ambiguity to pin against (the
+ *   process runs whatever code it has loaded), so a stale or absent pin on
+ *   an eager type is harmless and must not block the common redeploy path.
+ * - A dynamic source with `revision === undefined` (a legacy, pre-pinning
+ *   record) falls through to the ordinary {@link resolveExecutableRegistration}
+ *   active-pointer resolution when the type has at most one registered
+ *   candidate (unambiguous by construction), or throws
+ *   {@link WorkflowRevisionUnavailableError} with `reason: 'legacy-ambiguous'`
+ *   when it has two or more (there is no way to tell which one the run
+ *   actually started against).
+ * - A dynamic source with a defined `revision` throws
+ *   {@link WorkflowRevisionUnavailableError} with `reason: 'not-registered'`
+ *   when that exact revision is not among this process's registered
+ *   candidates (covers both "never registered at all" and "was the sole
+ *   candidate, but a different one is registered now") — otherwise it is
+ *   loaded and installed exactly like {@link resolveExecutableRegistration}'s
+ *   own dynamic path.
+ * - `type` with neither an eager registration nor any registered source
+ *   throws the pre-existing {@link WorkflowNotRegisteredError}, matching
+ *   {@link resolveExecutableRegistration}.
+ */
+export declare function resolveExecutableRegistrationForRevision(engine: Engine, internals: EngineInternals, type: string, revision: string | undefined): Promise<ExecutableRegistration>;
+/**
+ * Wraps `callbacks.resolveExecutableRegistration(type)`, remapping ONLY the
+ * "no source registered at all" case (a {@link WorkflowNotRegisteredError})
+ * to `notFoundError` — a caller's own, more-specific "no workflow
+ * registered" message (naming the workflow ID it was
+ * resuming/forking/retrying, for example) instead of the generic one. Every
+ * other error (including a source found but unresolvable) propagates
+ * unwrapped. Shared by `resume.ts`, `transition.ts`'s `fork()`, and
+ * `bulk-operations.ts`'s retry path so each keeps a single, low-complexity
+ * call site instead of its own try/catch.
+ */
+export declare function resolveExecutableRegistrationOrRenamedNotFound(resolve: (type: string) => Promise<ExecutableRegistration>, type: string, notFoundError: () => Error): Promise<ExecutableRegistration>;
+/**
+ * {@link resolveExecutableRegistrationOrRenamedNotFound}, pre-bound to
+ * `bulk-operations.ts`'s retry-failed message shape. Resolves against the
+ * failed run's own EXACT pinned `revision` (`WorkflowState.revision`, WFT-17)
+ * via {@link resolveExecutableRegistrationForRevision} — never the catalog's
+ * active pointer — so a bulk retry's pre-reactivation concurrency-admission
+ * lookup agrees with the exact-revision resolve the subsequent
+ * `engine.resume()` performs. Resolving against the active pointer here
+ * instead would let a retry commit the failed->running reactivation batch
+ * against the WRONG registration's `concurrency` config, and then — if the
+ * pinned revision is unavailable while a different revision is active —
+ * only discover that after the reactivation already committed, leaving the
+ * run stranded `running` with no generator ever resuming. Kept here (with
+ * the bulk of the logic off `bulk-operations.ts`, already at its own
+ * oxlint `max-lines` ceiling) rather than inlined at that one call site.
+ */
+export declare function resolveExecutableRegistrationForRetry(internals: EngineInternals, type: string, revision: string | undefined, workflowId: string): Promise<ExecutableRegistration>;
+/**
+ * Sync-only fallback lookup for PER-INSTANCE call sites that run after a
+ * workflow is already executing (or is being swept from storage) and must
+ * never trigger a new resolve — finalizer, constraint, retention, and
+ * search-attribute-schema resolution (`termination/finalizer-registration.ts`,
+ * `constraints.ts`, `workflow-retention-deadline.ts`, `listing.ts`). Reads
+ * the eager registration first (an eager type resolves the same regardless
+ * of `revision` — see {@link canResolveRevisionLocally}'s doc). Otherwise:
+ *
+ * - A defined `revision` reads `internals.sources.resolved.get(type)?.get(revision)`
+ *   directly — the running instance's OWN exact pin — with NO fallback to a
+ *   different revision when that exact one is not locally resolved (returns
+ *   `undefined` instead, matching {@link resolveExecutableRegistrationForRevision}'s
+ *   "never silently substitute a different revision" contract).
+ * - `revision === undefined` (a legacy pre-pinning record) falls back to
+ *   `internals.sources.lastResolvedRevisionByName` ONLY when
+ *   {@link canResolveRevisionLocally} classifies that as unambiguous —
+ *   exactly one registered candidate for `type`. With two or more
+ *   registered candidates this is genuinely ambiguous for a SPECIFIC
+ *   instance (WFT-19 review round 6, Codex, P1): silently substituting
+ *   whichever sibling revision this process last resolved could validate
+ *   `setAttributes()` against a sibling's schema, run a sibling's
+ *   finalizer, or — worst, since purge is irreversible — purge a run early
+ *   under a sibling's shorter retention window. Returns `undefined` in that
+ *   case instead, forcing the caller's async fallback
+ *   (`resolveExecutableRegistrationForRevision()`) to reach the
+ *   `legacy-ambiguous` classification and fail closed the same way it
+ *   already does for resume/recovery. {@link resolveLastKnownDynamicRegistration}
+ *   is the deliberate exception for the one genuinely TYPE-level caller
+ *   that wants the permissive last-resolved-wins answer even when
+ *   ambiguous.
+ *
+ * Returns `undefined` when no source has a matching entry.
+ */
+export declare function getResolvedDynamicRegistration(internals: EngineInternals, type: string, revision: string | undefined): RegistrationEntry | undefined;
+/**
+ * TYPE-level, sync-only "whatever this process last resolved" lookup —
+ * used ONLY by `retention.ts`'s `resolveWorkflowTypeRetention()`, an
+ * across-all-registered-types OVERVIEW API (`getRetentionOverview()`) with
+ * no single running instance to pin against, unlike every caller of
+ * {@link getResolvedDynamicRegistration} above. Deliberately does NOT fail
+ * closed when 2+ candidates are registered for `type`: for an overview,
+ * showing the last-resolved candidate's policy is a more useful signal
+ * than showing nothing, and — unlike `getResolvedDynamicRegistration`'s
+ * per-instance callers — no irreversible action (purge, finalizer run,
+ * schema validation) hangs off this call (WFT-19 review round 6, Codex).
+ */
+export declare function resolveLastKnownDynamicRegistration(internals: EngineInternals, type: string): RegistrationEntry | undefined;
+export {};

package/dist/core/engine/dynamic-source-execution.js

@@ -0,0 +1,108 @@
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+import { DynamicWorkflowSourceUnavailableError } from "./dynamic-source-errors.js";
+import { EngineDisposedError, WorkflowNotRegisteredError } from "./errors.js";
+import { assertConstraintsSupported, buildRegistrationEntry } from "./registration.js";
+import { WorkflowRevisionUnavailableError } from "./revision-errors.js";
+import { resolveWorkflowSourceForExecution } from "./source-resolution.js";
+async function resolveActiveSourceRevision(engine, type, byRevision) {
+  await ensureWorkflowCatalogReady(engine);
+  const activeRevision = (await getWorkflowCatalog(engine).resolveActiveDurable(type))?.revision;
+  if (activeRevision !== void 0 && byRevision.has(activeRevision))
+    return activeRevision;
+  throw new DynamicWorkflowSourceUnavailableError(type, void 0, "ambiguous-revision");
+}
+export async function resolveExecutableRegistration(engine, internals, type, onRevisionChosen) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return { entry: eager, revision: void 0 };
+  const byRevision = internals.sources.byName.get(type);
+  if (byRevision === void 0)
+    throw new WorkflowNotRegisteredError(type);
+  let revision;
+  if (byRevision.size === 1) {
+    revision = [...byRevision.keys()][0];
+    onRevisionChosen?.(revision);
+  } else {
+    revision = await resolveActiveSourceRevision(engine, type, byRevision);
+    onRevisionChosen?.(revision);
+  }
+  return loadAndInstallSourceRevision(engine, internals, type, revision);
+}
+async function loadAndInstallSourceRevision(engine, internals, type, revision) {
+  try {
+    await resolveWorkflowSourceForExecution(engine, type, revision);
+  } catch (error) {
+    if (error instanceof EngineDisposedError)
+      throw error;
+    throw new DynamicWorkflowSourceUnavailableError(type, revision, "load-failed", error);
+  }
+  const resolved = internals.sources.resolved.get(type)?.get(revision);
+  if (resolved === void 0)
+    throw new DynamicWorkflowSourceUnavailableError(type, revision, "load-failed", Error("Dynamic workflow source resolved without populating a local definition"));
+  assertConstraintsSupported(internals, type, resolved.definition);
+  const entry = buildRegistrationEntry(type, resolved.definition);
+  internals.workflowTypesByHandler.set(resolved.definition.handler, type);
+  internals.sources.lastResolvedRevisionByName.set(type, revision);
+  return { entry, revision };
+}
+export function canResolveRevisionLocally(internals, type, revision) {
+  if (internals.registrations.has(type))
+    return !0;
+  const byRevision = internals.sources.byName.get(type);
+  if (byRevision === void 0)
+    return !1;
+  if (revision === void 0)
+    return byRevision.size === 1;
+  return byRevision.has(revision);
+}
+export async function resolveExecutableRegistrationForRevision(engine, internals, type, revision) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return { entry: eager, revision: void 0 };
+  if (internals.sources.byName.get(type) === void 0)
+    throw new WorkflowNotRegisteredError(type);
+  if (!canResolveRevisionLocally(internals, type, revision)) {
+    if (revision === void 0)
+      throw new WorkflowRevisionUnavailableError(type, void 0, "legacy-ambiguous");
+    throw new WorkflowRevisionUnavailableError(type, revision, "not-registered");
+  }
+  if (revision === void 0)
+    return resolveExecutableRegistration(engine, internals, type);
+  return loadAndInstallSourceRevision(engine, internals, type, revision);
+}
+export async function resolveExecutableRegistrationOrRenamedNotFound(resolve, type, notFoundError) {
+  return resolve(type).catch((error) => {
+    if (error instanceof WorkflowNotRegisteredError)
+      throw notFoundError();
+    throw error;
+  });
+}
+export async function resolveExecutableRegistrationForRetry(internals, type, revision, workflowId) {
+  return resolveExecutableRegistrationOrRenamedNotFound((t) => resolveExecutableRegistrationForRevision(internals.engine, internals, t, revision), type, () => Error(`No workflow registered with name "${type}" (needed to retry "${workflowId}")`));
+}
+export function getResolvedDynamicRegistration(internals, type, revision) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return eager;
+  if (revision !== void 0) {
+    const resolved = internals.sources.resolved.get(type)?.get(revision);
+    if (resolved === void 0)
+      return;
+    return buildRegistrationEntry(type, resolved.definition);
+  }
+  if (!canResolveRevisionLocally(internals, type, void 0))
+    return;
+  return resolveLastKnownDynamicRegistration(internals, type);
+}
+export function resolveLastKnownDynamicRegistration(internals, type) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return eager;
+  const targetRevision = internals.sources.lastResolvedRevisionByName.get(type);
+  if (targetRevision === void 0)
+    return;
+  const resolved = internals.sources.resolved.get(type)?.get(targetRevision);
+  if (resolved === void 0)
+    return;
+  return buildRegistrationEntry(type, resolved.definition);
+}

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