@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/engine/catalog-readiness.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The sync/async boundary glue between `engine.register()` (synchronous,
+ * cannot itself build a manifest — that requires `crypto.subtle`) and the
+ * durable workflow catalog (async, WFT-9/WFT-10).
+ *
+ * `register()` stays byte-for-byte synchronous; `commitWorkflowDefinition`
+ * (`registration.ts`) only pushes the workflow's name onto
+ * `EngineInternals.pendingCatalogInstalls`. {@link ensureWorkflowCatalogReady}
+ * is the memoized function that, on first call, restores the catalog from
+ * storage, then drains `pendingCatalogInstalls` — building each pending
+ * workflow's manifest via the already-existing
+ * `buildWorkflowManifestForType` (`registry-workflow-manifest.ts`, reused
+ * rather than reimplemented) and unconditionally activating it via
+ * `WorkflowCatalog.activateRegistered`.
+ *
+ * Awaited at every entry point that can observe catalog state — see the
+ * call sites in `index.ts` — so "restore catalog state before recovery or
+ * any new start" holds.
+ *
+ * @module core/engine/catalog-readiness
+ */
+import type { Engine } from './index.ts';
+export { getWorkflowCatalog } from './internals.ts';
+/**
+ * Synchronous fast-path check: `true` once the catalog is restored and
+ * nothing is pending, `false` when {@link ensureWorkflowCatalogReady} would
+ * need to do real work. Every `ensureWorkflowCatalogReady` call site in
+ * `index.ts` guards its `await` with this check first — `await`ing an
+ * `async` function always costs one microtask tick even when the function's
+ * own body takes the fast path internally (JS's `await` semantics, not an
+ * implementation detail), so skipping the call entirely on an already-warm
+ * engine is what "avoid promise-machinery overhead on the hot path" (the
+ * WFT-9/WFT-10 design) actually requires — not just an early return inside
+ * the async function.
+ */
+export declare function isWorkflowCatalogReady(engine: Engine): boolean;
+/**
+ * Restore the workflow catalog from storage (once per engine instance) and
+ * drain any workflow names `engine.register()` has queued since the last
+ * drain. Memoized: concurrent callers await the same in-flight promise, and
+ * a call after a prior drain resolved with newly queued names starts a
+ * fresh drain rather than re-scanning storage.
+ *
+ * Also checks the {@link isWorkflowCatalogReady} fast path itself, so a
+ * direct call (bypassing a call site's own guard — as in
+ * `buildRegistrySnapshot`, or any future caller) is still cheap and correct
+ * without relying on every caller remembering to pre-check.
+ */
+export declare function ensureWorkflowCatalogReady(engine: Engine): Promise<void>;

package/dist/core/engine/catalog-readiness.js

@@ -0,0 +1,59 @@
+import { restoreWorkflowCatalog, WorkflowCatalog } from "../catalog/index.js";
+import { buildWorkflowManifestForType } from "../registry-workflow-manifest.js";
+import { dispatchCatalogInstallAndActivatedEvents } from "./catalog-events.js";
+import { EngineDisposedError } from "./errors.js";
+import { getInternals } from "./internals.js";
+export { getWorkflowCatalog } from "./internals.js";
+async function drainPendingCatalogInstalls(engine) {
+  const internals = getInternals(engine), catalog = internals.workflowCatalog, pending = internals.pendingCatalogInstalls;
+  internals.pendingCatalogInstalls = [];
+  for (let index = 0;index < pending.length; index += 1) {
+    const name = pending[index];
+    try {
+      const manifest = await buildWorkflowManifestForType(engine, name);
+      if (manifest === void 0)
+        continue;
+      const definition = engine.getWorkflowDefinition(name);
+      if (definition === void 0)
+        continue;
+      const preExisting = await catalog.hasInstalled(name, manifest.revision), pointerBefore = await catalog.resolveActiveDurable(name) ?? null, pointerAfter = await catalog.activateRegistered(name, manifest, definition);
+      internals.registeredCatalogRevisions.set(name, manifest.revision);
+      dispatchCatalogInstallAndActivatedEvents(engine, name, manifest.revision, preExisting, pointerBefore, pointerAfter);
+    } catch (error) {
+      internals.pendingCatalogInstalls = [
+        ...pending.slice(index),
+        ...internals.pendingCatalogInstalls
+      ];
+      throw error;
+    }
+  }
+}
+export function isWorkflowCatalogReady(engine) {
+  const internals = getInternals(engine);
+  return internals.catalogRestored && internals.pendingCatalogInstalls.length === 0;
+}
+export async function ensureWorkflowCatalogReady(engine) {
+  const internals = getInternals(engine);
+  if (isWorkflowCatalogReady(engine))
+    return;
+  if (internals.catalogDrainPromise !== null) {
+    await internals.catalogDrainPromise;
+    return ensureWorkflowCatalogReady(engine);
+  }
+  const drainPromise = (async () => {
+    if (internals.disposed)
+      throw new EngineDisposedError;
+    if (!internals.catalogRestored) {
+      internals.workflowCatalog = new WorkflowCatalog(internals.storage, await restoreWorkflowCatalog(internals.storage));
+      internals.catalogRestored = !0;
+    }
+    await drainPendingCatalogInstalls(engine);
+  })();
+  internals.catalogDrainPromise = drainPromise;
+  try {
+    await drainPromise;
+  } finally {
+    if (internals.catalogDrainPromise === drainPromise)
+      internals.catalogDrainPromise = null;
+  }
+}

