@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -1,11 +1,13 @@
 import type { AlertStateSnapshot } from '../../alerting/types.ts';
 import { type Storage as WeftStorage } from '../../storage/interface.ts';
 import { type ActivityMetadata, type ActivityRegistrationOptions, type RegisteredActivityFunction } from '../activity-registry.ts';
+import type { WorkflowRevisionRecord } from '../catalog/index.ts';
 import type { StoredStreamChunk } from '../context.ts';
 import type { TypedEventTarget, WeftEventMap } from '../events.ts';
 import type { Interceptor } from '../interceptor.ts';
 import { type ReviewRequest } from '../review/index.ts';
 import { Scheduler } from '../scheduler.ts';
+import type { WorkflowSourceHandle } from '../source/index.ts';
 import { type AnyActivityDefinition, type AnyWorkflowDefinition, type AttributeFilterKey, type BulkCancelResult, type BulkDeleteResult, type BulkOperationCommitOptions, type BulkOperationDryRunOptions, type BulkOperationDryRunResult, type BulkRetryFailedResult, type BulkSignalAllCommitOptions, type BulkSignalAllDryRunOptions, type BulkSignalResult, type BulkTagResult, type CheckpointState, type CheckpointSummary, type CoordinatedUpdateResult, type DefaultActivityTypes, type DefaultWorkflowRegistry, type ForkOptions, type InferActivityEntries, type InferActivityEntry, type InferWorkflowEntries, type InferWorkflowEntry, type ListFilter, type ListOptions, type PaginatedResult, type PendingAsyncActivityListOptions, type PendingAsyncActivityPage, type PurgeResult, type QueryDefinition, type RegisteredWorkflowDefinition, type RetentionOverview, type ReviewListEntry, type ReviewListFilter, type ScheduleDefinition, type ScheduleFilter, type ScheduleOptions, type ScheduleSpec, type ScheduleSummary, type ScheduleUpdateOptions, type SearchAttributeValue, type SignalDefinition, type SignalDeliveryOptions, type StartOrSignalOptions, type StartOrSignalSignal, type StartWorkflowOptions, type SubmitReviewOptions, type TypedListFilter, type UpdateDefinition, type WorkflowEvent, type WorkflowFinalizerStatus, type WorkflowInput, type WorkflowOutput, type WorkflowReplay, type WorkflowScheduleProvenance, type WorkflowServices, type WorkflowServicesUnion, type WorkflowState, type WorkflowSummary, type WorkflowTimelineEntry } from '../types.ts';
 import type { TimerEntry } from '../types/checkpoint.ts';
 import type { WorkflowAlreadyRegistered } from '../types/workflow-builder.ts';
