@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/engine/dynamic-source-errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Errors raised by the dynamic workflow source pipeline (WFT-15/16):
+ * {@link DynamicWorkflowSourceUnavailableError} at an execution entry point
+ * — `start`, `startOrSignal`, `schedule`, `fork`, `resume`, recovery, and
+ * bulk-retry — when a registered source's revision is ambiguous or its
+ * load fails; {@link WorkflowSourceNotRegisteredError} by
+ * `engine.resolveWorkflowSource()` / `engine.workflows.preload()` directly.
+ * Split out of `errors.ts`, which is at the repository's 500-line
+ * implementation-file ceiling with no headroom for two more documented
+ * classes; kept alongside `lease-errors.ts` and `source/errors.ts` as this
+ * file family's precedent for a domain-scoped errors module.
+ *
+ * @module core/engine/dynamic-source-errors
+ */
+import { WeftError } from '../weft-error.ts';
+/**
+ * Thrown by `engine.resolveWorkflowSource()` (and its
+ * `engine.workflows.preload()` alias) when called against a specific
+ * `(name, revision)` that `registerSource()` never recorded — a
+ * programmer-error contract, not untrusted-input rejection. `revision` is
+ * therefore always defined in practice.
+ *
+ * This is a DIFFERENT case from a workflow `type` with no eager
+ * registration AND no dynamic source at all: every execution entry point
+ * (`start`, `startOrSignal`, `schedule`, `fork`, `resume`, recovery,
+ * bulk-retry) keeps throwing the pre-existing
+ * {@link WorkflowNotRegisteredError} for that case instead, preserving the
+ * fault classification and wire code callers already depended on before
+ * WFT-15/16 — see `dynamic-source-execution.ts`'s
+ * `resolveExecutableRegistration()`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceNotRegisteredError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.resolveWorkflowSource('checkout', 'r-never-registered');
+ * } catch (err) {
+ *   if (err instanceof WorkflowSourceNotRegisteredError) {
+ *     console.error('registerSource() it first:', err.workflowType, err.revision);
+ *   }
+ * }
+ * ```
+ */
+export declare class WorkflowSourceNotRegisteredError extends WeftError<'WorkflowSourceNotRegisteredError'> {
+    readonly workflowType: string;
+    readonly revision: string | undefined;
+    constructor(workflowType: string, revision?: string);
+}
+/**
+ * Thrown when a registered dynamic workflow source cannot be turned into an
+ * executable registration: either its load failed (`reason: 'load-failed'`,
+ * `cause` carries the underlying error) or which revision to resolve could
+ * not be determined (`reason: 'ambiguous-revision'` — two or more revisions
+ * are registered for `workflowType` and the catalog has no active pointer
+ * naming one of them). Recovery classifies the affected type `unavailable`:
+ * only its runs fail, with this error as the `system` failure cause;
+ * sibling types continue.
+ *
+ * @example
+ * ```ts
+ * import { Engine, DynamicWorkflowSourceUnavailableError } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * try {
+ *   await engine.start('checkout', { orderId: 'order-1' });
+ * } catch (err) {
+ *   if (err instanceof DynamicWorkflowSourceUnavailableError) {
+ *     console.error(err.workflowType, err.reason);
+ *   }
+ * }
+ * ```
+ */
+export declare class DynamicWorkflowSourceUnavailableError extends WeftError<'DynamicWorkflowSourceUnavailableError'> {
+    readonly workflowType: string;
+    readonly revision: string | undefined;
+    readonly reason: 'load-failed' | 'ambiguous-revision';
+    readonly cause: unknown;
+    constructor(workflowType: string, revision: string | undefined, reason: 'load-failed' | 'ambiguous-revision', cause?: unknown);
+}

package/dist/core/engine/dynamic-source-errors.js