package/dist/core/engine/catalog-removal.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Reference accounting and removal for the durable workflow catalog
+ * (WFT-12): counts in-process references to a `(name, revision)`,
+ * decides whether removal is safe, and performs the removal itself —
+ * dispatching `WorkflowRevisionRemovedEvent` on success.
+ *
+ * Also owns the two `EngineInternals.inFlightStartsByRevision` accessors
+ * ({@link reserveInFlightStart}/{@link releaseInFlightStart}) that
+ * `lifecycle/start.ts` rides alongside its existing `pendingStarts`
+ * reservation try/finally, kept here rather than inline in `start.ts` to
+ * stay well under that file's line-count ceiling.
+ *
+ * @module core/engine/catalog-removal
+ */
+import { type WorkflowRevisionReferenceCounts } from '../catalog/index.ts';
+import type { Engine } from './index.ts';
+import { type EngineInternals } from './internals.ts';
+/**
+ * Reserve one in-flight-start slot against `type`'s currently active
+ * revision (if any), returning the revision reserved (or `undefined` when
+ * `type` has no active revision yet — a start under a still-warming
+ * catalog, which `Engine.start()`'s own `ensureWorkflowCatalogReady` await
+ * prevents in practice). Called once, synchronously, before
+ * `startWorkflow`'s `try` block; the returned value is captured by the
+ * caller and passed back to {@link releaseInFlightStart} in its `finally` —
+ * never re-resolved, so a concurrent activation moving the pointer
+ * mid-start cannot decrement a different revision than was incremented.
+ */
+export declare function reserveInFlightStart(internals: EngineInternals, type: string): string | undefined;
+/** Release the slot {@link reserveInFlightStart} reserved; a no-op when `revision` is `undefined`. */
+export declare function releaseInFlightStart(internals: EngineInternals, type: string, revision: string | undefined): void;
+/**
+ * Count every in-process reference this batch wires to a real signal
+ * against `(name, revision)`. `registeredDefinitions` and `inFlightStarts`
+ * are real; the other five fields of {@link WorkflowRevisionReferenceCounts}
+ * stay `0` until WFT-17 (see that type's own field-level docs).
+ */
+export declare function countWorkflowRevisionReferences(engine: Engine, name: string, revision: string): Promise<WorkflowRevisionReferenceCounts>;
+/**
+ * Outcome of {@link removeWorkflowRevision}.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowCatalogRemovalResult } from '@lostgradient/weft';
+ *
+ * function describe(result: WorkflowCatalogRemovalResult): string {
+ *   return result.removed ? 'removed' : `kept: ${result.reason}`;
+ * }
+ * void describe;
+ * ```
+ */
+export type WorkflowCatalogRemovalResult = Readonly<{
+    removed: true;
+}> | Readonly<{
+    removed: false;
+    reason: 'not-found';
+}> | Readonly<{
+    removed: false;
+    reason: 'active';
+    activeRevision: string;
+}> | Readonly<{
+    removed: false;
+    reason: 'referenced';
+    references: WorkflowRevisionReferenceCounts;
+}> | Readonly<{
+    removed: false;
+    reason: 'conflict';
+}>;
+/**
+ * Remove `(name, revision)` from the durable workflow catalog. Refuses when
+ * the revision is not installed (`'not-found'`), is the currently active
+ * revision (`'active'`), or is referenced by any nonzero count in
+ * {@link countWorkflowRevisionReferences} (`'referenced'`, carrying the
+ * full breakdown so a caller can report exactly what is still holding the
+ * revision). Refuses with `'conflict'` when the durable delete's own
+ * compare-and-swap loses to a concurrent writer — the caller may re-read
+ * and retry. Dispatches `catalog:revision-removed` on success.
+ *
+ * @example
+ * ```ts
+ * import { Engine, removeWorkflowRevision, workflow } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.register(workflow({ name: 'checkout', version: '1.0.0' }).execute(
+ *   async function* () { return 'ok'; },
+ * ));
+ * const result = await removeWorkflowRevision(engine, 'checkout', 'some-old-revision');
+ * if (!result.removed) console.log('kept:', result.reason);
+ * ```
+ */
+export declare function removeWorkflowRevision(engine: Engine, name: string, revision: string): Promise<WorkflowCatalogRemovalResult>;
+/**
+ * Bounded diagnostics projection for one `(name, revision)`, backing
+ * `weft.catalog.diagnostics` and `removeWorkflowRevision`'s own pre-check.
+ *
+ * @example
+ * ```ts
+ * import type { WorkflowRevisionDiagnostics } from '@lostgradient/weft';
+ *
+ * function isSafeToRemove(diagnostics: WorkflowRevisionDiagnostics): boolean {
+ *   return diagnostics.removable;
+ * }
+ * void isSafeToRemove;
+ * ```
+ */
+export type WorkflowRevisionDiagnostics = Readonly<{
+    name: string;
+    revision: string;
+    installed: boolean;
+    active: boolean;
+    activeRevision?: string;
+    references: WorkflowRevisionReferenceCounts;
+    removable: boolean;
+}>;
+/**
+ * Bounded diagnostics for one `(name, revision)`: whether it is installed,
+ * whether it is the currently active revision (and what the active
+ * revision is, when different), its full reference-count breakdown, and
+ * whether {@link removeWorkflowRevision} would currently succeed against
+ * it (`removable`). Never returns raw manifest or contract content — only
+ * identity and counts.
+ *
+ * @example
+ * ```ts
+ * import { Engine, getWorkflowRevisionDiagnostics } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * const diagnostics = await getWorkflowRevisionDiagnostics(engine, 'checkout', 'some-revision');
+ * console.log(diagnostics.installed, diagnostics.removable);
+ * ```
+ */
+export declare function getWorkflowRevisionDiagnostics(engine: Engine, name: string, revision: string): Promise<WorkflowRevisionDiagnostics>;