@@ -14,29 +16,36 @@ import { type EmptyActivityDefinitions, type EmptyWorkflowDefinitions, type Know
 import { type ActivityDefinitionName, type EngineCreateOptions, type EngineCreateWorkflowRegistry, type RegisteredActivityDefinitionExecute, type UnknownWorkflowNameWhenDefaultRegistryIsEmpty } from './engine-create-types.ts';
 import type { EngineConstructorOptions } from './engine-internal-types.ts';
 import type { EngineStateNamespace } from './engine-state-namespace.ts';
+import { type EngineWorkflowsNamespace } from './engine-workflows-namespace.ts';
 import { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
 import { ENGINE_LEASE_LOST_WARNING_NAME } from './lease-deposition.ts';
 import type { EngineLeaseHealth } from './lease-health.ts';
 import { type RecoverAllOptions, type StartOrSignalResult } from './lifecycle.ts';
 import { assertCompatiblePersistedDataVersion } from './persisted-data-version.ts';
 import { ScheduleHandle } from './schedule-handle.ts';
+import { type ResolveWorkflowSourceOptions } from './source-resolution.ts';
 import { type WorkflowFeedListener, type WorkflowFeedRecord, type WorkflowFeedSelector } from './workflow-feed.ts';
+export type { WorkflowRevisionReferenceCounts } from '../catalog/index.ts';
 export { ActivityReconciliationCapabilityError, ActivityReconciliationConflictError, ActivityReconciliationIndeterminateError, } from './activity-reconciliation.ts';
 export { AsyncActivityTokenNotFoundError } from './async-activity-completion.ts';
 export type { PendingAsyncActivity } from './async-activity-records.ts';
+export { getWorkflowRevisionDiagnostics, removeWorkflowRevision, type WorkflowCatalogRemovalResult, type WorkflowRevisionDiagnostics, } from './catalog-removal.ts';
 export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
 export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposalError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataCorruptError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
+export { getWorkflowCatalog } from './internals.ts';
 export { WeftWorkflowClaimLostWarning, WeftWorkflowWakeDiscardedWarning, WORKFLOW_CLAIM_LOST_WARNING_NAME, WORKFLOW_WAKE_DISCARDED_WARNING_NAME, } from './lease-deposition.ts';
 export type { WorkflowWakeKind } from './lease-deposition.ts';
 export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, OwnershipModeMismatchError, WorkflowClaimUnavailableError, } from './lease-errors.ts';
 export type { EngineLeaseHealth, LeaseLostReason } from './lease-health.ts';
 export type { RecoverAllOptions, RecoveredWorkflowInfo } from './lifecycle.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
+export type { ResolveWorkflowSourceOptions } from './source-resolution.ts';
 export type { WorkflowFeedListener, WorkflowFeedRecord, WorkflowFeedSelector, } from './workflow-feed.ts';
 export type { EngineCreateOptions } from './engine-create-types.ts';
 export { clearEngineLeakWarningTokenForTesting, getEngineLeakCollectionCountForTesting, hasEngineLeakWarningTokenForTesting, setEngineLeakWarningOverrideForTesting, setNextEngineLeakWarningTokenForTesting, shouldEmitEngineLeakWarningForTesting, } from './engine-leak-warnings.ts';
 export type { EngineStateNamespace } from './engine-state-namespace.ts';
+export type { ActivateWorkflowRevisionOptions, EngineWorkflowsNamespace, } from './engine-workflows-namespace.ts';
 export { assertCompatiblePersistedDataVersion };
 export declare const ENGINE_PARKED_WORKFLOW_COUNT_FOR_TESTING: unique symbol;
 export declare const ENGINE_SIGNAL_WAITER_COUNT_FOR_TESTING: unique symbol;
@@ -172,6 +181,7 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     removeEventListener<K extends Extract<keyof WeftEventMap, string>>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
     removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
     get state(): EngineStateNamespace;
+    get workflows(): EngineWorkflowsNamespace;
     /** Return detached snapshots of the alert rules that are currently firing. */
     getActiveAlerts(): readonly AlertStateSnapshot[];
     /**
@@ -212,6 +222,50 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
         readonly execute: RegisteredActivityDefinitionExecute<TActivities, TName>;
     }): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
     register<TDefinition extends AnyActivityDefinition>(definition: ActivityDefinitionName<TDefinition> extends Extract<keyof TActivities, string> ? never : TDefinition): Engine<TWorkflows, TActivities & InferActivityEntry<TDefinition>>;
+    /**
+     * Record `source` as a lazily-resolvable dynamic workflow source
+     * (WFT-13/14): synchronous, and it never invokes `source.load` — it only
+     * records a catalog candidate keyed `(source.descriptor.name,
+     * source.descriptor.revision)`. Call `resolveWorkflowSource()` to
+     * actually load, validate, and install it. A workflow name may not be
+     * both eagerly registered (`engine.register()`) and a dynamic source;
+     * registering the identical `source` reference twice for the same
+     * `(name, revision)` is idempotent.
+     *
+     * @example
+     * ```ts
+     * import { Engine, workflowSource } from '@lostgradient/weft';
+     *
+     * declare const loadCheckout: () => Promise<{
+     *   checkout: import('@lostgradient/weft').WorkflowDefinition<unknown, unknown, 'checkout'>;
+     * }>;
+     * const engine = new Engine();
+     * engine.registerSource(
+     *   workflowSource(
+     *     { name: 'checkout', location: './checkout.ts', exportName: 'checkout', revision: 'r1' },
+     *     loadCheckout,
+     *   ),
+     * );
+     * ```
+     */
+    registerSource(source: WorkflowSourceHandle): void;
+    /**
+     * Load, validate, and install one dynamic workflow source revision
+     * previously recorded via {@link Engine.registerSource}. Single-flight
+     * per `(name, revision)`: concurrent callers for the same key share one
+     * loader invocation. Does not wire `engine.start()` or recovery to await
+     * resolution — that is a later batch's job (WFT-15).
+     *
+     * @example
+     * ```ts
+     * import { Engine } from '@lostgradient/weft';
+     *
+     * declare const engine: Engine;
+     * const record = await engine.resolveWorkflowSource('checkout', 'r1');
+     * console.log(record.manifest.revision);
+     * ```
+     */
+    resolveWorkflowSource(name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;
     /**
      * Register every workflow from an object map at once and return a typed
      * engine view that exposes the newly added workflow names.
@@ -244,6 +298,35 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     listWorkflowDefinitions(): RegisteredWorkflowDefinition[];
     getActivityDefinition(name: string): ActivityMetadata | undefined;
     listActivityDefinitions(): ActivityMetadata[];
+    /**
+     * Resolve one activity's catalog metadata the same way dispatch resolves
+     * it for a running workflow of this type: the workflow's per-workflow
+     * `.activities({...})` registry first, falling back to the global registry
+     * — see `activity-resolution.ts`'s `resolveActivityViaRegistries`. Build
+     * tooling (`buildWorkerManifestFromRegistry`) uses this so a workflow-scoped
+     * activity's schema, not a same-named global activity's, feeds its
+     * `contractHash` when both are registered.
+     */
+    getWorkflowActivityDefinition(workflowType: string, activityName: string): ActivityMetadata | undefined;
+    /**
+     * List every activity definition registered on this workflow's own
+     * per-workflow `.activities({...})` registry — name, schema, description,
+     * tags, retry/timeout metadata, never a handler function. Returns an
+     * empty array for a workflow with no `.activities({...})` step (including
+     * an unknown `workflowType`), never `undefined`, so a caller can fold the
+     * result straight into a contract without an existence check first.
+     *
+     * Companion to {@link getWorkflowActivityDefinition}: that resolves one
+     * activity by name with the per-workflow-first, global-fallback dispatch
+     * order; this enumerates only the names the per-workflow registry itself
+     * declares — activities a workflow reaches solely through the global
+     * registry are deliberately excluded, since those are not part of what
+     * `.activities({...})` scoped to this workflow. Build tooling that needs a
+     * workflow's full scoped-activity contract set (`buildRegistrySnapshot`,
+     * `worker/manifest/registry-contract-builder.ts`) uses this instead of
+     * reaching into engine internals directly.
+     */
+    listWorkflowActivityDefinitions(workflowType: string): ActivityMetadata[];
     start<TName extends KnownWorkflowNames<TWorkflows>>(type: TName, input: WorkflowInput<TWorkflows, TName>, options?: StartWorkflowOptions<WorkflowServices<TWorkflows, TName>>): Promise<WorkflowHandle<WorkflowOutput<TWorkflows, TName>>>;
     start<TName extends string>(type: UnknownWorkflowNameWhenDefaultRegistryIsEmpty<TWorkflows, TName>, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
     /**

package/dist/core/engine/index.js

@@ -47,6 +47,7 @@ import {
   createUpdateCallbacks as createUpdateCallbacksForEngine
 } from "./callback-creators.js";
 import { registerCancelHandler } from "./cancel-handlers.js";
+import { ensureWorkflowCatalogReady, isWorkflowCatalogReady } from "./catalog-readiness.js";
 import {
   getCheckpointAt as getCheckpointStateAt,
   getEvents as getWorkflowEvents,
@@ -78,6 +79,9 @@ import {
   shouldStartEngineScheduler,
   validateEngineCreateBackgroundTaskOptions
 } from "./engine-runtime-helpers.js";
+import {
+  createEngineWorkflowsNamespace
+} from "./engine-workflows-namespace.js";
 import {
   EngineCreateNameMismatchError,
   EngineDisposalError,
@@ -167,6 +171,10 @@ import {
   releaseSignalWaiter,
   signal as signalWorkflow
 } from "./signals.js";
+import { registerSource as registerWorkflowSource } from "./source-registration.js";
+import {
+  resolveWorkflowSource as resolveWorkflowSourceImpl
+} from "./source-resolution.js";
 import {
   loadScheduleState,
   loadWorkflowState,
@@ -204,6 +212,10 @@ export {
   ActivityReconciliationIndeterminateError
 } from "./activity-reconciliation.js";
 export { AsyncActivityTokenNotFoundError } from "./async-activity-completion.js";
+export {
+  getWorkflowRevisionDiagnostics,
+  removeWorkflowRevision
+} from "./catalog-removal.js";
 export {
   ActivityResolutionError,
   BulkDeleteRequiresTerminalWorkflowsError,
@@ -224,6 +236,7 @@ export {
   WorkflowTypeNotRegisteredForRecoveryError
 } from "./errors.js";
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from "./handles.js";
+export { getWorkflowCatalog } from "./internals.js";
 export {
   WeftWorkflowClaimLostWarning,
   WeftWorkflowWakeDiscardedWarning,
@@ -282,6 +295,8 @@ export class Engine extends EventTarget {
       }
       await engine.#bootstrapOwnershipIfConfigured();
       await engine.#acquireLeaseIfConfigured();
+      if (!isWorkflowCatalogReady(engine))
+        await ensureWorkflowCatalogReady(engine);
       if (options.recover !== !1)
         await engine.recoverAll(options.acknowledgeUnknownWorkflowTypes !== void 0 ? { acknowledgeUnknownWorkflowTypes: options.acknowledgeUnknownWorkflowTypes } : {});
       if (shouldStartEngineScheduler(options, getInternals(engine).options.backgroundTaskMode))
@@ -424,6 +439,16 @@ export class Engine extends EventTarget {
     getInternals(this).activityWorkerDispatcher = createActivityWorkerDispatcher(options?.activityExecution);
     getInternals(this).strategy.onMessage(this.#handleStrategyMessage.bind(this));
     getInternals(this).alertManager = options?.alerts ? new AlertManager(this, options.alerts, getNow, resolvedOptions.backgroundTaskMode === "automatic") : null;
+    getInternals(this).workflowCatalog = null;
+    getInternals(this).pendingCatalogInstalls = [];
+    getInternals(this).catalogRestored = !1;
+    getInternals(this).catalogDrainPromise = null;
+    getInternals(this).registeredCatalogRevisions = new Map;
+    getInternals(this).inFlightStartsByRevision = new Map;
+    getInternals(this).workflowSourcesByName = new Map;
+    getInternals(this).sourceResolutionsInFlight = new Map;
+    getInternals(this).sourceResolutionWaiterControllers = new Set;
+    getInternals(this).resolvedWorkflowSources = new Map;
     this.#ensureRetentionSweepInterval();
     this.#startSecondInstanceDetection();
   }
@@ -675,6 +700,9 @@ export class Engine extends EventTarget {
       workflow: (workflowType, key, options) => new AtomicState(storage, KEYS.stateWorkflow(workflowType, key), options)
     };
   }
+  get workflows() {
+    return createEngineWorkflowsNamespace(this);
+  }
   getActiveAlerts() {
     return getInternals(this).alertManager?.activeStates ?? [];
   }
@@ -692,6 +720,12 @@ export class Engine extends EventTarget {
     registerWorkflow(getInternals(this), definition, this.#createRegistrationCallbacks());
     return typedEngineView(this);
   }
+  registerSource(source) {
+    registerWorkflowSource(getInternals(this), source);
+  }
+  async resolveWorkflowSource(name, revision, options) {
+    return resolveWorkflowSourceImpl(this, name, revision, options);
+  }
   registerWorkflows(workflows) {
     for (const [name, definition] of Object.entries(workflows)) {
       if (name !== definition.name)
@@ -730,14 +764,25 @@ export class Engine extends EventTarget {
   listActivityDefinitions() {
     return getInternals(this).activityRegistry.listDefinitions();
   }
+  getWorkflowActivityDefinition(workflowType, activityName) {
+    const internals = getInternals(this);
+    return internals.activityRegistriesByWorkflow.get(workflowType)?.getDefinition(activityName) ?? internals.activityRegistry.getDefinition(activityName);
+  }
+  listWorkflowActivityDefinitions(workflowType) {
+    return getInternals(this).activityRegistriesByWorkflow.get(workflowType)?.listDefinitions() ?? [];
+  }
   async start(type, input, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     if (options?.idempotencyKey !== void 0)
       return startWithIdempotencyFromLifecycle(getInternals(this), type, input, options, this.#createLifecycleCallbacks());
     return startWorkflowFromLifecycle(getInternals(this), type, input, options, void 0, this.#createLifecycleCallbacks());
   }
   async startOrSignal(type, input, signal, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return startOrSignalFromLifecycle(getInternals(this), type, input, signal, options, this.#createStartOrSignalCallbacks());
   }
   #createStartOrSignalCallbacks() {
@@ -810,6 +855,8 @@ export class Engine extends EventTarget {
   async schedule(typeOrDefinition, input, spec, options) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     if (typeof typeOrDefinition === "object")
       return scheduleDefinitionFromInternals(internals, typeOrDefinition);
     if (spec === void 0)
@@ -826,21 +873,29 @@ export class Engine extends EventTarget {
   async pauseSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return pauseScheduleFromInternals(internals, scheduleId);
   }
   async resumeSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return resumeScheduleFromInternals(internals, scheduleId);
   }
   async cancelSchedule(scheduleId) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return cancelScheduleFromInternals(internals, scheduleId);
   }
   async updateSchedule(scheduleId, newSpec, options) {
     const internals = getInternals(this);
     assertLeaseHeldForEngineWork(internals);
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return updateScheduleFromInternals(internals, scheduleId, newSpec, options);
   }
   [HANDLE_RESULT_PROMISE](workflowId) {
@@ -906,10 +961,14 @@ export class Engine extends EventTarget {
   }
   async fork(sourceWorkflowId, options) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return forkFromLifecycle(getInternals(this), sourceWorkflowId, options, this.#createLifecycleCallbacks());
   }
   async resume(workflowId) {
     assertLeaseHeldForEngineWork(getInternals(this));
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     return resumeFromLifecycle(getInternals(this), workflowId, this.#createLifecycleCallbacks());
   }
   async recoverAll(options) {
@@ -917,6 +976,8 @@ export class Engine extends EventTarget {
     await this.#acquireLeaseIfConfigured();
     if (getInternals(this).disposed)
       throw new EngineDisposedError;
+    if (!isWorkflowCatalogReady(this))
+      await ensureWorkflowCatalogReady(this);
     await recoverPendingAsyncActivities(getInternals(this));
     await recoverOrphanedScheduleTimers(getInternals(this));
     getInternals(this).onRecoveredWorkflowHook = options?.onRecoveredWorkflow;

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

@@ -29,7 +29,7 @@ import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
 import type { ComposedActivityInterceptor, ComposedWorkflowInterceptor, Interceptor } from '../interceptor.ts';
 import type { HumanReviewResult, ReviewCoordinator } from '../review/index.ts';
 import type { Scheduler } from '../scheduler.ts';
-import type { Checkpoint, StartWorkflowOptions } from '../types.ts';
+import type { Checkpoint, StartWorkflowOptions, WorkflowDefinition } from '../types.ts';
 import type { UpdateCoordinator } from '../updates.ts';
 import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
 import type { RecoveredWorkflowInfo } from './lifecycle/shared.ts';
@@ -58,6 +58,12 @@ export type DurableInlineOperation = {
 type EngineRuntime = WorkflowHandleEngine & ScheduleHandleEngine & {
     start(type: string, input: unknown, options?: StartWorkflowOptions): Promise<WorkflowHandle>;
 };
+type SourceHandle = import('../source/index.ts').WorkflowSourceHandle;
+type CatalogRevisionRecord = import('../catalog/index.ts').WorkflowRevisionRecord;
+type ResolvedSource = {
+    definition: WorkflowDefinition;
+    activityRegistry: ActivityRegistry;
+};
 export interface EngineInternals {
     engine: EngineRuntime;
     storage: WeftStorage;
@@ -386,6 +392,31 @@ export interface EngineInternals {
     workflowVisibilityWatermarkExpiresAt: number | undefined;
     pendingTimelineEntries: Map<string, PendingTimelineEntry>;
     pendingAtomicWorkflowCommitSideEffects: Map<string, import('./checkpoint-side-effects.ts').AtomicWorkflowCommitSideEffects>;
+    /**
+     * The durable workflow catalog (WFT-9/WFT-10), `null` until
+     * {@link import('./catalog-readiness.ts').ensureWorkflowCatalogReady} first
+     * restores it from storage. Read via {@link getWorkflowCatalog}, never
+     * directly.
+     */
+    workflowCatalog: import('../catalog/index.ts').WorkflowCatalog | null;
+    /** Workflow names `commitWorkflowDefinition` (`registration.ts`) has queued for catalog install+activate since the last drain — `engine.register()` stays synchronous (it cannot itself build a manifest) and defers to the next `ensureWorkflowCatalogReady` call. */
+    pendingCatalogInstalls: string[];
+    /** Whether {@link workflowCatalog} has been restored from storage at least once. */
+    catalogRestored: boolean;
+    /** The in-flight catalog restore-and-drain, or `null` when none is running; concurrent `ensureWorkflowCatalogReady` callers await this same promise rather than racing a second restore/drain. */
+    catalogDrainPromise: Promise<void> | null;
+    /** Name -> revision this process's own register()-drain most recently activated (WFT-12, `catalog-readiness.ts`). Process-local, never persisted. */
+    registeredCatalogRevisions: Map<string, string>;
+    /** Name -> revision -> in-flight `startWorkflow` count (WFT-12, `lifecycle/start.ts`). Process-local, never persisted. */
+    inFlightStartsByRevision: Map<string, Map<string, number>>;
+    /** Dynamic workflow sources (WFT-13/14): `registerSource()` candidates, keyed name then revision. Registering never invokes the loader. Process-local, never persisted. */
+    workflowSourcesByName: Map<string, Map<string, SourceHandle>>;
+    /** In-flight `resolveWorkflowSource` single-flight load per `(name, revision)`. Self-removes on settle via a `catalogDrainPromise`-style identity guard. */
+    sourceResolutionsInFlight: Map<string, Map<string, Promise<CatalogRevisionRecord>>>;
+    /** Per-caller `AbortController`s from in-flight `resolveWorkflowSource()` calls; disposal aborts every waiter without touching the shared load (mirrors `pendingWebhooks`). */
+    sourceResolutionWaiterControllers: Set<AbortController>;
+    /** A successful `resolveWorkflowSource()`'s live definition, keyed name then revision. Unread this batch — WFT-15's job. */
+    resolvedWorkflowSources: Map<string, Map<string, ResolvedSource>>;
 }
 /**
  * Set up an empty `EngineInternals` skeleton in the WeakMap. The Engine
@@ -406,4 +437,16 @@ export declare function initializeInternals(engine: EngineRuntime): void;
  * internals existing.
  */
 export declare function getInternals(engine: object): EngineInternals;
+/**
+ * Read an engine's durable workflow catalog. Throws when it has not been
+ * restored yet — every public entry point that can observe catalog state
+ * (`start`, `startOrSignal`, `schedule`/`pauseSchedule`/`resumeSchedule`/
+ * `cancelSchedule`/`updateSchedule`, `fork`, `resume`, `recoverAll`,
+ * `Engine.create`, and `buildRegistrySnapshot`) awaits
+ * `ensureWorkflowCatalogReady(engine)` first, which restores it. Calling
+ * this before that await boundary — for example from a pathological
+ * direct-internals test — is a programming error, not a recoverable runtime
+ * condition, so it fails loud rather than returning a placeholder catalog.
+ */
+export declare function getWorkflowCatalog(engine: object): import('../catalog/index.ts').WorkflowCatalog;
 export {};

package/dist/core/engine/internals.js

@@ -9,3 +9,9 @@ export function getInternals(engine) {
     throw Error("Engine internals not initialized \u2014 initializeInternals(this) was not called in the Engine constructor");
   return internals;
 }
+export function getWorkflowCatalog(engine) {
+  const internals = getInternals(engine);
+  if (internals.workflowCatalog === null)
+    throw Error("Workflow catalog not restored \u2014 ensureWorkflowCatalogReady(engine) was not awaited before " + "getWorkflowCatalog(engine) was called.");
+  return internals.workflowCatalog;
+}

package/dist/core/engine/lifecycle/start.js

@@ -9,6 +9,7 @@ import {
   coerceStartWorkflowTimestamp,
   parseStartWorkflowDuration
 } from "../../start-workflow-validation.js";
+import { releaseInFlightStart, reserveInFlightStart } from "../catalog-removal.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { WorkflowAlreadyExistsError, WorkflowNotRegisteredError } from "../errors.js";
 import { createDelayedStartTimerEntry } from "../operations-time.js";
@@ -90,6 +91,7 @@ export async function startWorkflow(internals, type, input, options, additionalS
     throw new WorkflowAlreadyExistsError(workflowId);
   internals.pendingStarts.add(workflowId);
   let startSucceeded = !1;
+  const inFlightRevision = reserveInFlightStart(internals, type);
   try {
     const terminalRunToPurge = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : null;
     assertPayloadWithinLimit(input, internals.options.payloadSizePolicy.maxBytes, "workflow input");
@@ -133,6 +135,7 @@ export async function startWorkflow(internals, type, input, options, additionalS
     return handle;
   } finally {
     internals.pendingStarts.delete(workflowId);
+    releaseInFlightStart(internals, type, inFlightRevision);
     if (!startSucceeded)
       rollbackTransientStartState(internals, workflowId);
   }

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

@@ -1,7 +1,83 @@
+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;
 };
+/**
+ * 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;
+/**
+ * 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,12 +7,13 @@ 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) {
   if (!registration.constraints || registration.constraints.length === 0)
@@ -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)) {
@@ -78,25 +80,29 @@ function normalizeMessageDefinitions(workflowType, messageKind, definitions) {
 function commitWorkflowDefinition(internals, definition, callbacks) {
   const name = definition.name;
   validateWorkflowOrActivityName(name, "workflow");
+  if (internals.workflowSourcesByName.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);
+  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/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;