@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/engine/bulk-operations.js

@@ -1,15 +1,8 @@
-import {
-  KEYS,
-  requireStorageCapability,
-  storageHas
-} from "../../storage/interface.js";
+import { KEYS, storageHas } from "../../storage/interface.js";
 import { assertScopedBulkWorkflowFilter } from "../bulk-workflow-filter.js";
-import { deserializeCheckpoint } from "../checkpoint.js";
-import { decode, encode } from "../codec.js";
-import { buildTimerBatchOperations } from "../scheduler.js";
-import { buildIndexOperations } from "../search-attributes.js";
-import { buildTerminalWorkflowIndexOperations, bulkMutateWorkflowTags } from "./attributes-tags.js";
+import { bulkMutateWorkflowTags } from "./attributes-tags.js";
 import { purgeInternal, purgeWorkflow } from "./bulk-operations-purge.js";
+import { runBulkFailedWorkflowRetry } from "./bulk-operations-retry.js";
 import {
   buildActionableBulkWorkflowFilter,
   buildBulkOperationPreparation,
@@ -17,43 +10,19 @@ import {
   normalizeBulkOperationOptions,
   prepareBulkOperation,
   resolveBulkOperationConcurrency,
+  runBulkWorkflowPool,
   shouldPersistBulkAudit,
   toBulkOperationError,
   validateBulkConfirmation,
   withBulkAuditEvent
 } from "./bulk-operations-shared.js";
 import { BulkDeleteRequiresTerminalWorkflowsError } from "./errors.js";
-import {
-  assertLeaseHeldForEngineWork,
-  commitFencedEngineWriteAllowingPreconditionFailure
-} from "./fenced-write.js";
+import { assertLeaseHeldForEngineWork } from "./fenced-write.js";
 import { BULK_OPERATION_BATCH_SIZE } from "./listing.js";
-import { createTerminalCleanupTimerId } from "./state-utilities.js";
-import { loadWorkflowState, runSerializedWorkflowStateWrite } from "./storage-io.js";
-import { decodeWorkflowState, isTerminalWorkflowStatus } from "./validation.js";
-import {
-  commitWithWorkflowClaimFold,
-  prepareWorkflowClaimFold,
-  throwWorkflowClaimUnavailable
-} from "./workflow-claim-fold.js";
-import { buildWorkflowConcurrencyStartOperations } from "./workflow-concurrency.js";
-import { buildWorkflowVisibilityIndexTransition } from "./workflow-indexes.js";
+import { loadWorkflowState } from "./storage-io.js";
+import { isTerminalWorkflowStatus } from "./validation.js";
 export { purgeInternal, TERMINAL_CLEANUP_DELAY_MS } from "./bulk-operations-purge.js";
-const ACTIVE_WORKFLOW_STATUSES = ["pending", "running", "suspended"], FAILED_WORKFLOW_STATUSES = ["failed"], CHECKPOINT_RETRY_CONCURRENCY_ADMISSION_MAX_ATTEMPTS = 5;
-async function runBulkWorkflowPool(items, concurrencyLimit, operation) {
-  const results = [];
-  for (let batchStart = 0;batchStart < items.length; batchStart += concurrencyLimit) {
-    const batchItems = items.slice(batchStart, batchStart + concurrencyLimit);
-    results.push(...await Promise.all(batchItems.map(async (item) => {
-      try {
-        return { item, status: "fulfilled", value: await operation(item) };
-      } catch (reason) {
-        return { item, status: "rejected", reason };
-      }
-    })));
-  }
-  return results;
-}
+const ACTIVE_WORKFLOW_STATUSES = ["pending", "running", "suspended"];
 export async function purge(internals, filter, cleanupWaiters) {
   return purgeInternal(internals, filter, { expiredOnly: !1, now: internals.options.getNow() }, cleanupWaiters);
 }
@@ -95,138 +64,10 @@ async function runBulkCancellation(internals, filter, options = {}) {
 export async function cancelAll(internals, filter, options = {}) {
   return runBulkCancellation(internals, filter, options);
 }
-async function runBulkFailedWorkflowRetry(internals, filter, options = {}) {
-  options = normalizeBulkOperationOptions(options);
-  assertScopedBulkWorkflowFilter(filter);
-  const actionableFilter = buildActionableBulkWorkflowFilter(internals, filter, FAILED_WORKFLOW_STATUSES), preparation = await prepareBulkOperation(internals, "retry-failed", actionableFilter, filter, {}, options);
-  if (options.dryRun === !0)
-    return preparation.preview;
-  validateBulkConfirmation(options, preparation);
-  const bulkConcurrency = resolveBulkOperationConcurrency(options);
-  let retried = 0;
-  const errors = [], retryResults = await runBulkWorkflowPool(preparation.workflowIds, bulkConcurrency, async (workflowId) => {
-    await retryFailedWorkflow(internals, workflowId);
-    return { status: "retried" };
-  });
-  for (const retryResult of retryResults) {
-    if (retryResult.status === "rejected") {
-      errors.push(toBulkOperationError(internals, retryResult.item, retryResult.reason));
-      continue;
-    }
-    retried += 1;
-  }
-  const result = { retried, failed: errors.length, errors };
-  if (!shouldPersistBulkAudit(options))
-    return result;
-  return withBulkAuditEvent(internals, preparation, options, result, retried);
-}
 export async function retryFailedAll(internals, filter, options = {}) {
   assertLeaseHeldForEngineWork(internals);
   return runBulkFailedWorkflowRetry(internals, filter, options);
 }
-async function retryFailedWorkflow(internals, workflowId) {
-  const state = await loadWorkflowState(internals, workflowId);
-  if (state === null)
-    throw Error("Workflow no longer exists");
-  if (state.status !== "failed")
-    throw Error(`Workflow is ${state.status}, not failed`);
-  if (await internals.storage.get(KEYS.checkpoint(workflowId)) !== null) {
-    await reactivateFailedWorkflowFromCheckpoint(internals, state);
-    await internals.engine.resume(workflowId);
-    return;
-  }
-  await internals.engine.start(state.type, state.input, {
-    id: workflowId,
-    onTerminalConflict: "start-new",
-    ...state.tags !== void 0 ? { tags: state.tags } : {}
-  });
-}
-async function reactivateFailedWorkflowFromCheckpoint(internals, state) {
-  const reactivated = await runSerializedWorkflowStateWrite(internals, state.id, async () => reactivateFailedWorkflowFromCheckpointSerialized(internals, state.id));
-  if (reactivated.terminalCleanupTimerId !== void 0)
-    await internals.scheduler.cancel(reactivated.terminalCleanupTimerId, state.id);
-}
-async function reactivateFailedWorkflowFromCheckpointSerialized(internals, workflowId) {
-  let lastConcurrencyStateKey;
-  for (let attempt = 0;attempt < CHECKPOINT_RETRY_CONCURRENCY_ADMISSION_MAX_ATTEMPTS; attempt += 1) {
-    const currentStateBytes = await internals.storage.get(KEYS.workflow(workflowId));
-    if (currentStateBytes === null)
-      throw Error("Workflow no longer exists");
-    const currentState = decodeWorkflowState(currentStateBytes);
-    if (currentState.status !== "failed")
-      throw Error(`Workflow is ${currentState.status}, not failed`);
-    const currentCheckpointBytes = await internals.storage.get(KEYS.checkpoint(workflowId));
-    if (currentCheckpointBytes === null)
-      throw Error("Checkpoint no longer exists");
-    const checkpoint = deserializeCheckpoint(currentCheckpointBytes), registration = internals.registrations.get(currentState.type);
-    if (registration === void 0)
-      throw Error(`No workflow registered with name "${currentState.type}" (needed to retry "${workflowId}")`);
-    const concurrencyStartOperations = registration.concurrency === void 0 ? void 0 : await buildWorkflowConcurrencyStartOperations(internals, currentState.type, workflowId, currentState.input, registration.concurrency);
-    lastConcurrencyStateKey = concurrencyStartOperations?.stateKey ?? lastConcurrencyStateKey;
-    const reactivatedState = buildReactivatedWorkflowState(internals, currentState), currentAttributes = await loadSearchAttributes(internals, workflowId), operations = [
-      ...buildTerminalWorkflowIndexOperations(currentState, reactivatedState),
-      { type: "put", key: KEYS.workflow(workflowId), value: encode(reactivatedState) },
-      ...buildWorkflowVisibilityIndexTransition(workflowId, currentState, reactivatedState).batchOps,
-      ...buildRetrySearchAttributeOperations(workflowId, currentAttributes, checkpoint.searchAttributes),
-      ...reactivatedState.executionDeadline === void 0 ? [] : buildTimerBatchOperations({
-        id: `deadline:${workflowId}`,
-        workflowId,
-        fireAt: reactivatedState.executionDeadline,
-        kind: "execution-deadline"
-      }),
-      ...concurrencyStartOperations?.operations ?? []
-    ], conditions = concurrencyStartOperations?.conditions ?? [];
-    if (await commitFailedWorkflowReactivation(internals, workflowId, operations, conditions))
-      return {
-        terminalCleanupTimerId: currentState.terminalCleanupToken === void 0 ? void 0 : createTerminalCleanupTimerId(!1, currentState.terminalCleanupToken)
-      };
-  }
-  throw Error(`Workflow concurrency admission for "${lastConcurrencyStateKey ?? workflowId}" changed too many times while retrying failed workflow "${workflowId}"`);
-}
-async function commitFailedWorkflowReactivation(internals, workflowId, operations, conditions) {
-  const claimFold = await prepareWorkflowClaimFold(internals, workflowId);
-  if (claimFold === void 0) {
-    if (conditions.length > 0)
-      requireStorageCapability(internals.storage, "conditionalBatch", "retry failed workflow");
-    return commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, operations, conditions);
-  }
-  const result = await commitWithWorkflowClaimFold(internals, claimFold, operations, conditions, "retry failed workflow claim acquisition");
-  if (result.status === "committed")
-    return !0;
-  return result.claimConflict ? throwWorkflowClaimUnavailable(internals, workflowId) : !1;
-}
-function buildReactivatedWorkflowState(internals, state) {
-  const reactivatedState = {
-    ...state,
-    status: "running",
-    updatedAt: internals.options.getNow()
-  };
-  delete reactivatedState.error;
-  delete reactivatedState.errorStack;
-  delete reactivatedState.failureCategory;
-  delete reactivatedState.result;
-  delete reactivatedState.terminationReason;
-  delete reactivatedState.terminalCleanupToken;
-  return reactivatedState;
-}
-async function loadSearchAttributes(internals, workflowId) {
-  const attributeBytes = await internals.storage.get(KEYS.attribute(workflowId));
-  if (attributeBytes === null)
-    return {};
-  return decode(attributeBytes);
-}
-function buildRetrySearchAttributeOperations(workflowId, currentAttributes, checkpointAttributes) {
-  const operations = buildIndexOperations(workflowId, currentAttributes, checkpointAttributes);
-  if (Object.keys(checkpointAttributes).length === 0)
-    operations.push({ type: "delete", key: KEYS.attribute(workflowId) });
-  else
-    operations.push({
-      type: "put",
-      key: KEYS.attribute(workflowId),
-      value: encode(checkpointAttributes)
-    });
-  return operations;
-}
 export async function signalAll(internals, filter, name, payload, maybeOptions) {
   const options = normalizeBulkOperationOptions(maybeOptions ?? {});
   assertScopedBulkWorkflowFilter(filter);

package/dist/core/engine/callback-creators-bundles.js

@@ -16,6 +16,7 @@ import {
   createReviewOperationCallbacks,
   handleScheduleTimerForEngine
 } from "./callback-creators-schedule.js";
+import { resolveExecutableRegistrationForRevision } from "./dynamic-source-execution.js";
 import { commitFencedEngineWrite } from "./fenced-write.js";
 import { guardTerminalWorkflow, guardTerminalWorkflowAfterCoordinatedRequest } from "./guards.js";
 import { getInternals } from "./internals.js";
@@ -122,7 +123,7 @@ export function createTimeOperationCallbacks(engine) {
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     failWorkflow: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine)),
     runSerializedWorkflowStateWrite: (workflowId, writeOperation) => runSerializedWorkflowStateWrite(getInternals(engine), workflowId, writeOperation),
-    beginWorkflowExecution: (workflowId, workflowExecutionToken, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration) => beginWorkflowExecution(getInternals(engine), workflowId, workflowExecutionToken, workflowType, input, checkpoint, executionDeadline, executionStateOwnerId, registration, createLifecycleCallbacks(engine)),
+    beginWorkflowExecution: (workflowId, workflowExecutionToken, workflowType, revision, input, checkpoint, executionDeadline, executionStateOwnerId, registration) => beginWorkflowExecution(getInternals(engine), workflowId, workflowExecutionToken, workflowType, revision, input, checkpoint, executionDeadline, executionStateOwnerId, registration, createLifecycleCallbacks(engine)),
     workflowVersionTupleFromState: (state) => workflowVersionTupleFromState(getInternals(engine), state, createLifecycleCallbacks(engine)),
     setWorkflowStartHeaders: (workflowId, headers) => setWorkflowStartHeaders(getInternals(engine), workflowId, headers, createLifecycleCallbacks(engine)),
     loadWorkflowStartHeaders: (workflowId) => loadWorkflowStartHeaders(getInternals(engine), workflowId, createLifecycleCallbacks(engine)),
@@ -131,7 +132,8 @@ export function createTimeOperationCallbacks(engine) {
     runWorkflowFinalizer: (workflowId, timerId) => runWorkflowFinalizer(getInternals(engine), workflowId, timerId, createTerminationCallbacks(engine)),
     handleScheduleTimer: (entry) => handleScheduleTimerForEngine(engine, entry),
     timeout: (workflowId) => engine.timeout(workflowId),
-    handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId)
+    handleCleanupError: (source, error, workflowId) => createTerminationCallbacks(engine).handleCleanupError(source, error, workflowId),
+    resolveExecutableRegistrationForRevision: (type, revision) => resolveExecutableRegistrationForRevision(engine, getInternals(engine), type, revision)
   };
 }
 export function createUpdateCallbacks(engine) {

package/dist/core/engine/callback-creators-core.js

@@ -3,6 +3,10 @@ import {
   broadcast as broadcastFromInternals,
   forwardEventToHandle as forwardEventToHandleFromBroadcast
 } from "./broadcast.js";
+import {
+  resolveExecutableRegistration,
+  resolveExecutableRegistrationForRevision
+} from "./dynamic-source-execution.js";
 import { createWorkflowHandleWithResultPromise } from "./handle-result.js";
 import {
   hasLocalCheckpointOwnership,
@@ -79,7 +83,11 @@ export function createLifecycleCallbacks(engine) {
     failWorkflowForUnavailableServices: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
     failWorkflowForRecoveryHook: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
     failWorkflowForCheckpointDecodeError: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
-    failWorkflowForVersionMismatch: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
+    failWorkflowForVersionMismatch: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
+    resolveExecutableRegistration: (type, onRevisionChosen) => resolveExecutableRegistration(engine, getInternals(engine), type, onRevisionChosen),
+    failWorkflowForUnavailableDynamicSource: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system"),
+    resolveExecutableRegistrationForRevision: (type, revision) => resolveExecutableRegistrationForRevision(engine, getInternals(engine), type, revision),
+    failWorkflowForRevisionUnavailable: (workflowId, error) => failWorkflow(getInternals(engine), workflowId, error, createTerminationCallbacks(engine), "system")
   };
 }
 export function createTerminationCallbacksWith(engine, handleScheduledWorkflowTerminal) {

package/dist/core/engine/callback-creators-schedule.js

@@ -20,8 +20,8 @@ import { feedOperationResult } from "./strategy-helpers.js";
 import { ensureTerminalCleanupTracked, failWorkflow, handleCleanupError } from "./termination.js";
 export function createScheduleCallbacks(engine) {
   return {
-    startWorkflow: async (type, input, options, additionalStartOperations) => {
-      await startWorkflow(getInternals(engine), type, input, options, additionalStartOperations, createLifecycleCallbacks(engine));
+    startWorkflow: async (type, input, options, additionalStartOperations, revisionOverride) => {
+      await startWorkflow(getInternals(engine), type, input, options, additionalStartOperations, createLifecycleCallbacks(engine), void 0, revisionOverride);
     },
     loadWorkflowState: (workflowId) => loadWorkflowState(getInternals(engine), workflowId),
     cancelWorkflow: (workflowId) => engine.cancel(workflowId),

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

@@ -0,0 +1,40 @@
+/**
+ * `activateCatalogRevisionCandidate` — a thin engine-level wrapper around
+ * `WorkflowCatalog.activateCandidate()`, the guarded activation primitive
+ * (WFT-9/WFT-10). Awaits catalog readiness, reads pre-activation state,
+ * calls the guarded primitive, dispatches the correct catalog event(s), and
+ * returns the primitive's own structured result verbatim:
+ * the shared installed/activated/draining helper on success, or
+ * `WorkflowRevisionActivationRejectedEvent` directly on refusal.
+ *
+ * `engine.workflows.activate()` (WFT-11,
+ * `core/engine/engine-workflows-namespace.ts`) is this wrapper's production
+ * caller — the only practical way an external caller reaches the guarded
+ * candidate-activation primitive, so routing it through here (rather than
+ * calling `WorkflowCatalog.activateCandidate()` directly) is what makes a
+ * manual activation dispatch `catalog:revision-installed`/
+ * `catalog:revision-activated`/`catalog:revision-draining`/
+ * `catalog:activation-rejected` the same way `engine.register()`'s
+ * drain path already does.
+ *
+ * Never imports `./index.ts` as a value (only as a type, matching
+ * `catalog-readiness.ts`'s own import-cycle discipline for itself) — the
+ * `Engine` class import here is `import type`, erased at build time.
+ *
+ * @module core/engine/catalog-activation
+ */
+import type { ActivateCandidateOptions, WorkflowCatalogActivationResult } from '../catalog/index.ts';
+import type { WorkflowRevisionManifest } from '../contract/types.ts';
+import type { Engine } from './index.ts';
+/**
+ * Activate `candidateManifest` for `name` through the catalog's guarded
+ * primitive (`checkWorkflowCompatibility`-gated, single-shot CAS), and
+ * return its structured result verbatim. On success, dispatches
+ * `catalog:revision-installed` (when genuinely new content),
+ * `catalog:revision-draining` (when displacing a prior active revision),
+ * and `catalog:revision-activated`. On refusal, dispatches
+ * `catalog:activation-rejected` carrying only the bounded `reason` code
+ * (and, for `'incompatible'`, the bounded `incompatibilityReasons` array) —
+ * never the full `WorkflowCompatibilityVerdict` object.
+ */
+export declare function activateCatalogRevisionCandidate(engine: Engine, name: string, candidateManifest: WorkflowRevisionManifest, options?: ActivateCandidateOptions): Promise<WorkflowCatalogActivationResult>;

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

@@ -0,0 +1,17 @@
+import { WorkflowRevisionActivationRejectedEvent } from "../events/catalog-events.js";
+import { dispatchCatalogInstallAndActivatedEvents } from "./catalog-events.js";
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+export async function activateCatalogRevisionCandidate(engine, name, candidateManifest, options) {
+  await ensureWorkflowCatalogReady(engine);
+  const catalog = getWorkflowCatalog(engine), preExisting = await catalog.hasInstalled(name, candidateManifest.revision), pointerBefore = await catalog.resolveActiveDurable(name) ?? null, result = await catalog.activateCandidate(name, candidateManifest, options);
+  if (result.applied) {
+    dispatchCatalogInstallAndActivatedEvents(engine, name, candidateManifest.revision, preExisting, pointerBefore, result.pointer);
+    return result;
+  }
+  if (result.reason === "incompatible") {
+    engine.dispatchEvent(new WorkflowRevisionActivationRejectedEvent(name, candidateManifest.revision, result.reason, result.verdict.compatible ? void 0 : result.verdict.reasons));
+    return result;
+  }
+  engine.dispatchEvent(new WorkflowRevisionActivationRejectedEvent(name, candidateManifest.revision, result.reason));
+  return result;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Shared installed/activated/draining event-dispatch helper (WFT-12), used
+ * by BOTH producers of catalog activation: `catalog-readiness.ts`'s
+ * `drainPendingCatalogInstalls` (the `engine.register()`-drain path) and
+ * `catalog-activation.ts`'s `activateCatalogRevisionCandidate` (the guarded
+ * primitive). The two producers return different result shapes
+ * (`activateRegistered` always succeeds and returns a bare pointer;
+ * `activateCandidate` returns a union that can also refuse) — this helper
+ * takes already-normalized before/after pointer values instead of either
+ * raw return type, so it stays agnostic to which producer called it.
+ * `activation-rejected` is NOT dispatched here — only `activateCandidate`
+ * can refuse, so its one caller dispatches that event itself.
+ *
+ * @module core/engine/catalog-events
+ */
+import type { WorkflowCatalogActivePointer } from '../catalog/index.ts';
+import type { Engine } from './index.ts';
+/**
+ * Dispatch `catalog:revision-installed` (only when `preExisting` is
+ * `false` — genuinely new content, not a byte-identical reinstall or a
+ * cross-process durable adoption of already-present content), then decide
+ * activated/draining from how `pointerBefore` and `pointerAfter` compare:
+ *
+ * - Identical `revision` AND `generation` (a true no-op — nothing was
+ *   durably written, e.g. `activateRegistered`'s own no-op branch): neither
+ *   fires.
+ * - Same `revision`, different `generation` (a reactivation that still
+ *   bumped the fencing counter, e.g. `activateCandidate` re-activating the
+ *   currently active revision): `catalog:revision-activated` fires with
+ *   `previousRevision: undefined` — nothing was actually displaced, so
+ *   there is nothing to drain.
+ * - Different `revision`: `catalog:revision-draining` for `pointerBefore`
+ *   (when it existed) followed by `catalog:revision-activated` for
+ *   `pointerAfter`, `previousRevision` set to the displaced revision.
+ */
+export declare function dispatchCatalogInstallAndActivatedEvents(engine: Engine, name: string, revision: string, preExisting: boolean, pointerBefore: WorkflowCatalogActivePointer | null, pointerAfter: WorkflowCatalogActivePointer): void;

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

@@ -0,0 +1,15 @@
+import {
+  WorkflowRevisionActivatedEvent,
+  WorkflowRevisionDrainingEvent,
+  WorkflowRevisionInstalledEvent
+} from "../events/catalog-events.js";
+export function dispatchCatalogInstallAndActivatedEvents(engine, name, revision, preExisting, pointerBefore, pointerAfter) {
+  if (!preExisting)
+    engine.dispatchEvent(new WorkflowRevisionInstalledEvent(name, revision));
+  if (pointerBefore !== null && pointerBefore.revision === pointerAfter.revision && pointerBefore.generation === pointerAfter.generation)
+    return;
+  const previousRevision = pointerBefore !== null && pointerBefore.revision !== pointerAfter.revision ? pointerBefore.revision : void 0;
+  if (previousRevision !== void 0)
+    engine.dispatchEvent(new WorkflowRevisionDrainingEvent(name, previousRevision));
+  engine.dispatchEvent(new WorkflowRevisionActivatedEvent(name, pointerAfter.revision, pointerAfter.generation, previousRevision));
+}

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,61 @@
+import { restoreWorkflowCatalog, WorkflowCatalog } from "../catalog/index.js";
+import { buildWorkflowManifestForType } from "../registry-workflow-manifest.js";
+import { dispatchCatalogInstallAndActivatedEvents } from "./catalog-events.js";
+import { resolveOrphanedCatalogTombstones } from "./catalog-tombstone-recovery.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) {
+      await resolveOrphanedCatalogTombstones(internals.storage);
+      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;
+  }
+}