package/dist/core/engine/catalog-removal.js

@@ -0,0 +1,70 @@
+import {
+  decrementNestedRevisionCount,
+  incrementNestedRevisionCount,
+  readNestedRevisionCount,
+  totalWorkflowRevisionReferences
+} from "../catalog/index.js";
+import { WorkflowRevisionRemovedEvent } from "../events/catalog-events.js";
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+import { getInternals } from "./internals.js";
+export function reserveInFlightStart(internals, type) {
+  const revision = internals.workflowCatalog?.resolveActive(type)?.revision;
+  if (revision !== void 0)
+    incrementNestedRevisionCount(internals.inFlightStartsByRevision, type, revision);
+  return revision;
+}
+export function releaseInFlightStart(internals, type, revision) {
+  if (revision !== void 0)
+    decrementNestedRevisionCount(internals.inFlightStartsByRevision, type, revision);
+}
+export async function countWorkflowRevisionReferences(engine, name, revision) {
+  const internals = getInternals(engine);
+  return {
+    registeredDefinitions: internals.registeredCatalogRevisions.get(name) === revision ? 1 : 0,
+    inFlightStarts: readNestedRevisionCount(internals.inFlightStartsByRevision, name, revision),
+    nonTerminalRuns: 0,
+    pinnedSchedules: 0,
+    pendingDispatches: 0,
+    activeExecutionRealms: 0,
+    retainedRecoveryRecords: 0
+  };
+}
+export async function removeWorkflowRevision(engine, name, revision) {
+  await ensureWorkflowCatalogReady(engine);
+  const catalog = getWorkflowCatalog(engine);
+  if (!await catalog.hasInstalled(name, revision))
+    return { removed: !1, reason: "not-found" };
+  const active = await catalog.resolveActiveDurable(name);
+  if (active !== void 0 && active.revision === revision)
+    return { removed: !1, reason: "active", activeRevision: active.revision };
+  const references = await countWorkflowRevisionReferences(engine, name, revision);
+  if (totalWorkflowRevisionReferences(references) > 0)
+    return { removed: !1, reason: "referenced", references };
+  const result = await catalog.remove(name, revision);
+  switch (result.outcome) {
+    case "removed":
+      engine.dispatchEvent(new WorkflowRevisionRemovedEvent(name, revision));
+      return { removed: !0 };
+    case "not-found":
+      return { removed: !1, reason: "not-found" };
+    case "active":
+      return { removed: !1, reason: "active", activeRevision: result.activeRevision };
+    case "conflict":
+      return { removed: !1, reason: "conflict" };
+    default:
+      throw Error(`Unknown workflow catalog removal outcome: ${String(result)}`);
+  }
+}
+export async function getWorkflowRevisionDiagnostics(engine, name, revision) {
+  await ensureWorkflowCatalogReady(engine);
+  const catalog = getWorkflowCatalog(engine), installed = await catalog.hasInstalled(name, revision), activePointer = await catalog.resolveActiveDurable(name), active = activePointer !== void 0 && activePointer.revision === revision, references = await countWorkflowRevisionReferences(engine, name, revision), removable = installed && !active && totalWorkflowRevisionReferences(references) === 0;
+  return {
+    name,
+    revision,
+    installed,
+    active,
+    ...activePointer !== void 0 ? { activeRevision: activePointer.revision } : {},
+    references,
+    removable
+  };
+}

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

