@lostgradient/weft 0.24.0 → 0.24.2

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

package/dist/core/engine/source-diagnostics.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Bounded per-`(name, revision)` load-state diagnostics for dynamic
+ * workflow sources (WFT-15/16): the `idle -> loading -> ready|failed`
+ * state machine, waiter-count bookkeeping, and the `loading -> cancelled`
+ * transition. The `record*`/`begin*`/`end*` functions are pure state
+ * mutation, individually unit-testable; the `*AndDispatch` wrappers pair
+ * each with the matching `workflow-source:load-*` event, gated on the pure
+ * function's boolean return so a late, orphaned settle never re-dispatches
+ * `ready`/`failed` after the key already moved to `cancelled`, and a fresh
+ * attempt for the same key resets cleanly back to `loading` first.
+ * `source-resolution.ts` calls only the `*AndDispatch` wrappers.
+ *
+ * @module core/engine/source-diagnostics
+ */
+import type { WorkflowSourceKind } from '../source/index.ts';
+import type { Engine } from './index.ts';
+import type { EngineInternals } from './internals.ts';
+import { type SourceLoadDiagnostics } from './source-runtime-state.ts';
+/** Bounded diagnostics for one `(name, revision)`, or `undefined` when no load was ever attempted. */
+export declare function readSourceLoadDiagnostics(internals: EngineInternals, name: string, revision: string): SourceLoadDiagnostics | undefined;
+/** Record that a fresh shared load for `(name, revision)` just started. */
+export declare function recordSourceLoadStarted(internals: EngineInternals, name: string, revision: string, kind: WorkflowSourceKind, now: number): void;
+/**
+ * Record a successful load, UNLESS the key already moved on (a `cancelled`
+ * transition from the last waiter releasing, or a fresh attempt already
+ * reset it back to `loading` for a NEW load this settle does not belong
+ * to). Returns whether the caller should dispatch `WorkflowSourceLoadReadyEvent`.
+ */
+export declare function recordSourceLoadReady(internals: EngineInternals, name: string, revision: string, now: number): boolean;
+/** The failed-load counterpart of {@link recordSourceLoadReady}. */
+export declare function recordSourceLoadFailed(internals: EngineInternals, name: string, revision: string, now: number, error: unknown): boolean;
+/** Increment the outstanding-waiter count for `(name, revision)`. Call once per `resolveWorkflowSource()` call, before any await. */
+export declare function beginSourceWaiter(internals: EngineInternals, name: string, revision: string): void;
+/**
+ * Decrement the outstanding-waiter count for `(name, revision)`; call in
+ * every `resolveWorkflowSource()` call's own `finally`. Returns whether
+ * this was the LAST outstanding waiter releasing while the shared load is
+ * still `loading` — the caller should transition diagnostics to
+ * `cancelled` and dispatch `WorkflowSourceLoadCancelledEvent`.
+ */
+export declare function endSourceWaiterAndCheckCancellation(internals: EngineInternals, name: string, revision: string): boolean;
+/**
+ * When a new caller joins a still-in-flight shared load whose diagnostics
+ * were marked `cancelled` (the last waiter released while the shared
+ * promise was still unsettled, and a later caller then joined that SAME
+ * orphaned promise instead of starting a fresh one — single-flight never
+ * aborts the shared load itself, only per-caller waiter interest), restore
+ * the state to `loading` so the eventual settle reaches its normal
+ * `ready`/`failed` transition instead of being silently suppressed by
+ * `recordSourceLoadReady`/`recordSourceLoadFailed`'s own `state !==
+ * 'loading'` guard. Never dispatches a fresh `WorkflowSourceLoadStartedEvent`
+ * — the load itself did not restart, only diagnostics visibility into it
+ * did. A no-op for any state other than `cancelled` (in particular,
+ * `getOrCreateSharedSourceLoad`'s cache-miss branch already sets `loading`
+ * itself via {@link recordSourceLoadStartedAndDispatch} for a genuinely new
+ * load, so this never fires there).
+ */
+export declare function reviveOrphanedSourceLoadDiagnostics(internals: EngineInternals, name: string, revision: string): void;
+/** Current outstanding-waiter count for `(name, revision)`. */
+export declare function readSourceWaiterCount(internals: EngineInternals, name: string, revision: string): number;
+/** Bundles the identity a `source-resolution.ts` call site already has in scope, so the `*AndDispatch` wrappers below take one argument instead of five. */
+export type SourceEventContext = {
+    engine: Engine;
+    internals: EngineInternals;
+    name: string;
+    revision: string;
+    kind: WorkflowSourceKind;
+};
+/** {@link recordSourceLoadStarted} plus dispatching `WorkflowSourceLoadStartedEvent`. */
+export declare function recordSourceLoadStartedAndDispatch(ctx: SourceEventContext, now: number): void;
+/** {@link recordSourceLoadReady} plus dispatching `WorkflowSourceLoadReadyEvent` when it returns `true`. */
+export declare function recordSourceLoadReadyAndDispatch(ctx: SourceEventContext, now: number): void;
+/** {@link recordSourceLoadFailed} plus dispatching `WorkflowSourceLoadFailedEvent` when it returns `true`. */
+export declare function recordSourceLoadFailedAndDispatch(ctx: SourceEventContext, now: number, error: unknown): void;
+/** {@link endSourceWaiterAndCheckCancellation} plus dispatching `WorkflowSourceLoadCancelledEvent` when it returns `true`. */
+export declare function endSourceWaiterAndDispatchCancellation(engine: Engine, internals: EngineInternals, name: string, revision: string): void;

