@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -1,7 +1,113 @@
+import { ActivityRegistry } from '../activity-registry.ts';
+import { type ActivityDefinition, type QueryDefinition, type SignalDefinition, type UpdateDefinition, type WorkflowDefinition } from '../types.ts';
+import type { RegistrationEntry } from './engine-internal-types.ts';
 import type { EngineInternals } from './internals.ts';
 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
+ * (base fields, optional fields, and, for a builder-produced definition,
+ * signal/update/query name-collision checks). Exported so the dynamic
+ * workflow-source validation pipeline (`core/source/validate.ts`, WFT-13/14)
+ * can normalize a loaded module's exported definition through the identical
+ * path `engine.register()` uses, rather than re-deriving a
+ * `RegistrationEntry` independently and risking the two producers drifting
+ * apart.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet' }).execute(async function* (_ctx, input: string) {
+ *   return `hello ${input}`;
+ * });
+ * console.log(greet.name);
+ * ```
+ */
+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
+ * workflow-source validation pipeline (`core/source/validate.ts`, WFT-13/14)
+ * can reject a loaded export that is a hand-rolled `{ name, handler }`
+ * literal rather than a builder-produced definition — the same "removed
+ * bare-handler shape" rejection `engine.register()` itself applies via
+ * {@link buildRegistrationEntry}.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet' }).execute(async function* (_ctx, input: string) {
+ *   return `hello ${input}`;
+ * });
+ * console.log(typeof greet.activities === 'object');
+ * ```
+ */
+export declare function isBuilderWorkflowDefinition(value: unknown): value is WorkflowDefinition & {
+    readonly activities: Readonly<Record<string, Readonly<ActivityDefinition>>>;
+    readonly signals: Readonly<Record<string, Readonly<SignalDefinition<unknown>>>>;
+    readonly updates: Readonly<Record<string, Readonly<UpdateDefinition<unknown>>>>;
+    readonly queries: Readonly<Record<string, Readonly<QueryDefinition<unknown>>>>;
+    readonly searchAttributes: Readonly<Record<string, unknown>>;
+};
+/**
+ * Build a fresh per-workflow {@link ActivityRegistry} from a builder workflow's
+ * activities map. Each entry is defensively deep-cloned and then turned into a
+ * fresh `ActivityCallable` via {@link activity}, so the engine's registry holds
+ * its own callable references and the user's `BuiltWorkflowDefinition` cannot
+ * influence dispatch by post-registration mutation.
+ *
+ * Exported so the dynamic workflow-source validation pipeline
+ * (`core/source/validate.ts`, WFT-13/14) can build the same
+ * uncommitted-but-canonical per-workflow registry for a loaded module's
+ * export that `engine.register()` builds for an eagerly registered one —
+ * required so {@link import('../registry-workflow-manifest.ts').buildWorkflowManifestFromDefinition}
+ * produces byte-identical manifests for the two paths.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from '@lostgradient/weft';
+ *
+ * const greet = workflow({ name: 'greet' }).execute(async function* (_ctx, input: string) {
+ *   return `hello ${input}`;
+ * });
+ * console.log(Object.keys(greet.activities).length);
+ * ```
+ */
+export declare function buildPerWorkflowActivityRegistry(activities: Readonly<Record<string, Readonly<ActivityDefinition>>>): ActivityRegistry;
 export declare function register(internals: EngineInternals, definition: unknown, callbacks: RegistrationCallbacks): void;
 export declare function resolveWorkflowTypeTarget(internals: EngineInternals, target: string | Function, _callbacks: RegistrationCallbacks): string;

package/dist/core/engine/registration.js

