@lostgradient/weft 0.24.0 → 0.24.2

package/dist/core/engine/nonterminal-revision-count.js

@@ -0,0 +1,16 @@
+import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
+import { isTopLevelWorkflowStateKey } from "./workflow-state-stream.js";
+export async function countNonTerminalRunsForRevision(storage, type, revision) {
+  let count = 0;
+  for await (const [key, bytes] of storage.scan("wf:")) {
+    if (!isTopLevelWorkflowStateKey(key))
+      continue;
+    const state = decodeWorkflowState(bytes);
+    if (state.type !== type || state.revision !== revision)
+      continue;
+    if (isTerminalWorkflowStatus(state.status))
+      continue;
+    count += 1;
+  }
+  return count;
+}

package/dist/core/engine/operations-time.d.ts

@@ -1,31 +1,13 @@
 import type { ContextOperationRequest } from '../context.ts';
-import type { Checkpoint, Duration, StartOptions, TimerEntry, WorkflowState } from '../types.ts';
-import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { StartOptions, TimerEntry } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
-type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+import { type TimeOperationCallbacks } from './time-operation-callbacks.ts';
 type SleepOperation = Extract<ContextOperationRequest, {
     type: 'sleep';
 }>;
-export type TimeOperationCallbacks = {
-    completeOperation: (workflowId: string, value: unknown) => void;
-    dispatchEvent: (event: Event) => void;
-    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
-    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
-    runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
-    beginWorkflowExecution: (workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
-    workflowVersionTupleFromState: (state: WorkflowState) => WorkflowVersionTuple;
-    setWorkflowStartHeaders: (workflowId: string, headers: Map<string, string> | undefined) => void;
-    loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
-    parseStartOptionDuration: (value: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter') => number;
-    runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
-    runWorkflowFinalizer: (workflowId: string, timerId: string) => Promise<void>;
-    handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
-    timeout: (workflowId: string) => Promise<void>;
-    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
-};
+export type { TimeOperationCallbacks };
 export declare function createDelayedStartTimerEntry(_internals: EngineInternals, workflowId: string, scheduledStartAt: number, options: StartOptions | undefined, callbacks: Pick<TimeOperationCallbacks, 'parseStartOptionDuration'>): TimerEntry;
 export declare function processSleepOperation(internals: EngineInternals, workflowId: string, operation: SleepOperation, callbacks: Pick<TimeOperationCallbacks, 'completeOperation' | 'loadWorkflowState'>): Promise<void>;
 export declare function registerSleepResolver(internals: EngineInternals, workflowId: string, operationId: string, resolve: () => void, scheduledFireAt: number): void;
-export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
-export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'workflowVersionTupleFromState'>): Promise<void>;
-export {};
+export declare function startDelayedWorkflow(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'beginWorkflowExecution' | 'dispatchEvent' | 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'resolveExecutableRegistrationForRevision' | 'runSerializedWorkflowStateWrite' | 'setWorkflowStartHeaders' | 'workflowVersionTupleFromState'>): Promise<void>;
+export declare function handleTimerFired(internals: EngineInternals, entry: TimerEntry, callbacks: Pick<TimeOperationCallbacks, 'failWorkflow' | 'handleCleanupError' | 'loadWorkflowStartHeaders' | 'loadWorkflowState' | 'runDeferredTerminalCleanup' | 'runWorkflowFinalizer' | 'runSerializedWorkflowStateWrite' | 'handleScheduleTimer' | 'setWorkflowStartHeaders' | 'timeout' | 'beginWorkflowExecution' | 'dispatchEvent' | 'resolveExecutableRegistrationForRevision' | 'workflowVersionTupleFromState'>): Promise<void>;

package/dist/core/engine/operations-time.js

@@ -4,7 +4,9 @@ import { encode } from "../codec.js";
 import { buildTimerBatchOperations, normalizeStorageTimestamp } from "../scheduler.js";
 import { notifyConditionWaiters, notifyConditionWaitersForTimerFire } from "./condition-waiters.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
+import { resolveDelayedStartRegistrationOrFail } from "./lifecycle/delayed-start-registration.js";
 import { reprovideRecoveredServices } from "./lifecycle/recovered-services.js";
+import { ensureDelayedStartClaimAndCleanupBeforeFailure } from "./lifecycle/standalone-claim-acquire.js";
 import {
   acknowledgeSupersededSleepTimers,
   handleSleepTimerWithAcknowledgement,
@@ -88,23 +90,22 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   const checkpoint = await loadDelayedWorkflowCheckpoint(internals, entry, callbacks);
   if (!checkpoint)
     return;
-  const registration = internals.registrations.get(state.type);
-  if (!registration) {
-    await callbacks.failWorkflow(entry.workflowId, Error(`No workflow registered with name "${state.type}"`));
+  const resolvedRegistration = await resolveDelayedStartRegistrationOrFail(internals, entry, state.type, state.revision, callbacks);
+  if (resolvedRegistration === null)
     return;
-  }
-  const now = internals.options.getNow(), executionDeadline = await resolveDelayedExecutionDeadline(entry, now, callbacks);
+  const { entry: registration, revision: resolvedRevision } = resolvedRegistration, now = internals.options.getNow(), executionDeadline = await resolveDelayedExecutionDeadline(internals, entry, now, callbacks);
   if (executionDeadline === "invalid")
     return;
   const runningState = await callbacks.runSerializedWorkflowStateWrite(entry.workflowId, async () => {
     const latestState = await callbacks.loadWorkflowState(entry.workflowId);
     if (!latestState || latestState.status !== "pending")
       return null;
-    const nextRunningState = {
+    const effectiveRevision = latestState.revision ?? resolvedRevision, nextRunningState = {
       ...latestState,
       status: "running",
       startedAt: now,
       updatedAt: now,
+      ...effectiveRevision !== void 0 && { revision: effectiveRevision },
       ...executionDeadline !== void 0 && { executionDeadline }
     }, operations = [
       {
@@ -136,7 +137,7 @@ export async function startDelayedWorkflow(internals, entry, callbacks) {
   internals.checkpoints.set(entry.workflowId, checkpoint);
   internals.workflowVersionTuples.set(entry.workflowId, callbacks.workflowVersionTupleFromState(runningState));
   callbacks.setWorkflowStartHeaders(entry.workflowId, await callbacks.loadWorkflowStartHeaders(entry.workflowId));
-  callbacks.beginWorkflowExecution(entry.workflowId, runningState.workflowExecutionToken, runningState.type, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
+  callbacks.beginWorkflowExecution(entry.workflowId, runningState.workflowExecutionToken, runningState.type, runningState.revision, runningState.input, checkpoint, executionDeadline, runningState.executionStateOwnerId ?? entry.workflowId, registration);
 }
 async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
   const checkpointBytes = await internals.storage.get(KEYS.checkpoint(entry.workflowId));
@@ -146,21 +147,22 @@ async function loadDelayedWorkflowCheckpoint(internals, entry, callbacks) {
   }
   return deserializeCheckpoint(checkpointBytes);
 }
-async function resolveDelayedExecutionDeadline(entry, now, callbacks) {
+async function resolveDelayedExecutionDeadline(internals, entry, now, callbacks) {
   if (entry.executionTimeoutMs === void 0)
     return;
   if (!Number.isFinite(entry.executionTimeoutMs) || entry.executionTimeoutMs < 0) {
-    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    await failInvalidDelayedExecutionTimeout(internals, entry, callbacks);
     return "invalid";
   }
   try {
     return normalizeStorageTimestamp(now + entry.executionTimeoutMs, `Delayed execution timeout for workflow "${entry.workflowId}"`);
   } catch {
-    await failInvalidDelayedExecutionTimeout(entry, callbacks);
+    await failInvalidDelayedExecutionTimeout(internals, entry, callbacks);
     return "invalid";
   }
 }
-async function failInvalidDelayedExecutionTimeout(entry, callbacks) {
+async function failInvalidDelayedExecutionTimeout(internals, entry, callbacks) {
+  await ensureDelayedStartClaimAndCleanupBeforeFailure(internals, entry.workflowId);
   await callbacks.failWorkflow(entry.workflowId, Error(`Invalid delayed execution timeout for workflow "${entry.workflowId}"`));
 }
 export async function handleTimerFired(internals, entry, callbacks) {

package/dist/core/engine/ownership-bootstrap.d.ts

@@ -85,7 +85,7 @@ export type WorkflowLeaseOwnershipBootstrapOptions = {
      * doc for why an engine that cannot execute a candidate's registered type
      * must never win its claim in the first place.
      */
-    isWorkflowTypeRegistered?: (workflowType: string) => boolean;
+    isWorkflowTypeRegistered?: (workflowType: string, revision: string | undefined) => boolean;
 };
 /**
  * Everything `Engine` needs to hold on `EngineInternals` once bootstrap

package/dist/core/engine/pinned-schedule-revision-count.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Count schedules pinned to an exact `(type, revision)` (WFT-20). Wired into
+ * `catalog-removal.ts`'s `countWorkflowRevisionReferences()`, replacing the
+ * `pinnedSchedules: 0` stub WFT-12 left in place pending this batch (see
+ * that field's own doc comment: "always 0 until WFT-20").
+ *
+ * Mirrors `nonterminal-revision-count.ts`'s bounded-scan shape exactly: only
+ * top-level `schedule:{id}` records are schedule states — `schedule:{id}:*`
+ * suffix keys (timer index, run metadata) share the `schedule:` prefix but
+ * are not, the same skip `listSchedules`/`recoverOrphanedScheduleTimers`
+ * already apply.
+ *
+ * @module core/engine/pinned-schedule-revision-count
+ */
+import type { Storage } from '../../storage/interface.ts';
+/**
+ * Scan `storage` for schedules whose `workflowType` and `pinnedRevision`
+ * match exactly, returning the count. Only `revisionPolicy: 'pinned'`
+ * schedules ever count — an `'active-at-fire'` schedule against the same
+ * `(type, revision)` never blocks removal, since it resolves whatever is
+ * active at each future fire regardless of what is being removed now. A
+ * `'cancelled'` pinned schedule is excluded too: it will never fire again,
+ * so it must not block removal of the revision it once pinned. A `'paused'`
+ * pinned schedule still counts — it can be resumed and fire again later.
+ */
+export declare function countPinnedSchedulesForRevision(storage: Storage, type: string, revision: string): Promise<number>;

package/dist/core/engine/pinned-schedule-revision-count.js

@@ -0,0 +1,19 @@
+import { decodeScheduleState } from "./validation/schedule.js";
+export async function countPinnedSchedulesForRevision(storage, type, revision) {
+  let count = 0;
+  for await (const [key, bytes] of storage.scan("schedule:")) {
+    if (key.slice(9).includes(":"))
+      continue;
+    const state = decodeScheduleState(bytes);
+    if (!state)
+      continue;
+    if (state.workflowType !== type)
+      continue;
+    if (state.revisionPolicy !== "pinned" || state.pinnedRevision !== revision)
+      continue;
+    if (state.status === "cancelled")
+      continue;
+    count += 1;
+  }
+  return count;
+}

package/dist/core/engine/pinned-schedule-revision.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Revision resolution for a `revisionPolicy: 'pinned'` schedule (WFT-20):
+ * capture-time resolution (what revision would run right now, recorded on
+ * the schedule) and fire-time resolution (resolve and reserve EXACTLY the
+ * captured revision, enforcing a real, checkable commitment for an eager
+ * workflow type rather than silently degrading to active-at-fire behavior).
+ *
+ * Fire-time resolution deliberately does NOT reuse
+ * `resolveExecutableRegistrationForRevision()` unchanged for an eager type:
+ * that resolver's documented "eager ignores the pin" rule is correct for
+ * run RECOVERY (a process only ever runs the code it has loaded, so a stale
+ * pin on an eager type is harmless) but wrong for a schedule's
+ * forward-looking commitment — silently falling back to whatever is active
+ * would make a "pinned" schedule lie about what it guarantees, and would
+ * make `pinnedSchedules` reference-count accounting
+ * ({@link import('./pinned-schedule-revision-count.ts').countPinnedSchedulesForRevision})
+ * block removal of a revision nothing will ever actually run again.
+ *
+ * @module core/engine/pinned-schedule-revision
+ */
+import type { ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { ScheduleRevisionPolicy } from '../types.ts';
+import { type ExecutableRegistration } from './dynamic-source-execution.ts';
+import type { Engine } from './index.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Capture-time resolution: the revision that would run RIGHT NOW for `type`,
+ * reusing the same resolver (and revision-selection rule) a fresh
+ * `engine.start()` call would use. Called by `schedule()`/`updateSchedule()`
+ * when a caller requests `revisionPolicy: 'pinned'`, so the captured
+ * {@link import('../types/schedules.ts').ScheduleMetadata.pinnedRevision} is
+ * exactly what would have run had the schedule fired at this instant. No
+ * `inFlightStartsByRevision` reservation here — this is not launching a
+ * workflow, only recording a decision; the write that persists the pin is
+ * separately fenced against a concurrent `removeWorkflowRevision()` via
+ * `buildCatalogEntryRevisionCondition` at the `writeScheduleState` call site.
+ */
+export declare function resolveScheduleRevisionForPin(engine: Engine, internals: EngineInternals, type: string): Promise<string>;
+/**
+ * `schedule()`'s create-time revision resolution — split out to keep that
+ * function under the complexity ceiling. For `revisionPolicy: 'pinned'`,
+ * captures and returns the current revision via
+ * {@link resolveScheduleRevisionForPin} (which already resolves, and for a
+ * lazy type loads, `type` internally). For `'active-at-fire'`, returns
+ * `undefined` and — for a lazy type not yet eagerly registered — resolves
+ * once here purely to trigger the loader at schedule-creation time, exactly
+ * as before this revision-policy field existed.
+ */
+export declare function resolveScheduleCreationRevision(internals: EngineInternals, type: string, revisionPolicy: ScheduleRevisionPolicy): Promise<string | undefined>;
+/**
+ * Fire-time resolve-and-reserve for a pinned schedule occurrence — the
+ * pinned-revision counterpart of
+ * `catalog-removal.ts`'s `resolveAndReserveExecutableRegistration`, reusing
+ * the identical early/late `inFlightStartsByRevision` reservation shape so a
+ * concurrent `removeWorkflowRevision()` sees an in-flight reference the same
+ * way it would for an ordinary start.
+ */
+export declare function resolveAndReservePinnedExecutableRegistration(engine: Engine, internals: EngineInternals, type: string, revision: string): Promise<{
+    registration: ExecutableRegistration['entry'];
+    inFlightRevision: string | undefined;
+    resolvedRevision: string | undefined;
+}>;
+/**
+ * The `writeScheduleState` `extraConditions`/`onExtraConditionsLost` options
+ * that fence a pinned schedule's create/update write against a concurrent
+ * `removeWorkflowRevision()` landing between {@link resolveScheduleRevisionForPin}'s
+ * capture and this commit — see `storage-io.ts`'s `writeScheduleState` doc for
+ * why this is necessary (the scan-based `pinnedSchedules` reference count
+ * cannot see an uncommitted schedule write, so `removeWorkflowRevision()`'s
+ * own reference check cannot block it on its own). `undefined` (no fencing)
+ * when `pinnedRevision` is `undefined` — this write is not pinning.
+ */
+export declare function buildPinnedRevisionWriteOptions(internals: EngineInternals, type: string, pinnedRevision: string | undefined): Promise<{
+    extraConditions: ConditionalBatchCondition[];
+    onExtraConditionsLost: () => Error;
+} | undefined>;

package/dist/core/engine/pinned-schedule-revision.js

@@ -0,0 +1,53 @@
+import { releaseInFlightStart, reserveInFlightStart } from "./catalog-removal.js";
+import {
+  resolveExecutableRegistration,
+  resolveExecutableRegistrationForRevision
+} from "./dynamic-source-execution.js";
+import { buildCatalogEntryRevisionCondition } from "./lifecycle/start-commit.js";
+import {
+  resolveCachedStartRevision,
+  resolveStartRevisionUncached
+} from "./lifecycle/start-revision-resolution.js";
+import { WorkflowRevisionUnavailableError } from "./revision-errors.js";
+export async function resolveScheduleRevisionForPin(engine, internals, type) {
+  const { revision: resolvedRevision } = await resolveExecutableRegistration(engine, internals, type);
+  return resolveCachedStartRevision(internals, type, resolvedRevision) ?? await resolveStartRevisionUncached(internals, type);
+}
+async function resolvePinnedExecutableRegistration(engine, internals, type, revision, onRevisionChosen) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0) {
+    if (internals.registeredCatalogRevisions.get(type) !== revision)
+      throw new WorkflowRevisionUnavailableError(type, revision, "not-registered");
+    onRevisionChosen?.(revision);
+    return { entry: eager, revision: void 0 };
+  }
+  onRevisionChosen?.(revision);
+  return resolveExecutableRegistrationForRevision(engine, internals, type, revision);
+}
+export async function resolveScheduleCreationRevision(internals, type, revisionPolicy) {
+  if (revisionPolicy === "pinned")
+    return resolveScheduleRevisionForPin(internals.engine, internals, type);
+  if (!internals.registrations.has(type))
+    await resolveExecutableRegistration(internals.engine, internals, type);
+  return;
+}
+export async function resolveAndReservePinnedExecutableRegistration(engine, internals, type, revision) {
+  let earlyReservation;
+  try {
+    const { entry: registration, revision: resolvedRevision } = await resolvePinnedExecutableRegistration(engine, internals, type, revision, (chosen) => {
+      earlyReservation = reserveInFlightStart(internals, type, chosen);
+    }), inFlightRevision = earlyReservation !== void 0 ? earlyReservation : reserveInFlightStart(internals, type, resolvedRevision);
+    return { registration, inFlightRevision, resolvedRevision };
+  } catch (error) {
+    releaseInFlightStart(internals, type, earlyReservation);
+    throw error;
+  }
+}
+export async function buildPinnedRevisionWriteOptions(internals, type, pinnedRevision) {
+  if (pinnedRevision === void 0)
+    return;
+  return {
+    extraConditions: [await buildCatalogEntryRevisionCondition(internals, type, pinnedRevision)],
+    onExtraConditionsLost: () => new WorkflowRevisionUnavailableError(type, pinnedRevision, "not-installed")
+  };
+}

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

@@ -6,6 +6,13 @@ export type RegistrationCallbacks = {
     ensureRetentionSweepInterval: () => void;
     dispatchEvent: (event: Event) => void;
 };
+/**
+ * Reject constraints on a workflow definition when the engine has no
+ * inline execution strategy. Exported so `dynamic-source-execution.ts`
+ * (WFT-15/16) can apply the identical guard to a dynamically-resolved
+ * definition — see that module's own call site.
+ */
+export declare function assertConstraintsSupported(internals: EngineInternals, name: string, registration: WorkflowDefinition): void;
 /**
  * Build the `RegistrationEntry` `engine.register()` would store for
  * `registration`, without committing anything — pure normalization
@@ -28,6 +35,29 @@ export type RegistrationCallbacks = {
  * ```
  */
 export declare function buildRegistrationEntry(name: string, registration: WorkflowDefinition): RegistrationEntry;
+/**
+ * Visit every RESOLVED `registerSource()`-registered type's normalized
+ * retention policy (via {@link buildRegistrationEntry}) — the dynamic-source
+ * counterpart to walking `internals.registrations.values()` directly for an
+ * eager type. Used by `bulk-operations-purge.ts` so a dynamic workflow's own
+ * (possibly shorter) retention window narrows the purge sweep's scan bound
+ * the same way an eager registration's does.
+ */
+export declare function forEachResolvedDynamicRetentionPolicy(internals: EngineInternals, visit: (policy: RegistrationEntry['retention']) => void): void;
+/**
+ * True when at least one `registerSource()`-registered type has a
+ * registered candidate revision this process has NOT yet resolved — its
+ * retention policy (and everything else `buildRegistrationEntry` would
+ * derive) is genuinely unknown, so `getMinimumRetentionMs()`'s scan-bound
+ * optimization in `bulk-operations-purge.ts` cannot be trusted (WFT-19
+ * review round 1): it silently excluded exactly this class of workflow
+ * from the periodic retention sweep's scan bound, since an unresolved
+ * candidate's possibly-shorter-than-default retention window was invisible
+ * to the minimum computation. Used to fall back to an unbounded terminal
+ * scan while any such candidate remains unresolved — self-healing once
+ * `shouldPurgeWorkflowState`'s own per-run resolve installs it.
+ */
+export declare function hasUnresolvedDynamicSourceCandidate(internals: EngineInternals): boolean;
 /**
  * Structural predicate for `BuiltWorkflowDefinition` — the runtime shape
  * `workflow({ name }).execute(...)` returns. Exported so the dynamic

package/dist/core/engine/registration.js

@@ -15,7 +15,7 @@ function copiedTags(tags) {
 function isWorkflowDefinition(value) {
   return typeof value === "object" && value !== null && "name" in value && "handler" in value && typeof value.handler === "function";
 }
-function assertConstraintsSupported(internals, name, registration) {
+export function assertConstraintsSupported(internals, name, registration) {
   if (!registration.constraints || registration.constraints.length === 0)
     return;
   if (internals.inlineStrategy === null)
@@ -68,6 +68,20 @@ export function buildRegistrationEntry(name, registration) {
   }
   return entry;
 }
+export function forEachResolvedDynamicRetentionPolicy(internals, visit) {
+  for (const [type, revisions] of internals.sources.resolved)
+    for (const resolved of revisions.values())
+      visit(buildRegistrationEntry(type, resolved.definition).retention);
+}
+export function hasUnresolvedDynamicSourceCandidate(internals) {
+  for (const [type, byRevision] of internals.sources.byName) {
+    const resolvedForType = internals.sources.resolved.get(type);
+    for (const revision of byRevision.keys())
+      if (resolvedForType?.has(revision) !== !0)
+        return !0;
+  }
+  return !1;
+}
 function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
   const normalized = Object.create(null), sortedDefinitions = Object.values(definitions).toSorted((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
   for (const definition of sortedDefinitions) {
@@ -80,13 +94,14 @@ function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
 function commitWorkflowDefinition(internals, definition, callbacks) {
   const name = definition.name;
   validateWorkflowOrActivityName(name, "workflow");
-  if (internals.workflowSourcesByName.has(name))
+  if (internals.sources.byName.has(name))
     throw Error(`Cannot register("${name}"): "${name}" is already registered as a dynamic workflow source via engine.registerSource(). A workflow name may not be both eagerly registered and a dynamic source.`);
   assertConstraintsSupported(internals, name, definition);
   const entry = buildRegistrationEntry(name, definition);
   internals.registrations.set(name, entry);
   callbacks.ensureRetentionSweepInterval();
   internals.workflowTypesByHandler.set(definition.handler, name);
+  internals.registeredCatalogRevisions.delete(name);
   if (!internals.pendingCatalogInstalls.includes(name))
     internals.pendingCatalogInstalls.push(name);
   callbacks.dispatchEvent(new WorkflowDefinitionRegisteredEvent(name));

package/dist/core/engine/retention.js

@@ -1,10 +1,15 @@
 import { purgeInternal } from "./bulk-operations.js";
+import { resolveLastKnownDynamicRegistration } from "./dynamic-source-execution.js";
 export function hasConfiguredRetention(internals) {
   if (internals.options.retention !== null)
     return !0;
   for (const registration of internals.registrations.values())
     if (registration.retention !== void 0 && registration.retention !== null)
       return !0;
+  for (const revisions of internals.sources.resolved.values())
+    for (const resolved of revisions.values())
+      if (resolved.definition.retention !== void 0 && resolved.definition.retention !== null)
+        return !0;
   return !1;
 }
 export function setNextRetentionSweepAt(internals) {
@@ -49,7 +54,7 @@ export async function runRetentionSweep(internals, handleCleanupError, cleanupWa
   }
 }
 export function resolveWorkflowTypeRetention(internals, type) {
-  const registration = internals.registrations.get(type);
+  const registration = resolveLastKnownDynamicRegistration(internals, type);
   if (registration?.retention)
     return {
       type,
@@ -69,7 +74,9 @@ export function resolveWorkflowTypeRetention(internals, type) {
   };
 }
 export function getRetentionOverview(internals, resolveRetentionForType = (type) => resolveWorkflowTypeRetention(internals, type)) {
-  const workflowTypes = [...internals.registrations.keys()].toSorted().map((type) => resolveRetentionForType(type));
+  const workflowTypes = [
+    ...new Set([...internals.registrations.keys(), ...internals.sources.byName.keys()])
+  ].toSorted().map((type) => resolveRetentionForType(type));
   return {
     defaultRetention: internals.options.retention,
     sweepIntervalMs: internals.options.retentionSweepIntervalMs,

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

@@ -0,0 +1,71 @@
+/**
+ * {@link WorkflowRevisionUnavailableError} (WFT-17/WFT-18) — thrown by
+ * {@link import('./dynamic-source-execution.ts').resolveExecutableRegistrationForRevision}
+ * when a resumed run's persisted, EXACT pinned `WorkflowState.revision` cannot
+ * be resolved in this process. Distinct from
+ * {@link import('./dynamic-source-errors.ts').DynamicWorkflowSourceUnavailableError},
+ * which covers a dynamic source whose ACTIVE revision is ambiguous or fails
+ * to load — this error instead covers "the run's own pin cannot be honored",
+ * which can also happen for a legacy (pre-revision-pinning) record on a
+ * dynamic source with two or more registered candidates, where there is no
+ * pin at all and the ambiguity cannot be resolved by falling back to
+ * whichever revision happens to be active (that fallback is exactly the bug
+ * this batch closes — see `documentation/guides/recovery-and-deploys.md`).
+ *
+ * @module core/engine/revision-errors
+ */
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown when a workflow run's pinned {@link import('../types/state.ts').WorkflowState.revision}
+ * cannot be resolved to an executable registration in this process:
+ *
+ * - `reason: 'not-registered'` — the run pins a specific revision (a
+ *   dynamic-source candidate this process has never `registerSource()`-registered,
+ *   including the case where the pin no longer matches a dynamic source's sole
+ *   remaining candidate).
+ * - `reason: 'legacy-ambiguous'` — the run predates revision pinning (no
+ *   `revision` was ever persisted for it) and its type is a dynamic source
+ *   with two or more registered candidates, so there is no way to tell which
+ *   one it actually started against.
+ * - `reason: 'not-installed'` — thrown at commit-time ADMISSION, not
+ *   recovery, for either a fresh `start()` or a checkpoint-backed failed-run
+ *   `retryFailedAll()` reactivation (WFT-17/WFT-18 Codex review on PR #958):
+ *   the resolved (or pinned) revision's durable catalog entry was
+ *   concurrently removed — `removeWorkflowRevision()` racing a `start()` on
+ *   a DIFFERENT process under a lease ownership mode, or racing a
+ *   `retryFailedAll()` on ANY process/mode, since a failed run contributes no
+ *   `inFlightStartsByRevision` reservation of its own — between this
+ *   process resolving the revision and that commit batch actually landing.
+ *   Fails the one call outright — never retried inside the engine — so the
+ *   caller re-issues it, which re-resolves against whatever is actually
+ *   still installed.
+ *
+ * `engine.recoverAll()` classifies the affected `(type, revision)` group
+ * `unavailable`: only the runs in that group fail (with this error as their
+ * `system` failure cause, delivered via `failWorkflow()`/`onRecoveredWorkflow`,
+ * never thrown to `recoverAll()`'s own caller); sibling groups — including
+ * OTHER revisions of the same dynamic-source type — continue recovering
+ * normally. A standalone `engine.resume(workflowId)` call has no such
+ * isolation to fall back on — there is only the one run — so it throws this
+ * error directly to its caller instead.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowRevisionUnavailableError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.resume('workflow-id');
+ * } catch (err) {
+ *   if (err instanceof WorkflowRevisionUnavailableError) {
+ *     console.error(err.workflowType, err.revision, err.reason);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowRevisionUnavailableError extends WeftError<'WorkflowRevisionUnavailableError'> {
+    readonly workflowType: string;
+    readonly revision: string | undefined;
+    readonly reason: 'not-registered' | 'legacy-ambiguous' | 'not-installed';
+    constructor(workflowType: string, revision: string | undefined, reason: 'not-registered' | 'legacy-ambiguous' | 'not-installed');
+}

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

@@ -0,0 +1,13 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowRevisionUnavailableError extends WeftError {
+  workflowType;
+  revision;
+  reason;
+  constructor(workflowType, revision, reason) {
+    super("WorkflowRevisionUnavailableError", reason === "legacy-ambiguous" ? `Cannot recover workflow type "${workflowType}": this run predates revision pinning and the type is a dynamic source with multiple registered revisions, so which one it started against cannot be determined.` : reason === "not-installed" ? `Cannot admit workflow type "${workflowType}": revision${revision === void 0 ? "" : ` "${revision}"`} is no longer installed in the durable catalog (removed concurrently). Retry the operation.` : `Cannot recover workflow type "${workflowType}": its pinned revision${revision === void 0 ? "" : ` "${revision}"`} is not registered in this process. Register the exact revision this run started against before retrying.`);
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.reason = reason;
+  }
+}

package/dist/core/engine/schedule-overlap.js

@@ -44,7 +44,8 @@ export async function drainQueuedScheduleRun(state, callbacks, completedWorkflow
     workflowId: queuedRun.workflowId,
     ...queuedRun.occurrence !== void 0 && { occurrence: queuedRun.occurrence },
     scheduleStateAfterStart: stateAfterStart,
-    ...completedWorkflowId !== void 0 && { completedWorkflowId }
+    ...completedWorkflowId !== void 0 && { completedWorkflowId },
+    skipAdmissionIdCheck: !0
   });
   return stateAfterStart;
 }

package/dist/core/engine/schedule-revision-fire.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The pinned-vs-active-at-fire branch point for a scheduled occurrence
+ * (WFT-20), split into its own tiny module so `schedule-run.ts` — a
+ * deliberately small, purpose-built module — has one obvious call site
+ * instead of inlining the branch.
+ *
+ * @module core/engine/schedule-revision-fire
+ */
+import type { ScheduleState } from '../types.ts';
+/**
+ * The revision override `startScheduledRun` should pass to
+ * `ScheduleCallbacks.startWorkflow` for this occurrence: `state.pinnedRevision`
+ * when `state.revisionPolicy === 'pinned'`, else `undefined` (an
+ * `'active-at-fire'` schedule resolves whatever revision is active at fire
+ * time, unchanged from pre-WFT-20 behavior).
+ */
+export declare function buildPinnedRevisionOverride(state: ScheduleState): string | undefined;

package/dist/core/engine/schedule-revision-fire.js

@@ -0,0 +1,3 @@
+export function buildPinnedRevisionOverride(state) {
+  return state.revisionPolicy === "pinned" ? state.pinnedRevision : void 0;
+}

package/dist/core/engine/schedule-run.d.ts

@@ -9,6 +9,16 @@ export type ScheduledRunStartOptions = {
     scheduleStateAfterStart?: ScheduleState;
     /** Prior terminal run whose transient schedule metadata is now settled. */
     completedWorkflowId?: string;
+    /**
+     * Internal only (WFT-95). Set by `drainQueuedScheduleRun()` when `workflowId`
+     * is a persisted `queuedRuns[].workflowId` being replayed, not a freshly
+     * minted one — safe unconditionally, since a post-fix queued run was already
+     * validated as non-`.`/`..` at schedule-admission time (relaxing the check
+     * here is then a no-op), and it is what lets a legacy pre-WFT-95 queued run
+     * whose id is `.`/`..` keep draining instead of pausing the schedule.
+     * Threaded straight through to `startWorkflow`'s `skipAdmissionIdCheck`.
+     */
+    skipAdmissionIdCheck?: boolean;
 };
 /**
  * Launch one scheduled occurrence's workflow run and emit `schedule:fired`.

package/dist/core/engine/schedule-run.js

@@ -3,6 +3,7 @@ import { encode } from "../codec.js";
 import { ScheduleFiredEvent } from "../events.js";
 import { unavailableServicesError } from "./lifecycle/recovered-services.js";
 import { EMPTY_STORAGE_VALUE } from "./lifecycle/shared.js";
+import { buildPinnedRevisionOverride } from "./schedule-revision-fire.js";
 import { encodeScheduleRunMetadata } from "./schedule-run-metadata.js";
 export async function startScheduledRun(internals, state, callbacks, options = {}) {
   const workflowId = options.workflowId ?? crypto.randomUUID(), occurrence = options.occurrence, metadata = encodeScheduleRunMetadata(state.id, occurrence), scheduleRunOperations = [
@@ -49,7 +50,7 @@ export async function startScheduledRun(internals, state, callbacks, options = {
       internals.workflowServices.set(workflowId, resolution.services);
   }
   internals.workflowsNeedingTerminalCleanup.add(workflowId);
-  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations);
+  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations, buildPinnedRevisionOverride(state), options.skipAdmissionIdCheck);
   internals.engine.dispatchEvent(new ScheduleFiredEvent(state.id, workflowId, internals.options.getNow(), occurrence));
   if (resolution !== null && resolution.status === "unavailable") {
     const unavailableError = unavailableServicesError(workflowId, resolution.reason);

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

@@ -10,9 +10,19 @@ export type RefreshedScheduleState = {
     currentWorkflowState: WorkflowState | null;
 };
 export type ScheduleCallbacks = {
+    /**
+     * `revisionOverride` (WFT-20) is the exact revision a `revisionPolicy: 'pinned'`
+     * occurrence must resolve against; `undefined` for an `'active-at-fire'` schedule.
+     *
+     * `skipAdmissionIdCheck` (WFT-95, internal only) is threaded straight through to
+     * `startWorkflow`'s parameter of the same name — see its doc comment. Set only when
+     * replaying a schedule's already-persisted `queuedRuns[].workflowId` via
+     * `drainQueuedScheduleRun()`; every other schedule-run start (a fresh cadence tick,
+     * a `cancel-running` replacement) omits it and gets strict id admission.
+     */
     startWorkflow: (type: string, input: unknown, options: {
         id: string;
-    }, additionalStartOperations?: BatchOperation[]) => Promise<void>;
+    }, additionalStartOperations?: BatchOperation[], revisionOverride?: string, skipAdmissionIdCheck?: boolean) => Promise<void>;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null | undefined>;
     cancelWorkflow: (workflowId: string) => Promise<void>;
     getWorkflowResult: (workflowId: string) => Promise<unknown>;