@@ -0,0 +1,25 @@
+import { WeftError } from "../weft-error.js";
+
+export class WorkflowSourceNotRegisteredError extends WeftError {
+  workflowType;
+  revision;
+  constructor(workflowType, revision) {
+    super("WorkflowSourceNotRegisteredError", revision === void 0 ? `No workflow registered with name "${workflowType}"` : `resolveWorkflowSource("${workflowType}", "${revision}") was called before registerSource() ` + "registered this exact (name, revision) \u2014 call engine.registerSource() first.");
+    this.workflowType = workflowType;
+    this.revision = revision;
+  }
+}
+
+export class DynamicWorkflowSourceUnavailableError extends WeftError {
+  workflowType;
+  revision;
+  reason;
+  cause;
+  constructor(workflowType, revision, reason, cause) {
+    super("DynamicWorkflowSourceUnavailableError", reason === "ambiguous-revision" ? `Cannot resolve dynamic workflow source "${workflowType}": multiple revisions are registered and none is the catalog active revision. Activate one via engine.workflows.activate(), or register only one revision at a time.` : `Dynamic workflow source "${workflowType}"${revision === void 0 ? "" : ` revision "${revision}"`} failed to load: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.workflowType = workflowType;
+    this.revision = revision;
+    this.reason = reason;
+    this.cause = cause;
+  }
+}

package/dist/core/engine/dynamic-source-execution.d.ts

@@ -0,0 +1,173 @@
+/**
+ * `resolveExecutableRegistration()` — the single async helper every
+ * execution entry point that can launch or resume a workflow
+ * (`start`/`startOrSignal`/`schedule`/`fork`/`resume`/recovery/bulk-retry)
+ * funnels through to turn a workflow `type` into a `RegistrationEntry` it
+ * can actually run (WFT-15/16).
+ *
+ * Fast path: an eagerly `engine.register()`-ed type resolves synchronously
+ * from `internals.registrations` and never touches `internals.sources` —
+ * this is what makes "starting the eager workflow does not import the lazy
+ * module" true. Slow path: a `engine.registerSource()`-registered type is
+ * resolved via `resolveWorkflowSourceForExecution()`, which awaits the
+ * loader (single-flight, shared with any other concurrent caller for the
+ * same key) and installs the result durably before this returns — so no
+ * workflow handler ever runs while its definition is still a catalog
+ * candidate.
+ *
+ * @module core/engine/dynamic-source-execution
+ */
+import type { Engine } from './index.ts';
+import type { EngineInternals } from './internals.ts';
+type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+/** The outcome of {@link resolveExecutableRegistration}. */
+export type ExecutableRegistration = {
+    entry: RegistrationEntry;
+    /** The dynamic source revision resolved, or `undefined` for an eager registration. */
+    revision: string | undefined;
+};
+/**
+ * Turn workflow `type` into an executable {@link RegistrationEntry}, awaiting
+ * dynamic-source resolution when `type` is not eagerly registered. Throws
+ * {@link WorkflowNotRegisteredError} when `type` is neither an eager
+ * registration nor a registered source (the pre-existing error — see the
+ * call site below for why); {@link DynamicWorkflowSourceUnavailableError}
+ * when a registered source's target revision is ambiguous or its load
+ * fails; {@link EngineDisposedError} unwrapped when the engine is disposed
+ * during resolution.
+ */
+export declare function resolveExecutableRegistration(engine: Engine, internals: EngineInternals, type: string, onRevisionChosen?: (revision: string) => void): Promise<ExecutableRegistration>;
+/**
+ * The shared classification `resolveExecutableRegistrationForRevision()`'s
+ * throw-vs-proceed decision and the ADR-0002 workflow-lease reclaim-
+ * eligibility gate (`index.ts`'s `isWorkflowTypeRegistered`) both delegate
+ * to, so the two decisions can never drift out of sync — an engine that
+ * cannot locally resolve a run's exact pin must never win that run's claim
+ * either (see `workflow-claim-reclaim-target.ts`'s own doc for why that
+ * would strand the run under a permanently-failing `onReclaimed` drive).
+ *
+ * - An eager registration is always resolvable, regardless of `revision`
+ *   (eager has no ambiguity to pin against).
+ * - `type` with no eager registration and no registered source at all is
+ *   never resolvable.
+ * - A dynamic source with `revision === undefined` (legacy/pre-pinning) is
+ *   resolvable only when it has exactly one registered candidate —
+ *   unambiguous by construction. Two or more is ambiguous; zero is
+ *   impossible (an empty `byRevision` map does not exist — the type
+ *   wouldn't be in `sources.byName` at all).
+ * - A dynamic source with a defined `revision` is resolvable exactly when
+ *   that revision is among this process's currently registered candidates.
+ */
+export declare function canResolveRevisionLocally(internals: EngineInternals, type: string, revision: string | undefined): boolean;
+/**
+ * Resolve workflow `type` against its EXACT pinned `revision` — the
+ * `WorkflowState.revision` a run persisted at start (WFT-17) — instead of
+ * whichever revision the catalog currently considers active. This is the
+ * resolver `resumeWorkflowFromStorage()` (`lifecycle/resume.ts`) uses for
+ * EVERY resume (both `recoverAll()`'s batch and a standalone
+ * `engine.resume(id)`), so "recovery never falls back from a missing exact
+ * revision to the active revision" (WFT-17/WFT-18's acceptance criterion)
+ * holds uniformly, not just inside the batch preflight.
+ *
+ * Classification:
+ * - An eager registration is always resolved from `internals.registrations`
+ *   regardless of `revision` — eager has no ambiguity to pin against (the
+ *   process runs whatever code it has loaded), so a stale or absent pin on
+ *   an eager type is harmless and must not block the common redeploy path.
+ * - A dynamic source with `revision === undefined` (a legacy, pre-pinning
+ *   record) falls through to the ordinary {@link resolveExecutableRegistration}
+ *   active-pointer resolution when the type has at most one registered
+ *   candidate (unambiguous by construction), or throws
+ *   {@link WorkflowRevisionUnavailableError} with `reason: 'legacy-ambiguous'`
+ *   when it has two or more (there is no way to tell which one the run
+ *   actually started against).
+ * - A dynamic source with a defined `revision` throws
+ *   {@link WorkflowRevisionUnavailableError} with `reason: 'not-registered'`
+ *   when that exact revision is not among this process's registered
+ *   candidates (covers both "never registered at all" and "was the sole
+ *   candidate, but a different one is registered now") — otherwise it is
+ *   loaded and installed exactly like {@link resolveExecutableRegistration}'s
+ *   own dynamic path.
+ * - `type` with neither an eager registration nor any registered source
+ *   throws the pre-existing {@link WorkflowNotRegisteredError}, matching
+ *   {@link resolveExecutableRegistration}.
+ */
+export declare function resolveExecutableRegistrationForRevision(engine: Engine, internals: EngineInternals, type: string, revision: string | undefined): Promise<ExecutableRegistration>;
+/**
+ * Wraps `callbacks.resolveExecutableRegistration(type)`, remapping ONLY the
+ * "no source registered at all" case (a {@link WorkflowNotRegisteredError})
+ * to `notFoundError` — a caller's own, more-specific "no workflow
+ * registered" message (naming the workflow ID it was
+ * resuming/forking/retrying, for example) instead of the generic one. Every
+ * other error (including a source found but unresolvable) propagates
+ * unwrapped. Shared by `resume.ts`, `transition.ts`'s `fork()`, and
+ * `bulk-operations.ts`'s retry path so each keeps a single, low-complexity
+ * call site instead of its own try/catch.
+ */
+export declare function resolveExecutableRegistrationOrRenamedNotFound(resolve: (type: string) => Promise<ExecutableRegistration>, type: string, notFoundError: () => Error): Promise<ExecutableRegistration>;
+/**
+ * {@link resolveExecutableRegistrationOrRenamedNotFound}, pre-bound to
+ * `bulk-operations.ts`'s retry-failed message shape. Resolves against the
+ * failed run's own EXACT pinned `revision` (`WorkflowState.revision`, WFT-17)
+ * via {@link resolveExecutableRegistrationForRevision} — never the catalog's
+ * active pointer — so a bulk retry's pre-reactivation concurrency-admission
+ * lookup agrees with the exact-revision resolve the subsequent
+ * `engine.resume()` performs. Resolving against the active pointer here
+ * instead would let a retry commit the failed->running reactivation batch
+ * against the WRONG registration's `concurrency` config, and then — if the
+ * pinned revision is unavailable while a different revision is active —
+ * only discover that after the reactivation already committed, leaving the
+ * run stranded `running` with no generator ever resuming. Kept here (with
+ * the bulk of the logic off `bulk-operations.ts`, already at its own
+ * oxlint `max-lines` ceiling) rather than inlined at that one call site.
+ */
+export declare function resolveExecutableRegistrationForRetry(internals: EngineInternals, type: string, revision: string | undefined, workflowId: string): Promise<ExecutableRegistration>;
+/**
+ * Sync-only fallback lookup for PER-INSTANCE call sites that run after a
+ * workflow is already executing (or is being swept from storage) and must
+ * never trigger a new resolve — finalizer, constraint, retention, and
+ * search-attribute-schema resolution (`termination/finalizer-registration.ts`,
+ * `constraints.ts`, `workflow-retention-deadline.ts`, `listing.ts`). Reads
+ * the eager registration first (an eager type resolves the same regardless
+ * of `revision` — see {@link canResolveRevisionLocally}'s doc). Otherwise:
+ *
+ * - A defined `revision` reads `internals.sources.resolved.get(type)?.get(revision)`
+ *   directly — the running instance's OWN exact pin — with NO fallback to a
+ *   different revision when that exact one is not locally resolved (returns
+ *   `undefined` instead, matching {@link resolveExecutableRegistrationForRevision}'s
+ *   "never silently substitute a different revision" contract).
+ * - `revision === undefined` (a legacy pre-pinning record) falls back to
+ *   `internals.sources.lastResolvedRevisionByName` ONLY when
+ *   {@link canResolveRevisionLocally} classifies that as unambiguous —
+ *   exactly one registered candidate for `type`. With two or more
+ *   registered candidates this is genuinely ambiguous for a SPECIFIC
+ *   instance (WFT-19 review round 6, Codex, P1): silently substituting
+ *   whichever sibling revision this process last resolved could validate
+ *   `setAttributes()` against a sibling's schema, run a sibling's
+ *   finalizer, or — worst, since purge is irreversible — purge a run early
+ *   under a sibling's shorter retention window. Returns `undefined` in that
+ *   case instead, forcing the caller's async fallback
+ *   (`resolveExecutableRegistrationForRevision()`) to reach the
+ *   `legacy-ambiguous` classification and fail closed the same way it
+ *   already does for resume/recovery. {@link resolveLastKnownDynamicRegistration}
+ *   is the deliberate exception for the one genuinely TYPE-level caller
+ *   that wants the permissive last-resolved-wins answer even when
+ *   ambiguous.
+ *
+ * Returns `undefined` when no source has a matching entry.
+ */
+export declare function getResolvedDynamicRegistration(internals: EngineInternals, type: string, revision: string | undefined): RegistrationEntry | undefined;
+/**
+ * TYPE-level, sync-only "whatever this process last resolved" lookup —
+ * used ONLY by `retention.ts`'s `resolveWorkflowTypeRetention()`, an
+ * across-all-registered-types OVERVIEW API (`getRetentionOverview()`) with
+ * no single running instance to pin against, unlike every caller of
+ * {@link getResolvedDynamicRegistration} above. Deliberately does NOT fail
+ * closed when 2+ candidates are registered for `type`: for an overview,
+ * showing the last-resolved candidate's policy is a more useful signal
+ * than showing nothing, and — unlike `getResolvedDynamicRegistration`'s
+ * per-instance callers — no irreversible action (purge, finalizer run,
+ * schema validation) hangs off this call (WFT-19 review round 6, Codex).
+ */
+export declare function resolveLastKnownDynamicRegistration(internals: EngineInternals, type: string): RegistrationEntry | undefined;
+export {};

package/dist/core/engine/dynamic-source-execution.js

@@ -0,0 +1,108 @@
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+import { DynamicWorkflowSourceUnavailableError } from "./dynamic-source-errors.js";
+import { EngineDisposedError, WorkflowNotRegisteredError } from "./errors.js";
+import { assertConstraintsSupported, buildRegistrationEntry } from "./registration.js";
+import { WorkflowRevisionUnavailableError } from "./revision-errors.js";
+import { resolveWorkflowSourceForExecution } from "./source-resolution.js";
+async function resolveActiveSourceRevision(engine, type, byRevision) {
+  await ensureWorkflowCatalogReady(engine);
+  const activeRevision = (await getWorkflowCatalog(engine).resolveActiveDurable(type))?.revision;
+  if (activeRevision !== void 0 && byRevision.has(activeRevision))
+    return activeRevision;
+  throw new DynamicWorkflowSourceUnavailableError(type, void 0, "ambiguous-revision");
+}
+export async function resolveExecutableRegistration(engine, internals, type, onRevisionChosen) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return { entry: eager, revision: void 0 };
+  const byRevision = internals.sources.byName.get(type);
+  if (byRevision === void 0)
+    throw new WorkflowNotRegisteredError(type);
+  let revision;
+  if (byRevision.size === 1) {
+    revision = [...byRevision.keys()][0];
+    onRevisionChosen?.(revision);
+  } else {
+    revision = await resolveActiveSourceRevision(engine, type, byRevision);
+    onRevisionChosen?.(revision);
+  }
+  return loadAndInstallSourceRevision(engine, internals, type, revision);
+}
+async function loadAndInstallSourceRevision(engine, internals, type, revision) {
+  try {
+    await resolveWorkflowSourceForExecution(engine, type, revision);
+  } catch (error) {
+    if (error instanceof EngineDisposedError)
+      throw error;
+    throw new DynamicWorkflowSourceUnavailableError(type, revision, "load-failed", error);
+  }
+  const resolved = internals.sources.resolved.get(type)?.get(revision);
+  if (resolved === void 0)
+    throw new DynamicWorkflowSourceUnavailableError(type, revision, "load-failed", Error("Dynamic workflow source resolved without populating a local definition"));
+  assertConstraintsSupported(internals, type, resolved.definition);
+  const entry = buildRegistrationEntry(type, resolved.definition);
+  internals.workflowTypesByHandler.set(resolved.definition.handler, type);
+  internals.sources.lastResolvedRevisionByName.set(type, revision);
+  return { entry, revision };
+}
+export function canResolveRevisionLocally(internals, type, revision) {
+  if (internals.registrations.has(type))
+    return !0;
+  const byRevision = internals.sources.byName.get(type);
+  if (byRevision === void 0)
+    return !1;
+  if (revision === void 0)
+    return byRevision.size === 1;
+  return byRevision.has(revision);
+}
+export async function resolveExecutableRegistrationForRevision(engine, internals, type, revision) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return { entry: eager, revision: void 0 };
+  if (internals.sources.byName.get(type) === void 0)
+    throw new WorkflowNotRegisteredError(type);
+  if (!canResolveRevisionLocally(internals, type, revision)) {
+    if (revision === void 0)
+      throw new WorkflowRevisionUnavailableError(type, void 0, "legacy-ambiguous");
+    throw new WorkflowRevisionUnavailableError(type, revision, "not-registered");
+  }
+  if (revision === void 0)
+    return resolveExecutableRegistration(engine, internals, type);
+  return loadAndInstallSourceRevision(engine, internals, type, revision);
+}
+export async function resolveExecutableRegistrationOrRenamedNotFound(resolve, type, notFoundError) {
+  return resolve(type).catch((error) => {
+    if (error instanceof WorkflowNotRegisteredError)
+      throw notFoundError();
+    throw error;
+  });
+}
+export async function resolveExecutableRegistrationForRetry(internals, type, revision, workflowId) {
+  return resolveExecutableRegistrationOrRenamedNotFound((t) => resolveExecutableRegistrationForRevision(internals.engine, internals, t, revision), type, () => Error(`No workflow registered with name "${type}" (needed to retry "${workflowId}")`));
+}
+export function getResolvedDynamicRegistration(internals, type, revision) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return eager;
+  if (revision !== void 0) {
+    const resolved = internals.sources.resolved.get(type)?.get(revision);
+    if (resolved === void 0)
+      return;
+    return buildRegistrationEntry(type, resolved.definition);
+  }
+  if (!canResolveRevisionLocally(internals, type, void 0))
+    return;
+  return resolveLastKnownDynamicRegistration(internals, type);
+}
+export function resolveLastKnownDynamicRegistration(internals, type) {
+  const eager = internals.registrations.get(type);
+  if (eager !== void 0)
+    return eager;
+  const targetRevision = internals.sources.lastResolvedRevisionByName.get(type);
+  if (targetRevision === void 0)
+    return;
+  const resolved = internals.sources.resolved.get(type)?.get(targetRevision);
+  if (resolved === void 0)
+    return;
+  return buildRegistrationEntry(type, resolved.definition);
+}

package/dist/core/engine/engine-internal-types.d.ts

@@ -3,6 +3,20 @@ import type { ConstraintDefinition } from '../constraint.ts';
 import type { ExecutionStrategy } from '../execution-strategy.ts';
 import type { InlineExecutionStrategy } from '../inline-execution-strategy.ts';
 import type { AnyActivityDefinition, ArchiveAdapter, Checkpoint, DefinitionSchema, EngineOptions, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, QueryDefinition, SearchAttributeSchema, SignalDefinition, UpdateDefinition, WorkflowConcurrencyOptions, WorkflowFunction, WorkflowTimelineEntry } from '../types.ts';
+/**
+ * The identity a running workflow instance was launched under, cached by
+ * `EngineInternals.workflowTypeByWorkflowId` for the lifetime of its
+ * execution (WFT-19). `revision` is the exact `WorkflowState.revision` this
+ * instance is pinned to (WFT-17) — `undefined` for an eager registration or
+ * a legacy (pre-pinning) record — so a process-local lookup keyed by
+ * `workflowId` can resolve THIS instance's own dynamic-source revision
+ * rather than falling back to whichever revision this process resolved
+ * last.
+ */
+export type WorkflowExecutionIdentity = {
+    type: string;
+    revision: string | undefined;
+};
 export interface RegistrationEntry {
     handler: WorkflowFunction;
     version: string;
@@ -103,6 +117,8 @@ export type QueuedInlineWorkflowExecutionStart = {
     nestingDepth: number;
     executionDeadline: number | undefined;
     executionStateOwnerId: string;
+    /** The exact revision this queued start is pinned to (WFT-17/WFT-19). */
+    revision: string | undefined;
     /**
      * Liveness callback invoked once this queued start has actually begun
      * executing (its generator has been driven). Set only for `defer: false`

package/dist/core/engine/engine-workflows-namespace.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Public promotion of the durable workflow catalog (WFT-9/WFT-10) to
+ * `engine.workflows` (WFT-11).
+ *
+ * This namespace is catalog bookkeeping and promotion control ONLY —
+ * `install()`/`activate()` change what {@link import('../registry-snapshot.ts').RegistrySnapshot}
+ * reports as the active revision, never which in-process handler
+ * `engine.start()` dispatches to. Execution routing resolves purely via
+ * `internals.registrations` (the workflow the process actually has code
+ * for), a concern dynamic module loading (WFT-13+) will connect to catalog
+ * activation. Until then, activating a different installed revision is
+ * observable only through this namespace, `getActive()`, and
+ * `buildRegistrySnapshot()` — starting a new run of `name` still executes
+ * whatever `engine.register()` last registered in this process.
+ *
+ * A later `engine.register()` call (or the restart-drain path that replays
+ * `pendingCatalogInstalls`) can silently revert a manual `activate()` here —
+ * `WorkflowCatalog.activateRegistered` is unconditional by design (see its
+ * own JSDoc) and does not consult or preserve a prior candidate activation.
+ * Reconciling loader-driven and registration-driven activation is WFT-13's
+ * job; this namespace does not attempt it.
+ *
+ * Every method awaits {@link ensureWorkflowCatalogReady} first (skipping the
+ * `await` entirely when {@link isWorkflowCatalogReady} already reports warm,
+ * matching every other catalog-observing entry point in `index.ts`), so the
+ * catalog is always restored from storage and every pending
+ * `engine.register()` install is drained before this namespace reads or
+ * writes it.
+ *
+ * @module core/engine/engine-workflows-namespace
+ */
+import { type WorkflowCatalogActivationResult, type WorkflowCatalogActivePointer, type WorkflowRevisionRecord } from '../catalog/index.ts';
+import type { WorkflowCompatibilityPolicy } from '../contract/compatibility.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { Engine } from './index.ts';
+import { type ResolveWorkflowSourceOptions } from './source-resolution.ts';
+/**
+ * Options accepted by {@link EngineWorkflowsNamespace.activate}.
+ *
+ * @example
+ * ```ts
+ * import { Engine } from '@lostgradient/weft';
+ * import type { ActivateWorkflowRevisionOptions } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const active = await engine.workflows.getActive('checkout');
+ * const options: ActivateWorkflowRevisionOptions = {
+ *   ...(active === null ? {} : { expectedGeneration: active.generation }),
+ *   policy: { requireExactRevision: false },
+ * };
+ * console.log(options.expectedGeneration);
+ * ```
+ */
+export type ActivateWorkflowRevisionOptions = {
+    /**
+     * The generation this caller last observed. Required once `name` has an
+     * active pointer — an omitted value there refuses with
+     * `expected-generation-required` rather than silently activating, which
+     * is what prevents two refreshers from racing to last-write-win. Omit (or
+     * pass `0`) for the very first activation of a name, which has no prior
+     * generation to name.
+     */
+    expectedGeneration?: number;
+    /** Compatibility policy; defaults to `DEFAULT_WORKFLOW_COMPATIBILITY_POLICY`. */
+    policy?: WorkflowCompatibilityPolicy;
+};
+/**
+ * Admin-facing surface over the durable workflow catalog: install a
+ * revision's manifest, activate an installed revision as the advertised
+ * active one, and read back installed/active state. Workflow code never
+ * touches this — it is an external maintenance and deployment-tooling
+ * surface, the same audience `engine.state.*` serves.
+ *
+ * @example
+ * ```ts
+ * import { Engine, buildWorkflowContract, buildWorkflowRevisionManifest } from '@lostgradient/weft';
+ * import { workflow, type WorkflowContext } from '@lostgradient/weft';
+ * import type { EngineWorkflowsNamespace } from '@lostgradient/weft';
+ *
+ * const checkout = workflow({ name: 'checkout', version: '1.0.0' }).execute(
+ *   async function* (_ctx: WorkflowContext, input: string) {
+ *     return input;
+ *   },
+ * );
+ *
+ * const engine = new Engine();
+ * engine.register(checkout);
+ * const workflows: EngineWorkflowsNamespace = engine.workflows;
+ *
+ * const contract = buildWorkflowContract({ name: 'checkout', version: '1.0.0' });
+ * const manifest = await buildWorkflowRevisionManifest(contract);
+ * const record = await workflows.install(manifest);
+ * const result = await workflows.activate('checkout', record.manifest.revision);
+ * console.log(result.applied);
+ * ```
+ */
+export interface EngineWorkflowsNamespace {
+    /**
+     * Install `manifest` for durable tracking. Requires
+     * `engine.getWorkflowDefinition(manifest.name)` to already resolve
+     * in-process — this namespace installs bookkeeping for a definition the
+     * engine already has, it does not load one (that is WFT-13+'s job).
+     * Idempotent on a byte-identical reinstall; throws
+     * {@link WorkflowCatalogConflictError} when `(manifest.name, manifest.revision)`
+     * is already installed with different contract content, and
+     * {@link WorkflowNotRegisteredError} when no in-process definition exists.
+     */
+    install(manifest: WorkflowRevisionManifest): Promise<WorkflowRevisionRecord>;
+    /**
+     * Activate an already-installed `(name, revision)` as the durably
+     * advertised active revision. Throws
+     * {@link WorkflowRevisionNotInstalledError} when that revision was never
+     * installed; otherwise delegates to the catalog's guarded
+     * `activateCandidate` and returns its structured result verbatim,
+     * including every `applied: false` refusal variant.
+     */
+    activate(name: string, revision: string, options?: ActivateWorkflowRevisionOptions): Promise<WorkflowCatalogActivationResult>;
+    /**
+     * The current active pointer for `name`, or `null` when never activated.
+     * In-memory only, matching {@link import('../registry-snapshot.ts').RegistrySnapshot}'s
+     * `activeRevisions` staleness contract exactly — the property that makes
+     * "operations and the registry snapshot agree" true by construction.
+     */
+    getActive(name: string): Promise<WorkflowCatalogActivePointer | null>;
+    /** One installed `(name, revision)` record, or `null` when not installed. */
+    getRevision(name: string, revision: string): Promise<WorkflowRevisionRecord | null>;
+    /** Every installed revision of `name`, sorted deterministically by revision. */
+    listRevisions(name: string): Promise<readonly WorkflowRevisionRecord[]>;
+    /**
+     * Load, validate, and install one dynamic workflow source revision
+     * previously recorded via `engine.registerSource()` (WFT-15/16). A thin,
+     * documented alias for `engine.resolveWorkflowSource()` — identical
+     * single-flight, cancellation, and error contract — offered here so
+     * deployment tooling that already reaches for `engine.workflows.*` for
+     * every other catalog operation does not need a second entry point.
+     */
+    preload(name: string, revision: string, options?: ResolveWorkflowSourceOptions): Promise<WorkflowRevisionRecord>;
+}
+/** Build the `engine.workflows` namespace object for `engine`. */
+export declare function createEngineWorkflowsNamespace(engine: Engine): EngineWorkflowsNamespace;

package/dist/core/engine/engine-workflows-namespace.js

@@ -0,0 +1,51 @@
+import {
+  WorkflowRevisionNotInstalledError
+} from "../catalog/index.js";
+import { activateCatalogRevisionCandidate } from "./catalog-activation.js";
+import {
+  ensureWorkflowCatalogReady,
+  getWorkflowCatalog,
+  isWorkflowCatalogReady
+} from "./catalog-readiness.js";
+import { WorkflowNotRegisteredError } from "./errors.js";
+import { resolveWorkflowSource } from "./source-resolution.js";
+async function ensureCatalogReady(engine) {
+  if (!isWorkflowCatalogReady(engine))
+    await ensureWorkflowCatalogReady(engine);
+}
+async function installWorkflowRevision(engine, manifest) {
+  await ensureCatalogReady(engine);
+  if (engine.getWorkflowDefinition(manifest.name) === void 0)
+    throw new WorkflowNotRegisteredError(manifest.name);
+  const entry = await getWorkflowCatalog(engine).install(manifest);
+  return { manifest: entry.manifest, installedAt: entry.installedAt };
+}
+async function activateWorkflowRevision(engine, name, revision, options) {
+  await ensureCatalogReady(engine);
+  const entry = await getWorkflowCatalog(engine).resolveEntry(name, revision);
+  if (entry === void 0)
+    throw new WorkflowRevisionNotInstalledError(name, revision);
+  return activateCatalogRevisionCandidate(engine, name, entry.manifest, options);
+}
+async function getActiveWorkflowRevision(engine, name) {
+  await ensureCatalogReady(engine);
+  return getWorkflowCatalog(engine).resolveActive(name) ?? null;
+}
+async function getInstalledWorkflowRevision(engine, name, revision) {
+  await ensureCatalogReady(engine);
+  return await getWorkflowCatalog(engine).resolveEntry(name, revision) ?? null;
+}
+async function listInstalledWorkflowRevisions(engine, name) {
+  await ensureCatalogReady(engine);
+  return getWorkflowCatalog(engine).listInstalledRevisions(name);
+}
+export function createEngineWorkflowsNamespace(engine) {
+  return {
+    install: (manifest) => installWorkflowRevision(engine, manifest),
+    activate: (name, revision, options) => activateWorkflowRevision(engine, name, revision, options),
+    getActive: (name) => getActiveWorkflowRevision(engine, name),
+    getRevision: (name, revision) => getInstalledWorkflowRevision(engine, name, revision),
+    listRevisions: (name) => listInstalledWorkflowRevisions(engine, name),
+    preload: (name, revision, options) => resolveWorkflowSource(engine, name, revision, options)
+  };
+}

package/dist/core/engine/finalizer-metadata.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Project a registration's stored definition-level finalizer onto the
+ * public, schema-only shape {@link RegisteredWorkflowDefinition.finalizer}
+ * exposes — split out of `construction.ts` so `copyWorkflowDefinition` stays
+ * under the repository's per-function complexity ceiling.
+ *
+ * @module core/engine/finalizer-metadata
+ */
+import type { AnyActivityDefinition } from '../types.ts';
+import type { RegisteredWorkflowDefinition } from '../types/workflow-registry.ts';
+/**
+ * Convert a stored `RegistrationEntry.finalizer` (when present) to a
+ * directly spreadable `{ finalizer: {...} } | {}` carrying the narrower
+ * schema-only shape `RegisteredWorkflowDefinition.finalizer` exposes — never
+ * the finalizer's `execute` handler, matching this interface's read-only
+ * introspection contract (the workflow's own handler is likewise never
+ * exposed). Returning the already-branched spread target (rather than
+ * `finalizer | undefined`, which would push a `=== undefined` ternary back
+ * onto the caller) keeps `copyWorkflowDefinition` under the repository's
+ * per-function complexity ceiling.
+ */
+export declare function copyFinalizerMetadata(finalizer: AnyActivityDefinition | undefined): Partial<Pick<RegisteredWorkflowDefinition, 'finalizer'>>;

package/dist/core/engine/finalizer-metadata.js

@@ -0,0 +1,12 @@
+export function copyFinalizerMetadata(finalizer) {
+  if (finalizer === void 0)
+    return {};
+  const source = finalizer;
+  return {
+    finalizer: {
+      name: source.name,
+      ...source.inputSchema === void 0 ? {} : { inputSchema: source.inputSchema },
+      ...source.outputSchema === void 0 ? {} : { outputSchema: source.outputSchema }
+    }
+  };
+}

package/dist/core/engine/handle-result.js

@@ -34,9 +34,11 @@ function fenceResultOnParentGeneration(internals, parentWorkflowId, promise) {
   promise.then(async (value) => {
     if (await parentStillOwnsGeneration(internals, parentWorkflowId))
       gate.resolve(value);
+    return;
   }, async (error) => {
     if (await parentStillOwnsGeneration(internals, parentWorkflowId))
       gate.reject(error);
+    return;
   });
   return gate.promise;
 }