package/dist/core/engine/source-diagnostics.js

@@ -0,0 +1,105 @@
+import {
+  WorkflowSourceLoadCancelledEvent,
+  WorkflowSourceLoadFailedEvent,
+  WorkflowSourceLoadReadyEvent,
+  WorkflowSourceLoadStartedEvent
+} from "../events/workflow-source-events.js";
+import { classifyErrorAsFailureCategory } from "../failure-categories.js";
+import {
+  decrementWaiterCount,
+  incrementWaiterCount,
+  readWaiterCount
+} from "./source-runtime-state.js";
+function getOrCreateDiagnosticsEntry(internals, name, revision) {
+  let byRevision = internals.sources.diagnostics.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    internals.sources.diagnostics.set(name, byRevision);
+  }
+  let entry = byRevision.get(revision);
+  if (entry === void 0) {
+    entry = {
+      state: "idle",
+      kind: "module",
+      requestedRevision: revision,
+      loadStartedAt: void 0,
+      loadDurationMs: void 0,
+      lastFailureCategory: void 0
+    };
+    byRevision.set(revision, entry);
+  }
+  return entry;
+}
+export function readSourceLoadDiagnostics(internals, name, revision) {
+  return internals.sources.diagnostics.get(name)?.get(revision);
+}
+export function recordSourceLoadStarted(internals, name, revision, kind, now) {
+  const entry = getOrCreateDiagnosticsEntry(internals, name, revision);
+  entry.state = "loading";
+  entry.kind = kind;
+  entry.loadStartedAt = now;
+  entry.loadDurationMs = void 0;
+  entry.lastFailureCategory = void 0;
+}
+export function recordSourceLoadReady(internals, name, revision, now) {
+  const entry = readSourceLoadDiagnostics(internals, name, revision);
+  if (entry === void 0 || entry.state !== "loading")
+    return !1;
+  entry.state = "ready";
+  entry.loadDurationMs = entry.loadStartedAt === void 0 ? void 0 : now - entry.loadStartedAt;
+  return !0;
+}
+export function recordSourceLoadFailed(internals, name, revision, now, error) {
+  const entry = readSourceLoadDiagnostics(internals, name, revision);
+  if (entry === void 0 || entry.state !== "loading")
+    return !1;
+  entry.state = "failed";
+  entry.loadDurationMs = entry.loadStartedAt === void 0 ? void 0 : now - entry.loadStartedAt;
+  entry.lastFailureCategory = classifyErrorAsFailureCategory(error, {
+    defaultErrorCategory: "application"
+  });
+  return !0;
+}
+export function beginSourceWaiter(internals, name, revision) {
+  incrementWaiterCount(internals.sources.waitersByKey, name, revision);
+}
+export function endSourceWaiterAndCheckCancellation(internals, name, revision) {
+  if (decrementWaiterCount(internals.sources.waitersByKey, name, revision) > 0)
+    return !1;
+  const entry = readSourceLoadDiagnostics(internals, name, revision);
+  if (entry === void 0 || entry.state !== "loading")
+    return !1;
+  entry.state = "cancelled";
+  return !0;
+}
+export function reviveOrphanedSourceLoadDiagnostics(internals, name, revision) {
+  const entry = readSourceLoadDiagnostics(internals, name, revision);
+  if (entry === void 0 || entry.state !== "cancelled")
+    return;
+  entry.state = "loading";
+}
+export function readSourceWaiterCount(internals, name, revision) {
+  return readWaiterCount(internals.sources.waitersByKey, name, revision);
+}
+export function recordSourceLoadStartedAndDispatch(ctx, now) {
+  recordSourceLoadStarted(ctx.internals, ctx.name, ctx.revision, ctx.kind, now);
+  ctx.engine.dispatchEvent(new WorkflowSourceLoadStartedEvent(ctx.name, ctx.revision, ctx.kind));
+}
+export function recordSourceLoadReadyAndDispatch(ctx, now) {
+  if (!recordSourceLoadReady(ctx.internals, ctx.name, ctx.revision, now))
+    return;
+  const loadDurationMs = readSourceLoadDiagnostics(ctx.internals, ctx.name, ctx.revision).loadDurationMs;
+  ctx.engine.dispatchEvent(new WorkflowSourceLoadReadyEvent(ctx.name, ctx.revision, ctx.kind, loadDurationMs));
+}
+export function recordSourceLoadFailedAndDispatch(ctx, now, error) {
+  if (!recordSourceLoadFailed(ctx.internals, ctx.name, ctx.revision, now, error))
+    return;
+  const diagnostics = readSourceLoadDiagnostics(ctx.internals, ctx.name, ctx.revision);
+  ctx.engine.dispatchEvent(new WorkflowSourceLoadFailedEvent(ctx.name, ctx.revision, ctx.kind, diagnostics.loadDurationMs ?? 0, diagnostics.lastFailureCategory));
+}
+export function endSourceWaiterAndDispatchCancellation(engine, internals, name, revision) {
+  if (!endSourceWaiterAndCheckCancellation(internals, name, revision))
+    return;
+  const kind = readSourceLoadDiagnostics(internals, name, revision)?.kind ?? "module";
+  engine.dispatchEvent(new WorkflowSourceLoadCancelledEvent(name, revision, kind));
+}

