@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -0,0 +1,236 @@
+/**
+ * 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';
+type RegistrationEntry = EngineInternals['registrations'] extends Map<string, infer Entry> ? Entry : never;
+/**
+ * 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.
+ *
+ * `revisionOverride` (WFT-15/16) is the revision `resolveExecutableRegistration()`
+ * already resolved for a `registerSource()`-registered `type` — passed
+ * through instead of re-deriving via `catalog.resolveActive(type)`, which
+ * would read `undefined` for a dynamic source with no catalog active
+ * pointer set (a source can resolve and install without ever being
+ * `engine.workflows.activate()`-d), making `inFlightStarts` diagnostics
+ * silently miss a lazy run in flight. `undefined` (the default) preserves
+ * the eager-path behavior byte-for-byte.
+ */
+export declare function reserveInFlightStart(internals: EngineInternals, type: string, revisionOverride?: string): string | undefined;
+/**
+ * `startWorkflow`'s combined "resolve `type`, reserve an `inFlightStarts`
+ * slot for the resolved revision" step. Reserves EARLY — before the loader
+ * is awaited, via `resolve()`'s `onRevisionChosen` hook — for a lazy type,
+ * closing the window where a concurrent `removeWorkflowRevision()` could
+ * observe zero references against a revision this call's own source load
+ * is about to durably (re)install; reserves afterward for an eager type,
+ * exactly as before WFT-15/16 (that path never invokes the hook). If the
+ * loader then fails — `resolve()` rejects AFTER the hook already fired — the
+ * early reservation is released here before rethrowing: `startWorkflow`
+ * only assigns its own `inFlightRevision` on a successful return, so its
+ * `finally` releases nothing on this path and the increment would otherwise
+ * leak forever, permanently reporting the revision non-`removable`.
+ *
+ * `resolvedRevision` is the raw value `resolve()` itself returned —
+ * `undefined` for an eager registration, the resolved candidate for a
+ * dynamic source — distinct from `inFlightRevision`, which for an eager
+ * type falls back to the catalog's cached ACTIVE pointer (see
+ * {@link reserveInFlightStart}). A caller that needs "the exact revision of
+ * the code this process is about to run" (WFT-17's `WorkflowState.revision`)
+ * must use `resolvedRevision`, not `inFlightRevision` — the two intentionally
+ * diverge for an eager type under a multi-engine deployment where this
+ * process's own registration lags the durable active pointer.
+ */
+export declare function resolveAndReserveExecutableRegistration(internals: EngineInternals, type: string, resolve: (type: string, onRevisionChosen?: (revision: string) => void) => Promise<{
+    entry: RegistrationEntry;
+    revision: string | undefined;
+}>): Promise<{
+    registration: RegistrationEntry;
+    inFlightRevision: string | undefined;
+    resolvedRevision: 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 in-memory, constant-time lookups; `nonTerminalRuns` (WFT-17 — see
+ * {@link countNonTerminalRunsForRevision}) is an UNBOUNDED, full `wf:`-prefix
+ * durable scan — the same shape `groupActiveWorkflowsByType` already uses
+ * elsewhere for this class of diagnostic, so it's consistent with how this
+ * codebase already pays for this, but it is O(n) in the total number of
+ * workflow records, not bounded by `(name, revision)`. `removeWorkflowRevision()`
+ * calls this TWICE per removal attempt (its own pre-check, and
+ * {@link finalizeRevisionRemoval}'s post-check) — worth knowing before
+ * wiring `removeWorkflowRevision()` into an automated cleanup path on a
+ * large durable store, rather than the operator-triggered use this batch
+ * assumes. `pinnedSchedules` is ALSO an unbounded, full `schedule:`-prefix
+ * durable scan (WFT-20 — see {@link countPinnedSchedulesForRevision}), so
+ * this function now pays for two bounded-but-unbounded-in-store-size scans
+ * per call. The remaining two fields of {@link WorkflowRevisionReferenceCounts}
+ * stay `0` — the dispatch ledger and execution realms are out of this
+ * batch's scope.
+ */
+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.
+ *
+ * Checks references BOTH before and after the durable delete (WFT-17,
+ * Codex review on PR #958). The pre-check above is an OPTIMIZATION — it
+ * refuses upfront in the common case, avoiding a needless delete-then-restore
+ * round trip — but is not, on its own, the guarantee: a concurrent
+ * `engine.start()` on a DIFFERENT process could read the entry as still
+ * installed, and commit a NEW run pinned to `revision`, in the narrow
+ * window between this function's pre-check scan and its own delete CAS
+ * landing; the pre-check's zero-references snapshot would then be stale
+ * by the time the delete actually commits. The POST-check closes this: it
+ * is safe to trust because `start-commit.ts`'s own start batch fences on
+ * this exact catalog entry's bytes (`buildCatalogEntryStartPrecondition`)
+ * — `conditionalBatch`'s precondition is evaluated against LIVE storage
+ * state at commit time, so ANY start whose commit lands after this
+ * function's delete necessarily loses its own CAS and never creates the
+ * reference at all. A nonzero post-delete count can therefore only be a
+ * run that committed BEFORE the delete — this function restores the entry
+ * and reports `'referenced'` rather than leaving a real, still-referenced
+ * run pinned to a revision the catalog no longer carries.
+ *
+ * `catalog.remove()`'s delete and `finalizeRevisionRemoval`'s restore-or-
+ * finalize used to be two SEPARATE commits (WFT-17/18, Codex review on PR
+ * #958): a process crash between them left the revision durably uninstalled
+ * with NO durable record of what was deleted, recoverable by no one. Both
+ * halves of `removeCatalogEntry` (the delete) now land in ONE
+ * `conditionalBatch` with a `catalog-tombstone:<name>:<revision>` record
+ * (the exact deleted bytes) — see `core/catalog/removal.ts`'s module doc —
+ * so this function's own restore-or-finalize below is itself a SECOND
+ * atomic operation (not a bare `install()`/no-op), and a crash between the
+ * two commits leaves a durable tombstone ANY process can resolve, not just
+ * this one. `catalog-tombstone-recovery.ts`'s boot-time sweep and this
+ * function's own targeted pre-check (below) both close that residual
+ * window; see that module's doc for the full mechanism.
+ *
+ * @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;
+    /**
+     * Dynamic-source load diagnostics (WFT-15/16), present only when `name`
+     * has an entry in `internals.sources.byName` — i.e. `name` has ever been
+     * `registerSource()`-registered on this engine. `undefined` for a purely
+     * eager name, or a dynamic source this process has never heard of.
+     */
+    source?: {
+        kind: import('../source/index.ts').WorkflowSourceKind;
+        requestedRevision: string;
+        state: import('./source-runtime-state.ts').SourceLoadState;
+        loadDurationMs?: number;
+        lastFailureCategory?: import('../types/identity.ts').FailureCategory;
+        waiterCount: number;
+    };
+}>;
+/**
+ * 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>;
+export {};

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

@@ -0,0 +1,123 @@
+import {
+  decrementNestedRevisionCount,
+  finalizeCatalogTombstone,
+  incrementNestedRevisionCount,
+  readNestedRevisionCount,
+  restoreCatalogEntryFromTombstone,
+  totalWorkflowRevisionReferences
+} from "../catalog/index.js";
+import { WorkflowRevisionRemovedEvent } from "../events/catalog-events.js";
+import { ensureWorkflowCatalogReady, getWorkflowCatalog } from "./catalog-readiness.js";
+import { resolveCatalogTombstoneIfPresent } from "./catalog-tombstone-recovery.js";
+import { getInternals } from "./internals.js";
+import { countNonTerminalRunsForRevision } from "./nonterminal-revision-count.js";
+import { countPinnedSchedulesForRevision } from "./pinned-schedule-revision-count.js";
+import { readSourceLoadDiagnostics, readSourceWaiterCount } from "./source-diagnostics.js";
+export function reserveInFlightStart(internals, type, revisionOverride) {
+  const revision = revisionOverride ?? internals.workflowCatalog?.resolveActive(type)?.revision;
+  if (revision !== void 0)
+    incrementNestedRevisionCount(internals.inFlightStartsByRevision, type, revision);
+  return revision;
+}
+export async function resolveAndReserveExecutableRegistration(internals, type, resolve) {
+  let earlyReservation;
+  try {
+    const { entry: registration, revision } = await resolve(type, (chosen) => {
+      earlyReservation = reserveInFlightStart(internals, type, chosen);
+    }), inFlightRevision = earlyReservation !== void 0 ? earlyReservation : reserveInFlightStart(internals, type, revision);
+    return { registration, inFlightRevision, resolvedRevision: revision };
+  } catch (error) {
+    releaseInFlightStart(internals, type, earlyReservation);
+    throw error;
+  }
+}
+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), nonTerminalRuns = await countNonTerminalRunsForRevision(internals.storage, name, revision), pinnedSchedules = await countPinnedSchedulesForRevision(internals.storage, name, revision);
+  return {
+    registeredDefinitions: internals.registeredCatalogRevisions.get(name) === revision ? 1 : 0,
+    inFlightStarts: readNestedRevisionCount(internals.inFlightStartsByRevision, name, revision),
+    nonTerminalRuns,
+    pinnedSchedules,
+    pendingDispatches: 0,
+    activeExecutionRealms: 0,
+    retainedRecoveryRecords: 0
+  };
+}
+export async function removeWorkflowRevision(engine, name, revision) {
+  await ensureWorkflowCatalogReady(engine);
+  const catalog = getWorkflowCatalog(engine), internals = getInternals(engine);
+  await resolveCatalogTombstoneIfPresent(internals.storage, name, revision);
+  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 preReferences = await countWorkflowRevisionReferences(engine, name, revision);
+  if (totalWorkflowRevisionReferences(preReferences) > 0)
+    return { removed: !1, reason: "referenced", references: preReferences };
+  const result = await catalog.remove(name, revision);
+  switch (result.outcome) {
+    case "removed":
+      return finalizeRevisionRemoval(engine, name, revision, result.tombstoneBytes);
+    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)}`);
+  }
+}
+async function finalizeRevisionRemoval(engine, name, revision, tombstoneBytes) {
+  const internals = getInternals(engine), postReferences = await countWorkflowRevisionReferences(engine, name, revision);
+  if (totalWorkflowRevisionReferences(postReferences) > 0) {
+    await restoreCatalogEntryFromTombstone(internals.storage, name, revision, tombstoneBytes);
+    return { removed: !1, reason: "referenced", references: postReferences };
+  }
+  await finalizeCatalogTombstone(internals.storage, name, revision, tombstoneBytes);
+  engine.dispatchEvent(new WorkflowRevisionRemovedEvent(name, revision));
+  return { removed: !0 };
+}
+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, source = buildSourceDiagnostics(getInternals(engine), name, revision);
+  return {
+    name,
+    revision,
+    installed,
+    active,
+    ...activePointer !== void 0 ? { activeRevision: activePointer.revision } : {},
+    references,
+    removable,
+    ...source !== void 0 ? { source } : {}
+  };
+}
+function resolveDiagnosticsSourceKind(diagnostics, registeredRevisions, revision) {
+  if (diagnostics !== void 0)
+    return diagnostics.kind;
+  const registered = registeredRevisions.get(revision);
+  return registered === void 0 ? "module" : registered.descriptor.kind;
+}
+function buildSourceDiagnostics(internals, name, revision) {
+  const registeredRevisions = internals.sources.byName.get(name);
+  if (registeredRevisions === void 0)
+    return;
+  const diagnostics = readSourceLoadDiagnostics(internals, name, revision);
+  return {
+    kind: resolveDiagnosticsSourceKind(diagnostics, registeredRevisions, revision),
+    requestedRevision: revision,
+    state: diagnostics === void 0 ? "idle" : diagnostics.state,
+    ...diagnostics?.loadDurationMs !== void 0 && {
+      loadDurationMs: diagnostics.loadDurationMs
+    },
+    ...diagnostics?.lastFailureCategory !== void 0 && {
+      lastFailureCategory: diagnostics.lastFailureCategory
+    },
+    waiterCount: readSourceWaiterCount(internals, name, revision)
+  };
+}

package/dist/core/engine/catalog-tombstone-recovery.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolves durable `catalog-tombstone:<name>:<revision>` records left
+ * behind by {@link import('../catalog/removal.ts').removeCatalogEntry}
+ * (WFT-17/18, Codex review on PR #958) — a tombstone exists only in the
+ * brief window between its delete-and-tombstone commit and the SAME call's
+ * own resolution (restore or finalize), normally sub-millisecond. A
+ * tombstone that outlives that window is an ORPHAN: the process that
+ * created it crashed (or otherwise failed) before resolving it. This
+ * module makes that recoverable by ANY process, not just the one that
+ * crashed — the exact gap the tombstone design closes (see
+ * `core/catalog/removal.ts`'s module doc for the full mechanism).
+ *
+ * Deliberately lives in `core/engine/`, not alongside the tombstone
+ * primitives in `core/catalog/`: resolving an orphan needs a FRESH
+ * reference count, and the only reference signal meaningful for a
+ * crashed peer's tombstone is the durable one —
+ * `nonterminal-revision-count.ts`'s `wf:`-prefix scan (in-process signals
+ * like `registeredDefinitions`/`inFlightStarts` are per-engine-instance and
+ * say nothing about what a DIFFERENT, crashed process was doing).
+ * `core/catalog/**` never imports from `core/engine/**` — a directional
+ * boundary `check-import-cycles.ts` enforces — so this orchestration has to
+ * live on the engine side of that line.
+ *
+ * Two call sites: `catalog-readiness.ts`'s boot-time sweep (every
+ * orphaned tombstone in the whole store, run once per engine instance
+ * before recovery or any new start can observe stale state) and
+ * `catalog-removal.ts`'s `removeWorkflowRevision` (a single, targeted
+ * check for the EXACT `(name, revision)` key it is about to act on, since
+ * a long-lived engine could observe a peer crash mid-lifetime, after its
+ * own boot sweep already ran).
+ *
+ * @module core/engine/catalog-tombstone-recovery
+ */
+import { type Storage } from '../../storage/interface.ts';
+/**
+ * Sweep every `catalog-tombstone:` record in `storage` and resolve each
+ * one. Bounded by the number of orphaned tombstones actually present —
+ * normally zero, so this is a cheap prefix scan that yields nothing to
+ * iterate; only non-trivial after a real crash left orphans behind. Called
+ * once per engine instance, at catalog-boot time
+ * (`catalog-readiness.ts`), before recovery's own preflight or any fresh
+ * start can observe a revision this sweep would otherwise still be
+ * resolving.
+ */
+export declare function resolveOrphanedCatalogTombstones(storage: Storage): Promise<void>;
+/**
+ * Targeted check for ONE `(name, revision)` tombstone — used by
+ * `removeWorkflowRevision` immediately before it acts, so a peer crash
+ * that happened after this engine's own boot-time sweep already ran (a
+ * long-lived engine) does not leave a stale tombstone permanently blocking
+ * every future removal attempt on that exact key (`removeCatalogEntry`'s
+ * own CAS requires the tombstone key absent). A no-op when no tombstone is
+ * present for this exact key — the overwhelmingly common case, costing one
+ * `storage.get`.
+ */
+export declare function resolveCatalogTombstoneIfPresent(storage: Storage, name: string, revision: string): Promise<void>;

package/dist/core/engine/catalog-tombstone-recovery.js

@@ -0,0 +1,39 @@
+import { KEYS } from "../../storage/interface.js";
+import { tryDecodeStorageKeyComponent } from "../../storage/key-encoding.js";
+import {
+  decodeCatalogEntryRecord,
+  finalizeCatalogTombstone,
+  restoreCatalogEntryFromTombstone
+} from "../catalog/index.js";
+import { countNonTerminalRunsForRevision } from "./nonterminal-revision-count.js";
+function splitCatalogTombstoneKey(key) {
+  const parts = key.split(":");
+  if (parts.length !== 3)
+    return null;
+  const name = tryDecodeStorageKeyComponent(parts[1] ?? ""), revision = tryDecodeStorageKeyComponent(parts[2] ?? "");
+  if (name === null || revision === null)
+    return null;
+  return { name, revision };
+}
+async function resolveCatalogTombstone(storage, name, revision, tombstoneBytes) {
+  if (await countNonTerminalRunsForRevision(storage, name, revision) > 0)
+    await restoreCatalogEntryFromTombstone(storage, name, revision, tombstoneBytes);
+  else
+    await finalizeCatalogTombstone(storage, name, revision, tombstoneBytes);
+}
+export async function resolveOrphanedCatalogTombstones(storage) {
+  for await (const [key, bytes] of storage.scan(KEYS.catalogTombstonePrefix())) {
+    const split = splitCatalogTombstoneKey(key);
+    if (split === null)
+      throw Error(`The store's catalog tombstone key ("${key}") does not match the expected catalog-tombstone:<name>:<revision> shape. Treating it as absent would risk silently abandoning an in-flight catalog removal, so this fails closed instead. Resolve by operator repair: inspect the stored bytes and, only if certain no removal is actually in flight, delete the key.`);
+    await decodeCatalogEntryRecord(key, bytes, split.name, split.revision);
+    await resolveCatalogTombstone(storage, split.name, split.revision, bytes);
+  }
+}
+export async function resolveCatalogTombstoneIfPresent(storage, name, revision) {
+  const tombstoneKey = KEYS.catalogTombstone(name, revision), tombstoneBytes = await storage.get(tombstoneKey);
+  if (tombstoneBytes === null)
+    return;
+  await decodeCatalogEntryRecord(tombstoneKey, tombstoneBytes, name, revision);
+  await resolveCatalogTombstone(storage, name, revision, tombstoneBytes);
+}

package/dist/core/engine/constraints.js

@@ -1,9 +1,13 @@
 import { ConstraintViolatedEvent } from "../events.js";
+import { getResolvedDynamicRegistration } from "./dynamic-source-execution.js";
+function resolveRunningInstanceRevision(internals, workflowId) {
+  return internals.workflowTypeByWorkflowId.get(workflowId)?.revision;
+}
 export async function evaluateConstraints(internals, workflowId, callbacks) {
   const context = internals.inlineStrategy?.getContext(workflowId);
   if (!context)
     return !1;
-  const constraints = internals.registrations.get(context.workflowType)?.constraints;
+  const revision = resolveRunningInstanceRevision(internals, workflowId), constraints = getResolvedDynamicRegistration(internals, context.workflowType, revision)?.constraints;
   if (!constraints || constraints.length === 0)
     return !1;
   const stateSnapshot = {

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;
@@ -50,7 +50,7 @@ export declare function createExecutionStrategyBundle(parameters: {
     maxNestingDepth: number;
     development: boolean;
     broadcastEvents: boolean;
-    getRegistration: (workflowType: string) => RegistrationEntry | undefined;
+    getRegistration: (workflowType: string, workflowId: string) => RegistrationEntry | undefined;
     /** Live accessor for registered workflow type names (WFT-28); registrations are still empty here. */
     listRegisteredWorkflowTypes: () => Iterable<string>;
     getComposedWorkflowInterceptor?: () => ComposedWorkflowInterceptor | null;

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/decode-revision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Decoded-`revision` sanitization for {@link import('./validation.ts').decodeWorkflowState}.
+ * Split out of `validation.ts`, which has no headroom under the repository's
+ * 500-line implementation-file ceiling.
+ *
+ * @module core/engine/decode-revision
+ */
+import type { WorkflowState } from '../types.ts';
+/**
+ * Normalize a decoded `revision` that is present but not a non-empty,
+ * bounded string.
+ *
+ * Deliberately NEVER drops a present-but-malformed value to `undefined` —
+ * `revision` is engine-derived (never user-supplied at the API surface), so
+ * an invalid value here indicates storage corruption or tampering, and
+ * `undefined` is the SAME signal a genuinely missing `revision` carries
+ * (a legitimate pre-revision-pinning record). Recovery treats an
+ * `undefined` pin as unambiguous for an eager type or a dynamic source with
+ * at most one registered candidate — silently executing that sole
+ * candidate against a checkpoint whose true originating revision is
+ * actually unknown, rather than rejecting the damaged identity. Instead,
+ * a malformed value is replaced with a deterministic, distinctly-prefixed
+ * marker derived from the workflow id: still a valid, bounded `string`, but
+ * virtually guaranteed not to match any real registered candidate, so the
+ * ordinary `resolveExecutableRegistrationForRevision()` "not-registered"
+ * path rejects it explicitly (an `unavailable` recovery outcome, isolated
+ * to that one run) instead of silently downgrading it to "legacy."
+ *
+ * Only a genuinely absent `revision` (never persisted at all) returns
+ * early, unchanged, above.
+ */
+export declare function sanitizeDecodedRevision(state: WorkflowState): void;

package/dist/core/engine/decode-revision.js

@@ -0,0 +1,9 @@
+const MAX_WORKFLOW_REVISION_LENGTH = 512, CORRUPTED_WORKFLOW_REVISION_PREFIX = "weft:corrupted-revision:";
+export function sanitizeDecodedRevision(state) {
+  if (state.revision === void 0)
+    return;
+  if (typeof state.revision === "string" && state.revision.length > 0 && state.revision.length <= MAX_WORKFLOW_REVISION_LENGTH)
+    return;
+  console.warn(`[weft] Decoded workflow state for "${state.id}" has a malformed revision field; replacing it with a corruption marker so recovery rejects it explicitly as an unavailable pin, rather than silently treating this run as pre-revision-pinning. This usually indicates corruption or tampering of the storage record.`);
+  state.revision = `${CORRUPTED_WORKFLOW_REVISION_PREFIX}${state.id}`.slice(0, MAX_WORKFLOW_REVISION_LENGTH);
+}

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

@@ -4,6 +4,10 @@ import type { EngineInternals } from './internals.ts';
  * `Engine[Symbol.dispose]` — the operation order is correctness-sensitive
  * (abort before clearing waiters, dispose strategies before nulling them) and
  * is preserved exactly. `Engine[Symbol.dispose]` and `[Symbol.asyncDispose]`
- * both delegate here.
+ * both delegate here. `dispatchEvent` defaults to a no-op so every existing
+ * direct-internals test that calls this with one argument keeps compiling
+ * and running — only `Engine`'s own two call sites pass the real
+ * `engine.dispatchEvent` binding, which is what lets
+ * `disposeSourceResolutionState` fire `workflow-source:load-cancelled`.
  */
-export declare function disposeEngine(internals: EngineInternals): void;
+export declare function disposeEngine(internals: EngineInternals, dispatchEvent?: (event: Event) => void): void;

package/dist/core/engine/disposal.js

@@ -1,3 +1,4 @@
+import { WorkflowSourceLoadCancelledEvent } from "../events/workflow-source-events.js";
 import { disposeEngineCleanupInterval } from "./engine-runtime-helpers.js";
 import { EngineDisposedError } from "./errors.js";
 import { disposeQueuedInlineWorkflowStarts } from "./inline-launch-queue.js";
@@ -13,7 +14,29 @@ function clearPendingResultPollTimers(internals) {
     clearTimeout(timer);
   internals.pendingResultPollTimers.clear();
 }
-export function disposeEngine(internals) {
+function rejectPendingResultResolvers(internals) {
+  for (const waiter of internals.resultResolvers.values())
+    waiter.reject(new EngineDisposedError);
+}
+function disposeSourceResolutionState(internals, dispatchEvent) {
+  for (const controller of internals.sources.waiterControllers)
+    controller.abort(new EngineDisposedError);
+  const stillLoading = [];
+  for (const [name, byRevision] of internals.sources.diagnostics)
+    for (const [revision, entry] of byRevision)
+      if (entry.state === "loading")
+        stillLoading.push({ name, revision, kind: entry.kind });
+  internals.sources.waiterControllers.clear();
+  internals.sources.resolutionsInFlight.clear();
+  internals.sources.byName.clear();
+  internals.sources.resolved.clear();
+  internals.sources.waitersByKey.clear();
+  internals.sources.lastResolvedRevisionByName.clear();
+  internals.sources.diagnostics.clear();
+  for (const { name, revision, kind } of stillLoading)
+    dispatchEvent(new WorkflowSourceLoadCancelledEvent(name, revision, kind));
+}
+export function disposeEngine(internals, dispatchEvent = () => {}) {
   internals.disposed = !0;
   internals.alertManager?.[Symbol.dispose]();
   internals.alertManager = null;
@@ -40,8 +63,7 @@ export function disposeEngine(internals) {
   disposeSecondInstanceDetection(internals);
   disposeLeaseManager(internals);
   internals.handleCache.clear();
-  for (const waiter of internals.resultResolvers.values())
-    waiter.reject(new EngineDisposedError);
+  rejectPendingResultResolvers(internals);
   rejectAllSleepTimerAcknowledgements(internals, new EngineDisposedError);
   internals.resultResolvers.clear();
   internals.updateWaiters.clear();
@@ -57,6 +79,7 @@ export function disposeEngine(internals) {
   for (const controller of internals.pendingWebhooks)
     controller.abort();
   internals.pendingWebhooks.clear();
+  disposeSourceResolutionState(internals, dispatchEvent);
   clearPendingResultPollTimers(internals);
   internals.sleepResolvers.clear();
   internals.sleepResolversByWorkflow.clear();