@@ -32,7 +32,7 @@ export type NormalizedWorkerExecutionConfiguration = {
     discardOnCancel: true;
 };
 export declare function definitionEntries<TDefinition extends object>(definitions: Record<string, TDefinition> | undefined): Array<[string, TDefinition]>;
-export declare function typedEngineView<TViewWorkflows extends object, TViewActivities extends object>(engine: object, _phantomTypes?: readonly [TViewWorkflows, TViewActivities]): never;
+export declare function typedEngineView(engine: object): never;
 export declare function readEnvironmentVariableFromSources(name: string, sources: {
     bunEnv?: Record<string, string | undefined> | undefined;
     processEnv?: Record<string, string | undefined> | undefined;

package/dist/core/engine/construction.js

@@ -15,6 +15,7 @@ import {
   DEFAULT_WORKER_TURN_TIMEOUT_MS,
   MIN_WORKER_PROTOCOL_MESSAGE_BYTES
 } from "../worker-protocol.js";
+import { copyFinalizerMetadata } from "./finalizer-metadata.js";
 import { resolveBackgroundTaskMode, resolveOwnershipFields } from "./ownership-options.js";
 import {
   normalizeHistoryPolicy,
@@ -25,7 +26,7 @@ import {
 export function definitionEntries(definitions) {
   return Object.entries(definitions ?? {});
 }
-export function typedEngineView(engine, _phantomTypes) {
+export function typedEngineView(engine) {
   return engine;
 }
 let didWarnOnMemoryStorageFallback = !1;
@@ -76,7 +77,8 @@ export function copyWorkflowDefinition(type, registration) {
     ...registration.updates === void 0 ? {} : { updates: { ...registration.updates } },
     ...registration.queries === void 0 ? {} : { queries: { ...registration.queries } },
     ...registration.searchAttributes === void 0 ? {} : { searchAttributes: registration.searchAttributes },
-    ...registration.concurrency === void 0 ? {} : { concurrency: registration.concurrency }
+    ...registration.concurrency === void 0 ? {} : { concurrency: registration.concurrency },
+    ...copyFinalizerMetadata(registration.finalizer)
   };
 }
 function resolveRetentionFields(options) {

package/dist/core/engine/disposal.js

@@ -13,6 +13,14 @@ function clearPendingResultPollTimers(internals) {
     clearTimeout(timer);
   internals.pendingResultPollTimers.clear();
 }
+function disposeSourceResolutionState(internals) {
+  for (const controller of internals.sourceResolutionWaiterControllers)
+    controller.abort(new EngineDisposedError);
+  internals.sourceResolutionWaiterControllers.clear();
+  internals.sourceResolutionsInFlight.clear();
+  internals.workflowSourcesByName.clear();
+  internals.resolvedWorkflowSources.clear();
+}
 export function disposeEngine(internals) {
   internals.disposed = !0;
   internals.alertManager?.[Symbol.dispose]();
@@ -57,6 +65,7 @@ export function disposeEngine(internals) {
   for (const controller of internals.pendingWebhooks)
     controller.abort();
   internals.pendingWebhooks.clear();
+  disposeSourceResolutionState(internals);
   clearPendingResultPollTimers(internals);
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();

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

@@ -0,0 +1,130 @@
+/**
+ * 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';
+/**
+ * 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[]>;
+}
+/** 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,49 @@
+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";
+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)
+  };
+}

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