@@ -1,3 +1,4 @@
+import { isRecord } from "../../worker/manifest/is-record.js";
 import { ActivityRegistry } from "../activity-registry.js";
 import { WorkflowDefinitionRegisteredEvent } from "../events.js";
 import {
@@ -6,14 +7,15 @@ import {
 } from "../types.js";
 import { clonePlain } from "../types/clone-plain.js";
 import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
 import { normalizeRetentionPolicy } from "./validation.js";
 function copiedTags(tags) {
   return tags === void 0 ? void 0 : [...tags];
 }
 function isWorkflowDefinition(value) {
-  return typeof value === "object" && value !== null && "name" in value && "handler" in 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)
@@ -23,7 +25,7 @@ function buildBaseRegistrationEntry(name, registration) {
   const tags = copiedTags(registration.tags), normalizedRetention = normalizeRetentionPolicy(registration.retention, `registration("${name}").retention`);
   return {
     handler: registration.handler,
-    version: registration.version ?? "1",
+    version: registration.version ?? DEFAULT_WORKFLOW_VERSION,
     ...registration.description === void 0 ? {} : { description: registration.description },
     ...tags === void 0 ? {} : { tags },
     ...registration.inputSchema === void 0 ? {} : {
@@ -56,7 +58,7 @@ function applyOptionalRegistrationFields(entry, registration) {
   if (registration.finalizer !== void 0)
     entry.finalizer = registration.finalizer;
 }
-function buildRegistrationEntry(name, registration) {
+export function buildRegistrationEntry(name, registration) {
   const entry = buildBaseRegistrationEntry(name, registration);
   applyOptionalRegistrationFields(entry, registration);
   if (isBuilderWorkflowDefinition(registration)) {
@@ -66,6 +68,20 @@ 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) {
@@ -78,25 +94,30 @@ function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
 function commitWorkflowDefinition(internals, definition, callbacks) {
   const name = definition.name;
   validateWorkflowOrActivityName(name, "workflow");
+  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));
 }
 function hasNonNullObjectField(value, key) {
   if (!(key in value))
     return !1;
   const fieldValue = value[key];
-  return typeof fieldValue === "object" && fieldValue !== null;
+  return isRecord(fieldValue);
 }
-function isBuilderWorkflowDefinition(value) {
+export function isBuilderWorkflowDefinition(value) {
   if (!isWorkflowDefinition(value))
     return !1;
   return hasNonNullObjectField(value, "activities") && hasNonNullObjectField(value, "signals") && hasNonNullObjectField(value, "updates") && hasNonNullObjectField(value, "queries") && hasNonNullObjectField(value, "searchAttributes");
 }
-function buildPerWorkflowActivityRegistry(activities) {
+export function buildPerWorkflowActivityRegistry(activities) {
   const registry = new ActivityRegistry;
   for (const definition of Object.values(activities)) {
     const clonedDefinition = clonePlain(definition), callable = activity(clonedDefinition);

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-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.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));
   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,10 @@ 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. */
     startWorkflow: (type: string, input: unknown, options: {
         id: string;
-    }, additionalStartOperations?: BatchOperation[]) => Promise<void>;
+    }, additionalStartOperations?: BatchOperation[], revisionOverride?: string) => Promise<void>;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null | undefined>;
     cancelWorkflow: (workflowId: string) => Promise<void>;
     getWorkflowResult: (workflowId: string) => Promise<unknown>;

package/dist/core/engine/schedules.js

@@ -1,7 +1,11 @@
 import { KEYS } from "../../storage/interface.js";
 import { decode } from "../codec.js";
-import { WorkflowNotRegisteredError } from "./errors.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
+import {
+  buildPinnedRevisionWriteOptions,
+  resolveScheduleCreationRevision,
+  resolveScheduleRevisionForPin
+} from "./pinned-schedule-revision.js";
 import { ScheduleHandle } from "./schedule-handle.js";
 import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { getNextScheduleOccurrence } from "./schedule-occurrence.js";
@@ -31,9 +35,7 @@ import {
 export { startScheduledRun } from "./schedule-run.js";
 export { handleScheduleTimer } from "./schedule-timer.js";
 export async function schedule(internals, type, input, spec, options) {
-  if (!internals.registrations.has(type))
-    throw new WorkflowNotRegisteredError(type);
-  const normalizedSpec = normalizeScheduleSpec(spec), normalizedOptions = normalizeScheduleOptions(options), scheduleId = normalizedOptions.id ?? crypto.randomUUID();
+  const normalizedSpec = normalizeScheduleSpec(spec), normalizedOptions = normalizeScheduleOptions(options), scheduleId = normalizedOptions.id ?? crypto.randomUUID(), revisionPolicy = normalizedOptions.revisionPolicy ?? "active-at-fire", pinnedRevision = await resolveScheduleCreationRevision(internals, type, revisionPolicy);
   if (internals.pendingScheduleCreations.has(scheduleId))
     throw Error(`Schedule with id "${scheduleId}" already exists`);
   internals.pendingScheduleCreations.add(scheduleId);
@@ -52,13 +54,15 @@ export async function schedule(internals, type, input, spec, options) {
       overlap: normalizedOptions.overlap,
       backfill: normalizedOptions.backfill,
       ...normalizedOptions.jitterMs !== void 0 && { jitterMs: normalizedOptions.jitterMs },
+      revisionPolicy,
+      ...pinnedRevision !== void 0 && { pinnedRevision },
       createdAt: now,
       updatedAt: now,
       nextFireAt: getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now),
       missedFireCount: 0,
       queuedRuns: []
     };
-    await writeScheduleState(internals, state);
+    await writeScheduleState(internals, state, await buildPinnedRevisionWriteOptions(internals, type, pinnedRevision));
     return new ScheduleHandle(scheduleId, internals.engine);
   } finally {
     internals.pendingScheduleCreations.delete(scheduleId);
@@ -152,18 +156,33 @@ export async function updateSchedule(internals, scheduleId, newSpec, options) {
     const state = await requireScheduleState(internals, normalizedScheduleId), now = internals.options.getNow(), {
       cronExpression: _droppedCron,
       intervalMs: _droppedInterval,
-      ...stateWithoutCadence
-    } = state, cadenceFields = normalizedSpec.kind === "interval" ? { intervalMs: normalizedSpec.intervalMs } : { cronExpression: normalizedSpec.cronExpression }, anchorFields = normalizedSpec.kind === "interval" ? { createdAt: now } : {}, updatedState = {
-      ...stateWithoutCadence,
+      pinnedRevision: _droppedPinnedRevision,
+      ...stateWithoutCadenceOrPin
+    } = state, cadenceFields = normalizedSpec.kind === "interval" ? { intervalMs: normalizedSpec.intervalMs } : { cronExpression: normalizedSpec.cronExpression }, anchorFields = normalizedSpec.kind === "interval" ? { createdAt: now } : {};
+    let pinnedRevision, revisionFields;
+    if (normalizedOptions.revisionPolicy === void 0)
+      revisionFields = {
+        revisionPolicy: state.revisionPolicy,
+        ...state.pinnedRevision !== void 0 && { pinnedRevision: state.pinnedRevision }
+      };
+    else if (normalizedOptions.revisionPolicy === "pinned") {
+      pinnedRevision = await resolveScheduleRevisionForPin(internals.engine, internals, state.workflowType);
+      revisionFields = { revisionPolicy: "pinned", pinnedRevision };
+    } else
+      revisionFields = { revisionPolicy: "active-at-fire" };
+    const updatedState = {
+      ...stateWithoutCadenceOrPin,
       ...normalizedOptions,
       ...cadenceFields,
       ...anchorFields,
+      ...revisionFields,
       updatedAt: now,
       nextFireAt: state.status === "cancelled" ? null : getNextScheduleOccurrence({ ...cadenceFields, createdAt: now }, now)
     };
     await writeScheduleState(internals, updatedState, {
       includeTimer: state.status === "active",
-      replaceTimerFrom: state
+      replaceTimerFrom: state,
+      ...await buildPinnedRevisionWriteOptions(internals, state.workflowType, pinnedRevision)
     });
   });
 }