@lostgradient/weft 0.23.1 → 0.24.1

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.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `registerSource()` — the synchronous entry point for a dynamic workflow
+ * source (WFT-13/14). Mirrors `engine.register()`'s own "stays synchronous,
+ * defers the real work" contract: this records a catalog candidate keyed
+ * `(name, revision)` and returns — it never invokes the source's loader and
+ * never touches storage. The loader runs only inside a later, explicit
+ * `resolveWorkflowSource()` call (`source-resolution.ts`).
+ *
+ * @module core/engine/source-registration
+ */
+import type { WorkflowSourceHandle } from '../source/index.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * Record `source` as a lazily-resolvable candidate for
+ * `(source.descriptor.name, source.descriptor.revision)`. Synchronous and
+ * side-effect-free beyond the in-memory record: never invokes
+ * `source.load`, never reads or writes storage.
+ *
+ * Collision rules, checked in both directions against `engine.register()`'s
+ * own state so a workflow name can never be simultaneously eager and lazy:
+ *
+ * - A name already eagerly registered (`internals.registrations` — set by
+ *   BOTH branches of `engine.register()`, unlike `workflowDefinitionsByName`,
+ *   which only the builder-produced branch populates; checking that narrower
+ *   map here would let a plain `{ name, handler }` `WorkflowDefinition`
+ *   registered via `engine.register()` collide silently with a same-named
+ *   `registerSource()` call) cannot also be registered as a source — throws.
+ * - Re-registering the identical `source` object reference for the same
+ *   `(name, revision)` is idempotent (a no-op), mirroring `engine.register()`'s
+ *   own same-reference-is-idempotent rule for eager definitions.
+ * - Registering a *different* handle under the same `(name, revision)` key
+ *   throws — a revision identity, once claimed, names exactly one source.
+ * - Multiple *different* revisions of the same lazy name may coexist
+ *   unregistered — this is the direct lazy analog of the catalog already
+ *   supporting multiple installed revisions per name (WFT-9/10); nothing in
+ *   this batch's acceptance criteria forbids it.
+ *
+ * The symmetric check — an eager `engine.register()` call for a name
+ * already claimed by a source — lives in `registration.ts`'s
+ * `commitWorkflowDefinition`.
+ */
+export declare function registerSource(internals: EngineInternals, source: WorkflowSourceHandle): void;

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

@@ -0,0 +1,38 @@
+import { utf8ByteLength } from "../../worker/manifest/utf8.js";
+import { MAX_CONTRACT_IDENTIFIER_BYTES } from "../contract/limits.js";
+import { validateWorkflowOrActivityName } from "../types/name-grammar.js";
+function assertWellFormedSourceDescriptor(source) {
+  const { kind, name, revision } = source.descriptor;
+  if (typeof kind !== "string" || kind.length === 0)
+    throw TypeError("registerSource(): source.descriptor.kind must be a non-empty string");
+  if (typeof name !== "string" || name.length === 0)
+    throw TypeError("registerSource(): source.descriptor.name must be a non-empty string");
+  if (typeof revision !== "string" || revision.length === 0)
+    throw TypeError("registerSource(): source.descriptor.revision must be a non-empty string");
+  const revisionBytes = utf8ByteLength(revision);
+  if (revisionBytes > MAX_CONTRACT_IDENTIFIER_BYTES)
+    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.sources.byName.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    internals.sources.byName.set(name, byRevision);
+  }
+  const existing = byRevision.get(revision);
+  if (existing === void 0) {
+    byRevision.set(revision, source);
+    return;
+  }
+  if (existing === source)
+    return;
+  throw Error(`Cannot registerSource("${name}", "${revision}"): a different source handle is already registered for this exact (name, revision) key.`);
+}

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

@@ -0,0 +1,101 @@
+/**
+ * `resolveWorkflowSource()` — the async, single-flight entry point that
+ * loads, validates, and installs one dynamic workflow source revision
+ * (WFT-13/14).
+ *
+ * Single-flight per `(name, revision)`: the underlying load+validate+install
+ * work is shared by every concurrent caller for the same key via
+ * `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 its own settle.
+ *
+ * @module core/engine/source-resolution
+ */
+import type { WorkflowRevisionRecord } from '../catalog/index.ts';
+import type { Engine } from './index.ts';
+/**
+ * Options accepted by {@link resolveWorkflowSource}.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { ResolveWorkflowSourceOptions } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * const options: ResolveWorkflowSourceOptions = { signal: AbortSignal.timeout(5_000) };
+ * const record = await engine.resolveWorkflowSource('checkout', 'r1', options);
+ * console.log(record.manifest.revision);
+ * ```
+ */
+export type ResolveWorkflowSourceOptions = {
+    /** When aborted, this caller's own `resolveWorkflowSource()` call rejects; a load already in flight for other callers is unaffected. */
+    signal?: AbortSignal;
+};
+/**
+ * Load, validate, and install one dynamic workflow source revision
+ * previously recorded via `engine.registerSource()`. Returns the installed
+ * {@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.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 caller reading `internals.sources.resolved` must
+ * account for that gap rather than assuming every installed revision has a
+ * 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
+ * thing it skips is re-invoking the loader and re-running
+ * {@link import('../source/index.ts').validateResolvedWorkflowSource}.
+ *
+ * Single-flight per `(name, revision)` — see the module doc for the full
+ * cancellation contract. Throws a plain `Error` when `registerSource()` was
+ * never called for this exact key (a programmer error, not untrusted-input
+ * rejection); throws {@link WorkflowSourceValidationError} when the loaded
+ * module fails validation, OR when a cached manifest contradicts a pinned
+ * `workflowVersion`/`contractHash`; throws {@link EngineDisposedError} when
+ * the engine is disposed, either already or during the call; propagates
+ * {@link import('../catalog/index.ts').WorkflowCatalogConflictError}
+ * unwrapped on a genuine content conflict with an already-installed
+ * revision.
+ *
+ * @example
+ * ```ts
+ * import { Engine, workflowSource } from '@lostgradient/weft';
+ *
+ * declare const engine: Engine;
+ * declare const loadCheckout: () => Promise<{
+ *   checkout: import('@lostgradient/weft').WorkflowDefinition<unknown, unknown, 'checkout'>;
+ * }>;
+ * engine.registerSource(
+ *   workflowSource(
+ *     { name: 'checkout', location: './checkout.ts', exportName: 'checkout', revision: 'r1' },
+ *     loadCheckout,
+ *   ),
+ * );
+ * const record = await engine.resolveWorkflowSource('checkout', 'r1');
+ * console.log(record.manifest.revision);
+ * ```
+ */
+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