package/dist/core/engine/source-registration.js

@@ -14,16 +14,18 @@ function assertWellFormedSourceDescriptor(source) {
     throw TypeError(`registerSource(): source.descriptor.revision is ${revisionBytes} bytes, exceeding the maximum identifier size of ${MAX_CONTRACT_IDENTIFIER_BYTES}`);
 }
 export function registerSource(internals, source) {
+  if (internals.inlineStrategy === null)
+    throw Error('registerSource() is only supported in inline execution mode; a dynamically-loaded definition cannot be shipped to a Worker realm. Use workflowExecutionMode: "inline", or register this workflow eagerly with engine.register() instead.');
   assertWellFormedSourceDescriptor(source);
   const { name, revision } = source.descriptor;
   validateWorkflowOrActivityName(name, "workflow");
   Object.freeze(source.descriptor);
   if (internals.registrations.has(name))
     throw Error(`Cannot registerSource("${name}"): "${name}" is already registered as an eager workflow via engine.register(). A workflow name may not be both eagerly registered and a dynamic source.`);
-  let byRevision = internals.workflowSourcesByName.get(name);
+  let byRevision = internals.sources.byName.get(name);
   if (byRevision === void 0) {
     byRevision = new Map;
-    internals.workflowSourcesByName.set(name, byRevision);
+    internals.sources.byName.set(name, byRevision);
   }
   const existing = byRevision.get(revision);
   if (existing === void 0) {

package/dist/core/engine/source-resolution.d.ts

@@ -5,13 +5,12 @@
  *
  * Single-flight per `(name, revision)`: the underlying load+validate+install
  * work is shared by every concurrent caller for the same key via
- * `internals.sourceResolutionsInFlight`, but each caller races that shared
+ * `internals.sources.resolutionsInFlight`, but each caller races that shared
  * work against its OWN per-call cancellation interest — a cancelled waiter
- * never aborts a load another waiter still needs, and the shared load
- * itself is never tied to any individual caller's lifetime. Disposal aborts
- * every outstanding waiter (rejecting each pending `resolveWorkflowSource()`
- * call) without touching the shared load, which keeps running to whatever
- * point it naturally settles.
+ * never aborts a load another waiter still needs, and the shared load itself
+ * is never tied to any individual caller's lifetime. Disposal aborts every
+ * outstanding waiter (rejecting each pending `resolveWorkflowSource()` call)
+ * without touching the shared load, which keeps running to its own settle.
  *
  * @module core/engine/source-resolution
  */
@@ -41,12 +40,15 @@ export type ResolveWorkflowSourceOptions = {
  * {@link WorkflowRevisionRecord} immediately, without invoking the loader
  * at all, when `(name, revision)` is already durably installed — including
  * a revision installed by a different process. When that is the case,
- * `internals.resolvedWorkflowSources` is NOT populated for this key (there
+ * `internals.sources.resolved` is NOT populated for this key (there
  * is no locally-loaded `WorkflowDefinition` to stash — only the durable
  * manifest was ever read) even though the catalog itself considers the
- * revision installed; a later batch reading `resolvedWorkflowSources` must
+ * revision installed; a caller reading `internals.sources.resolved` must
  * account for that gap rather than assuming every installed revision has a
- * live definition available in this process. This fast path still requires
+ * live definition available in this process — see
+ * {@link resolveWorkflowSourceForExecution} for the internal-only variant
+ * that closes exactly this gap for callers that need a local definition.
+ * This fast path still requires
  * `registerSource()` to have been called for this exact key first (see
  * {@link resolveCachedOrHandle}), and still validates a pinned
  * `workflowVersion`/`contractHash` against the cached manifest — the ONLY
@@ -83,3 +85,17 @@ export type ResolveWorkflowSourceOptions = {
  * ```
  */
 export declare function resolveWorkflowSource(engine: Engine, name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;
+/**
+ * Internal-only variant of {@link resolveWorkflowSource} used exclusively by
+ * `resolveExecutableRegistration()` (`dynamic-source-execution.ts`, WFT-15).
+ * Identical cancellation, disposal, and single-flight contract, with one
+ * difference: a cache hit whose local resolved-definition cache
+ * (`internals.sources.resolved`) is still empty for this exact key falls
+ * through to a real load instead of returning the cached manifest —
+ * closing the cross-process-restart gap {@link resolveWorkflowSource}'s own
+ * doc calls out. `catalog.install()` is idempotent on byte-identical
+ * content, so re-installing an already-installed manifest never throws.
+ * Not exported from the package root — reached only via
+ * `resolveExecutableRegistration`.
+ */
+export declare function resolveWorkflowSourceForExecution(engine: Engine, name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;

package/dist/core/engine/source-resolution.js

@@ -9,8 +9,17 @@ import {
   WorkflowSourceValidationError
 } from "../source/index.js";
 import { ensureWorkflowCatalogReady, isWorkflowCatalogReady } from "./catalog-readiness.js";
+import { WorkflowSourceNotRegisteredError } from "./dynamic-source-errors.js";
 import { EngineDisposedError } from "./errors.js";
 import { getInternals, getWorkflowCatalog } from "./internals.js";
+import {
+  beginSourceWaiter,
+  endSourceWaiterAndDispatchCancellation,
+  recordSourceLoadFailedAndDispatch,
+  recordSourceLoadReadyAndDispatch,
+  recordSourceLoadStartedAndDispatch,
+  reviveOrphanedSourceLoadDiagnostics
+} from "./source-diagnostics.js";
 function toAbortError(signal) {
   const reason = signal.reason;
   return reason instanceof Error ? reason : Error("resolveWorkflowSource() aborted");
@@ -31,10 +40,10 @@ async function runSharedSourceLoad(engine, internals, name, revision, handle) {
     throw new EngineDisposedError;
   const installed = await getWorkflowCatalog(engine).install(outcome.manifest, outcome.definition);
   if (!internals.disposed) {
-    let resolvedByRevision = internals.resolvedWorkflowSources.get(name);
+    let resolvedByRevision = internals.sources.resolved.get(name);
     if (resolvedByRevision === void 0) {
       resolvedByRevision = new Map;
-      internals.resolvedWorkflowSources.set(name, resolvedByRevision);
+      internals.sources.resolved.set(name, resolvedByRevision);
     }
     resolvedByRevision.set(revision, {
       definition: outcome.loadedDefinition,
@@ -44,21 +53,37 @@ async function runSharedSourceLoad(engine, internals, name, revision, handle) {
   return { manifest: installed.manifest, installedAt: installed.installedAt };
 }
 function getOrCreateSharedSourceLoad(engine, internals, name, revision, handle) {
-  let byRevision = internals.sourceResolutionsInFlight.get(name);
+  let byRevision = internals.sources.resolutionsInFlight.get(name);
   if (byRevision === void 0) {
     byRevision = new Map;
-    internals.sourceResolutionsInFlight.set(name, byRevision);
+    internals.sources.resolutionsInFlight.set(name, byRevision);
   }
   const existing = byRevision.get(revision);
-  if (existing !== void 0)
+  if (existing !== void 0) {
+    reviveOrphanedSourceLoadDiagnostics(internals, name, revision);
     return existing;
-  const shared = runSharedSourceLoad(engine, internals, name, revision, handle).finally(() => {
-    const currentByRevision = internals.sourceResolutionsInFlight.get(name);
+  }
+  const eventContext = {
+    engine,
+    internals,
+    name,
+    revision,
+    kind: handle.descriptor.kind
+  };
+  recordSourceLoadStartedAndDispatch(eventContext, internals.options.getNow());
+  const shared = runSharedSourceLoad(engine, internals, name, revision, handle).then((record) => {
+    recordSourceLoadReadyAndDispatch(eventContext, internals.options.getNow());
+    return record;
+  }, (error) => {
+    recordSourceLoadFailedAndDispatch(eventContext, internals.options.getNow(), error);
+    throw error;
+  }).finally(() => {
+    const currentByRevision = internals.sources.resolutionsInFlight.get(name);
     if (currentByRevision?.get(revision) !== shared)
       return;
     currentByRevision.delete(revision);
     if (currentByRevision.size === 0)
-      internals.sourceResolutionsInFlight.delete(name);
+      internals.sources.resolutionsInFlight.delete(name);
   });
   shared.catch(() => {});
   byRevision.set(revision, shared);
@@ -72,10 +97,10 @@ function createWaiterAbort(options) {
     options?.signal?.addEventListener("abort", forwardAbort, { once: !0 });
   return { controller, detach: () => options?.signal?.removeEventListener("abort", forwardAbort) };
 }
-async function resolveCachedOrHandle(engine, internals, name, revision) {
-  const handle = internals.workflowSourcesByName.get(name)?.get(revision);
+async function resolveCachedOrHandle(engine, internals, name, revision, requireLocalDefinition) {
+  const handle = internals.sources.byName.get(name)?.get(revision);
   if (handle === void 0)
-    throw Error(`resolveWorkflowSource("${name}", "${revision}") was called before registerSource() ` + "registered this exact (name, revision) \u2014 call engine.registerSource() first.");
+    throw new WorkflowSourceNotRegisteredError(name, revision);
   if (!isWorkflowCatalogReady(engine))
     await ensureWorkflowCatalogReady(engine);
   const existing = await getWorkflowCatalog(engine).resolveEntry(name, revision);
@@ -83,11 +108,19 @@ async function resolveCachedOrHandle(engine, internals, name, revision) {
     const expectedManifest = buildExpectedManifest(handle.descriptor, existing.manifest), verdict = checkWorkflowCompatibility(expectedManifest, existing.manifest, DEFAULT_WORKFLOW_COMPATIBILITY_POLICY);
     if (!verdict.compatible)
       throw new WorkflowSourceValidationError(name, revision, verdict.reasons);
+    if (requireLocalDefinition && internals.sources.resolved.get(name)?.get(revision) === void 0)
+      return { handle };
     return { cached: existing };
   }
   return { handle };
 }
 export async function resolveWorkflowSource(engine, name, revision, options) {
+  return resolveWorkflowSourceCore(engine, name, revision, options, !1);
+}
+export async function resolveWorkflowSourceForExecution(engine, name, revision, options) {
+  return resolveWorkflowSourceCore(engine, name, revision, options, !0);
+}
+async function resolveWorkflowSourceCore(engine, name, revision, options, requireLocalDefinition) {
   const internals = getInternals(engine), waiter = createWaiterAbort(options);
   if (waiter.controller.signal.aborted) {
     waiter.detach();
@@ -97,9 +130,10 @@ export async function resolveWorkflowSource(engine, name, revision, options) {
     waiter.detach();
     throw new EngineDisposedError;
   }
-  internals.sourceResolutionWaiterControllers.add(waiter.controller);
+  internals.sources.waiterControllers.add(waiter.controller);
+  beginSourceWaiter(internals, name, revision);
   try {
-    const cachedOrHandle = resolveCachedOrHandle(engine, internals, name, revision), cachedOrHandleAbort = abortRejection(waiter.controller.signal);
+    const cachedOrHandle = resolveCachedOrHandle(engine, internals, name, revision, requireLocalDefinition), cachedOrHandleAbort = abortRejection(waiter.controller.signal);
     cachedOrHandleAbort.catch(() => {});
     let outcome;
     try {
@@ -114,6 +148,7 @@ export async function resolveWorkflowSource(engine, name, revision, options) {
     return await Promise.race([shared, waiterAbort]);
   } finally {
     waiter.detach();
-    internals.sourceResolutionWaiterControllers.delete(waiter.controller);
+    internals.sources.waiterControllers.delete(waiter.controller);
+    endSourceWaiterAndDispatchCancellation(engine, internals, name, revision);
   }
 }

package/dist/core/engine/source-runtime-state.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `EngineInternals.sources` — the single consolidated container for every
+ * piece of process-local, in-memory state the dynamic workflow-source
+ * pipeline (WFT-13/14, WFT-15/16) needs: registered candidates, in-flight
+ * single-flight loads, per-caller waiter controllers, locally-resolved
+ * definitions, and bounded per-`(name, revision)` diagnostics.
+ *
+ * WFT-13/14 originally spread this across five flat `EngineInternals`
+ * fields (`workflowSourcesByName`, `sourceResolutionsInFlight`,
+ * `sourceResolutionWaiterControllers`, `resolvedWorkflowSources`, plus the
+ * `ResolvedSource` type alias). WFT-15/16 folds them into one field —
+ * `internals.sources: WorkflowSourceRuntimeState` — both because
+ * `internals.ts` and `lifecycle/start.ts` are already at the repository's
+ * 500-line implementation-file ceiling (no headroom for four more
+ * documented fields) and because the diagnostics state this batch adds
+ * (`diagnostics`, `waitersByKey`, `lastResolvedRevisionByName`) is the same
+ * kind of per-`(name, revision)` bookkeeping the original four fields
+ * already were — one container, one owner.
+ *
+ * Every consumer reaches this state via `internals.sources.<field>` rather
+ * than a flat `internals.<field>` — see `scripts/check-engine-internals-field-access.ts`,
+ * which is updated in the same commit to the single `sources` name.
+ *
+ * @module core/engine/source-runtime-state
+ */
+import type { ActivityRegistry } from '../activity-registry.ts';
+import type { WorkflowDefinition } from '../types.ts';
+import type { FailureCategory } from '../types/identity.ts';
+type SourceHandle = import('../source/index.ts').WorkflowSourceHandle;
+type CatalogRevisionRecord = import('../catalog/index.ts').WorkflowRevisionRecord;
+type WorkflowSourceKind = import('../source/index.ts').WorkflowSourceKind;
+/** A successful `resolveWorkflowSource()`'s live, in-process definition and activity registry. */
+export type ResolvedSource = {
+    definition: WorkflowDefinition;
+    activityRegistry: ActivityRegistry;
+};
+/**
+ * Load-state machine for one `(name, revision)`, backing both the
+ * `weft.catalog.diagnostics` `source` extension and the
+ * `workflow-source:load-*` events. `'idle'` is the type-level starting
+ * point before the first `resolveWorkflowSource()` call for a key, and IS
+ * observable externally: `weft.catalog.diagnostics` reports it for any
+ * `registerSource()`-registered revision that has never had a load start
+ * (see `buildSourceDiagnostics()` in `catalog-removal.ts`), and no
+ * `workflow-source:load-*` event is emitted for that state.
+ */
+export type SourceLoadState = 'idle' | 'loading' | 'ready' | 'failed' | 'cancelled';
+/** Bounded, per-`(name, revision)` diagnostics — no manifest or contract content, only identity and state. */
+export type SourceLoadDiagnostics = {
+    state: SourceLoadState;
+    kind: WorkflowSourceKind;
+    requestedRevision: string;
+    loadStartedAt: number | undefined;
+    loadDurationMs: number | undefined;
+    lastFailureCategory: FailureCategory | undefined;
+};
+/** The consolidated dynamic workflow-source runtime state — see the module doc. */
+export type WorkflowSourceRuntimeState = {
+    /** `registerSource()` candidates, keyed name then revision. Registering never invokes the loader. */
+    byName: Map<string, Map<string, SourceHandle>>;
+    /** In-flight `resolveWorkflowSource` single-flight load per `(name, revision)`. */
+    resolutionsInFlight: Map<string, Map<string, Promise<CatalogRevisionRecord>>>;
+    /** Per-caller `AbortController`s from in-flight `resolveWorkflowSource()` calls; disposal aborts every waiter without touching the shared load. */
+    waiterControllers: Set<AbortController>;
+    /**
+     * Outstanding-waiter count per `(name, revision)`, keyed name then
+     * revision — a flat composite-string key is not safe here, since unlike a
+     * workflow `name`, a source `revision` is only byte-length-bounded, not
+     * grammar-restricted, so it may contain whatever separator character a
+     * flat key would pick. Incremented/decremented inside
+     * `resolveWorkflowSource`'s own try/finally. Drives the `loading` ->
+     * `cancelled` diagnostics transition: that transition fires only when
+     * the LAST outstanding waiter for a key releases while the shared load
+     * is still unsettled.
+     */
+    waitersByKey: Map<string, Map<string, number>>;
+    /** A successful `resolveWorkflowSource()`'s live definition, keyed name then revision. */
+    resolved: Map<string, Map<string, ResolvedSource>>;
+    /** The revision `resolveExecutableRegistration()` most recently resolved for a name — used by the sync-only fallback readers (`finalizer.ts`, `constraints.ts`). */
+    lastResolvedRevisionByName: Map<string, string>;
+    /** Bounded per-`(name, revision)` load-state diagnostics, keyed name then revision. */
+    diagnostics: Map<string, Map<string, SourceLoadDiagnostics>>;
+};
+/** Build an empty {@link WorkflowSourceRuntimeState}. */
+export declare function createWorkflowSourceRuntimeState(): WorkflowSourceRuntimeState;
+/** Read the nested `name -> revision -> value` count at `(name, revision)` from {@link WorkflowSourceRuntimeState.waitersByKey}, defaulting to `0`. */
+export declare function readWaiterCount(waitersByKey: WorkflowSourceRuntimeState['waitersByKey'], name: string, revision: string): number;
+/** Increment the waiter count at `(name, revision)`, creating intermediate maps as needed. Returns the new count. */
+export declare function incrementWaiterCount(waitersByKey: WorkflowSourceRuntimeState['waitersByKey'], name: string, revision: string): number;
+/** Decrement the waiter count at `(name, revision)`, removing empty intermediate maps. Returns the new count (never negative). */
+export declare function decrementWaiterCount(waitersByKey: WorkflowSourceRuntimeState['waitersByKey'], name: string, revision: string): number;
+export {};

package/dist/core/engine/source-runtime-state.js

@@ -0,0 +1,36 @@
+export function createWorkflowSourceRuntimeState() {
+  return {
+    byName: new Map,
+    resolutionsInFlight: new Map,
+    waiterControllers: new Set,
+    waitersByKey: new Map,
+    resolved: new Map,
+    lastResolvedRevisionByName: new Map,
+    diagnostics: new Map
+  };
+}
+export function readWaiterCount(waitersByKey, name, revision) {
+  return waitersByKey.get(name)?.get(revision) ?? 0;
+}
+export function incrementWaiterCount(waitersByKey, name, revision) {
+  let byRevision = waitersByKey.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    waitersByKey.set(name, byRevision);
+  }
+  const next = (byRevision.get(revision) ?? 0) + 1;
+  byRevision.set(revision, next);
+  return next;
+}
+export function decrementWaiterCount(waitersByKey, name, revision) {
+  const byRevision = waitersByKey.get(name), current = byRevision?.get(revision) ?? 0, next = Math.max(0, current - 1);
+  if (byRevision === void 0)
+    return next;
+  if (next === 0) {
+    byRevision.delete(revision);
+    if (byRevision.size === 0)
+      waitersByKey.delete(name);
+  } else
+    byRevision.set(revision, next);
+  return next;
+}

package/dist/core/engine/storage-io.d.ts

@@ -1,4 +1,4 @@
-import { type BatchOperation } from '../../storage/interface.ts';
+import { type BatchOperation, type ConditionalBatchCondition } from '../../storage/interface.ts';
 import type { ScheduleState, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 import { type WorkflowClaimTransitionFragment } from './workflow-claim-transitions.ts';
@@ -84,11 +84,28 @@ export declare function commitExternalTerminalWorkflowStateOperations(internals:
 export declare function loadScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState | null>;
 /** Load a schedule state. */
 export declare function requireScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState>;
-/** Persist schedule state and optionally write the next schedule timer. */
+/**
+ * Persist schedule state and optionally write the next schedule timer.
+ *
+ * `extraConditions` (WFT-20) additionally fences the commit on caller-supplied
+ * preconditions — used by a `revisionPolicy: 'pinned'` create/update to fence
+ * the write on `buildCatalogEntryRevisionCondition(type, pinnedRevision)` so a
+ * concurrent `removeWorkflowRevision()` landing between pin capture and this
+ * commit cannot let a pin to an already-removed revision durably land. When
+ * the commit's `extraConditions` are the ones that lost the CAS,
+ * `onExtraConditionsLost` (required whenever `extraConditions` is non-empty)
+ * supplies the thrown error instead of this function's own generic
+ * lost-precondition error, so the caller sees an actionable, typed failure
+ * (e.g. `WorkflowRevisionUnavailableError`) rather than a bare "lost its
+ * precondition" message. Every existing caller passes neither option and gets
+ * byte-for-byte the pre-WFT-20 commit shape.
+ */
 export declare function writeScheduleState(internals: EngineInternals, state: ScheduleState, options?: {
     includeTimer?: boolean;
     replaceTimerFrom?: ScheduleState;
     additionalOperations?: BatchOperation[];
+    extraConditions?: ConditionalBatchCondition[];
+    onExtraConditionsLost?: () => Error;
 }): Promise<void>;
 /** Load persisted workflow start headers by workflow ID. */
 export declare function loadWorkflowStartHeaders(internals: EngineInternals, workflowId: string): Promise<Map<string, string> | undefined>;