@@ -0,0 +1,154 @@
+import {
+  checkWorkflowCompatibility,
+  DEFAULT_WORKFLOW_COMPATIBILITY_POLICY
+} from "../contract/compatibility.js";
+import {
+  buildExpectedManifest,
+  resolveSourceModule,
+  validateResolvedWorkflowSource,
+  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");
+}
+function abortRejection(signal) {
+  return new Promise((_resolve, reject) => {
+    signal.addEventListener("abort", () => reject(toAbortError(signal)), { once: !0 });
+  });
+}
+async function runSharedSourceLoad(engine, internals, name, revision, handle) {
+  const resolved = await resolveSourceModule(handle.descriptor, handle);
+  if (!resolved.ok)
+    throw new WorkflowSourceValidationError(name, revision, [resolved.reason]);
+  const outcome = await validateResolvedWorkflowSource(handle.descriptor, resolved.moduleValue);
+  if (!outcome.ok)
+    throw new WorkflowSourceValidationError(name, revision, outcome.reasons);
+  if (internals.disposed)
+    throw new EngineDisposedError;
+  const installed = await getWorkflowCatalog(engine).install(outcome.manifest, outcome.definition);
+  if (!internals.disposed) {
+    let resolvedByRevision = internals.sources.resolved.get(name);
+    if (resolvedByRevision === void 0) {
+      resolvedByRevision = new Map;
+      internals.sources.resolved.set(name, resolvedByRevision);
+    }
+    resolvedByRevision.set(revision, {
+      definition: outcome.loadedDefinition,
+      activityRegistry: outcome.activityRegistry
+    });
+  }
+  return { manifest: installed.manifest, installedAt: installed.installedAt };
+}
+function getOrCreateSharedSourceLoad(engine, internals, name, revision, handle) {
+  let byRevision = internals.sources.resolutionsInFlight.get(name);
+  if (byRevision === void 0) {
+    byRevision = new Map;
+    internals.sources.resolutionsInFlight.set(name, byRevision);
+  }
+  const existing = byRevision.get(revision);
+  if (existing !== void 0) {
+    reviveOrphanedSourceLoadDiagnostics(internals, name, revision);
+    return existing;
+  }
+  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.sources.resolutionsInFlight.delete(name);
+  });
+  shared.catch(() => {});
+  byRevision.set(revision, shared);
+  return shared;
+}
+function createWaiterAbort(options) {
+  const controller = new AbortController, forwardAbort = () => controller.abort(options?.signal?.reason);
+  if (options?.signal?.aborted)
+    forwardAbort();
+  else
+    options?.signal?.addEventListener("abort", forwardAbort, { once: !0 });
+  return { controller, detach: () => options?.signal?.removeEventListener("abort", forwardAbort) };
+}
+async function resolveCachedOrHandle(engine, internals, name, revision, requireLocalDefinition) {
+  const handle = internals.sources.byName.get(name)?.get(revision);
+  if (handle === void 0)
+    throw new WorkflowSourceNotRegisteredError(name, revision);
+  if (!isWorkflowCatalogReady(engine))
+    await ensureWorkflowCatalogReady(engine);
+  const existing = await getWorkflowCatalog(engine).resolveEntry(name, revision);
+  if (existing !== void 0) {
+    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();
+    throw toAbortError(waiter.controller.signal);
+  }
+  if (internals.disposed) {
+    waiter.detach();
+    throw new EngineDisposedError;
+  }
+  internals.sources.waiterControllers.add(waiter.controller);
+  beginSourceWaiter(internals, name, revision);
+  try {
+    const cachedOrHandle = resolveCachedOrHandle(engine, internals, name, revision, requireLocalDefinition), cachedOrHandleAbort = abortRejection(waiter.controller.signal);
+    cachedOrHandleAbort.catch(() => {});
+    let outcome;
+    try {
+      outcome = await Promise.race([cachedOrHandle, cachedOrHandleAbort]);
+    } finally {
+      cachedOrHandle.catch(() => {});
+    }
+    if (outcome.cached !== void 0)
+      return outcome.cached;
+    const shared = getOrCreateSharedSourceLoad(engine, internals, name, revision, outcome.handle), waiterAbort = abortRejection(waiter.controller.signal);
+    waiterAbort.catch(() => {});
+    return await Promise.race([shared, waiterAbort]);
+  } finally {
+    waiter.detach();
+    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;
+}