@lostgradient/weft 0.24.0 → 0.24.2

package/dist/core/engine/workflow-claim-reclaim-target.js

@@ -17,7 +17,21 @@ async function isWorkflowTypeRegistered(storage, workflowId, isTypeRegistered) {
   if (bytes === null)
     return !1;
   try {
-    return isTypeRegistered(decodeWorkflowState(bytes).type);
+    const state = decodeWorkflowState(bytes);
+    return isTypeRegistered(state.type, state.revision);
+  } catch {
+    return !1;
+  }
+}
+async function isWorkflowStillRunningAndEligible(storage, workflowId, isTypeRegistered) {
+  const bytes = await storage.get(KEYS.workflow(workflowId));
+  if (bytes === null)
+    return !1;
+  try {
+    const state = decodeWorkflowState(bytes);
+    if (state.status !== "running")
+      return !1;
+    return isTypeRegistered === void 0 || isTypeRegistered(state.type, state.revision);
   } catch {
     return !1;
   }
@@ -39,14 +53,14 @@ export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onR
       throw error;
     }
   }
-  async function releaseClaimAcquiredWhileDisposing(workflowId) {
-    await registry.release(workflowId);
+  async function releaseClaimAcquiredWhileDisposing(workflowId, acquiredEpoch) {
+    await registry.release(workflowId, acquiredEpoch);
   }
   async function confirmStillRunningOrReleaseFreshClaim(workflowId, acquiredEpoch) {
-    if (await isWorkflowStillRunning(storage, workflowId))
+    if (await isWorkflowStillRunningAndEligible(storage, workflowId, isTypeRegistered))
       return !0;
     if (registry.currentEpoch(workflowId) === acquiredEpoch)
-      await registry.release(workflowId);
+      await registry.release(workflowId, acquiredEpoch);
     return !1;
   }
   async function redriveAlreadyHeldClaim(workflowId, expectedEpoch) {
@@ -55,7 +69,7 @@ export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onR
     if (!await isWorkflowStillRunning(storage, workflowId)) {
       pendingRedriveWorkflowIds.delete(workflowId);
       if (registry.currentEpoch(workflowId) === expectedEpoch)
-        await registry.release(workflowId);
+        await registry.release(workflowId, expectedEpoch);
       return { status: "not-eligible" };
     }
     if (disposing)
@@ -76,7 +90,7 @@ export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onR
     }
     metrics.recordClaimAttempt("acquired");
     if (disposing) {
-      await releaseClaimAcquiredWhileDisposing(workflowId);
+      await releaseClaimAcquiredWhileDisposing(workflowId, acquireResult.epoch);
       return { status: "not-eligible" };
     }
     if (!await confirmStillRunningOrReleaseFreshClaim(workflowId, acquireResult.epoch))
@@ -86,7 +100,7 @@ export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onR
   async function handleTakeoverAcquired(workflowId, acquiredEpoch) {
     metrics.recordClaimAttempt("takeover");
     if (disposing) {
-      await releaseClaimAcquiredWhileDisposing(workflowId);
+      await releaseClaimAcquiredWhileDisposing(workflowId, acquiredEpoch);
       return { status: "not-eligible" };
     }
     if (!await confirmStillRunningOrReleaseFreshClaim(workflowId, acquiredEpoch))

package/dist/core/engine/workflow-claim-registry.d.ts

@@ -8,39 +8,43 @@
  * fragments; this module is the thin, stateful layer around them that reads
  * storage, executes `storageConditionalBatch`, and tracks — for every claim
  * THIS engine currently holds — the exact epoch and holder bytes it last
- * wrote. Renewal and release condition on those exact bytes, extracted from
- * the fragment they were just written by rather than re-encoded from the
- * fields the registry happens to know, mirroring `lease-manager.ts`'s
- * "never round-trip encode(decode(raw))" discipline.
+ * wrote, extracted from the fragment they were just written by rather than
+ * re-encoded, mirroring `lease-manager.ts`'s "never round-trip
+ * encode(decode(raw))" discipline.
  *
  * **Scope.** The unit itself: acquire, renew, release, takeover, and
  * release-all — plus, additively, {@link WorkflowClaimRegistry.prepareAcquireFragment}
  * and {@link WorkflowClaimRegistry.recordFoldedAcquire}, the two-step seam a
- * caller uses to fold `acquire` into ITS OWN atomic enabling write (a create
- * batch, a delayed-start pending→running transition, a failed-workflow
- * reactivation) instead of committing the fragment through this registry's
- * own `acquire()`. Driving `renew` and the reclaim scan from a lifecycle
- * task, and turning a lost `acquire`/`takeover` into
- * `WorkflowClaimUnavailableError` for explicit single-workflow callers, are
- * still each call site's own responsibility — this registry never throws
- * that error itself. Per the ADR, background scanning never throws it either
- * — it skips the workflow and continues — so every method here returns a
- * discriminated result instead of throwing on a lost CAS, leaving that
- * decision to the caller — `takeover` also gates on a per-workflow-id
- * anti-thrash cooldown ({@link WorkflowClaimTakeoverCooldown}). Still out of
- * scope: `weft_workflow_claim_*` metrics, `wakeOwnershipCheck`, and external
- * terminal-transition rotation (any engine may commit those unconditioned).
+ * caller uses to fold `acquire` into ITS OWN atomic enabling write instead of
+ * committing the fragment through this registry's own `acquire()`. Driving
+ * `renew`/the reclaim scan, and turning a lost `acquire`/`takeover` into
+ * `WorkflowClaimUnavailableError` for explicit single-workflow callers, stay
+ * each call site's responsibility — this registry never throws that error,
+ * and per the ADR background scanning never does either, so every method
+ * returns a discriminated result instead. `takeover` also gates on a
+ * per-workflow-id anti-thrash cooldown ({@link WorkflowClaimTakeoverCooldown}).
+ * Still out of scope: `weft_workflow_claim_*` metrics, `wakeOwnershipCheck`,
+ * and external terminal-transition rotation.
  *
  * **Renewal-vs-release serialization.** A per-workflow in-flight-renewal
  * promise (mirroring `lease-manager.ts`'s single `inFlightRenewal`) lets
  * `release()` await a renewal already in progress before reading the cached
- * bytes it conditions on; otherwise both race the same holder bytes and
- * whichever commits second loses its CAS. A `releasing` set stops a NEW
- * renewal from starting once release has begun, so a `renew()` arriving
- * mid-release fails fast as `'not-held'`. A renewal that THROWS (a transient
- * storage error, not a CAS-false result) is not a lost claim: it propagates
- * to its caller leaving cached bytes untouched, and `release()`'s wait
- * swallows it — a storage hiccup must not fail a terminal or shutdown release.
+ * bytes it conditions on; otherwise both race the same holder bytes. A
+ * `releasing` set stops a NEW renewal from starting once release has begun,
+ * so a `renew()` arriving mid-release fails fast as `'not-held'`. A renewal
+ * that THROWS (transient, not a CAS-false result) is not a lost claim: it
+ * propagates leaving cached bytes untouched, and `release()`'s wait swallows
+ * it — a storage hiccup must not fail a terminal or shutdown release.
+ *
+ * **Epoch-guarded release (WFT-134).** `release(workflowId, expectedEpoch?)`
+ * takes an OPTIONAL epoch a caller itself acquired; without it, `release`
+ * drops whatever entry is CURRENTLY tracked — correct only when nothing else
+ * could have replaced the claim meanwhile. A caller undoing ITS OWN
+ * acquisition must pass that epoch: a `recordFoldedAcquire` replacement can
+ * land even during this call's own in-flight-renewal await, and
+ * `expectedEpoch` is re-checked against the freshly-read entry AFTER that
+ * await, so a stale pre-await snapshot never authorizes releasing a newer,
+ * live claim.
  *
  * @module core/engine/workflow-claim-registry
  */
@@ -56,10 +60,7 @@ export type WorkflowClaimRegistryOptions = {
     getNow: () => number;
     /** `workflowClaimTtl` (ms), resolved by `ownership-options.ts`. */
     claimTtlMs: number;
-    /**
-     * `workflowClaimRenewInterval` (ms), resolved by `ownership-options.ts` —
-     * feeds `isWorkflowClaimExpired`'s grace term.
-     */
+    /** `workflowClaimRenewInterval` (ms) — feeds `isWorkflowClaimExpired`'s grace term. */
     claimRenewIntervalMs: number;
     /** Operator-warning seam; defaults to `process.emitWarning` via {@link emitWorkflowClaimLostWarning}. */
     warn?: EmitWorkflowLeaseWarning;
@@ -98,8 +99,8 @@ export type WorkflowClaimReleaseResult = {
 };
 /**
  * A prepared, not-yet-committed `acquire` — the output of
- * {@link WorkflowClaimRegistry.prepareAcquireFragment}, meant to be merged
- * into a caller's own atomic enabling write and then handed back to
+ * {@link WorkflowClaimRegistry.prepareAcquireFragment}, merged into a
+ * caller's own atomic write and handed to
  * {@link WorkflowClaimRegistry.recordFoldedAcquire} once that write commits.
  */
 export type WorkflowClaimAcquirePreparation = {
@@ -130,8 +131,8 @@ export type WorkflowClaimTakeoverResult = {
 };
 /**
  * Owns this engine's per-workflow ownership claims: reads storage, executes
- * the pure transition fragments, and tracks the exact bytes it last wrote for
- * every claim it currently holds. See the module doc for scope.
+ * the pure transition fragments, and tracks the exact bytes last written for
+ * every held claim. See the module doc for scope.
  */
 export declare class WorkflowClaimRegistry {
     #private;
@@ -142,25 +143,20 @@ export declare class WorkflowClaimRegistry {
     get engineId(): string;
     /**
      * Every workflow id this engine currently tracks a live claim for — active
-     * or parked. A defensive-copy snapshot, mirroring `releaseAll`'s own
-     * `[...this.#claims.keys()]` read: callers (the claim-renewal task, an
-     * active-claims metrics gauge) must not observe mutations to this registry's
-     * internal map while iterating a snapshot they already took.
+     * or parked. A defensive-copy snapshot: callers (the claim-renewal task, an
+     * active-claims metrics gauge) must not observe mutations to this
+     * registry's internal map while iterating a snapshot they already took.
      */
     listHeldWorkflowIds(): readonly string[];
     /**
      * Defensive copy of the epoch bytes this engine last wrote for
-     * `workflowId`, for fencing durable writes — `null` if untracked. A copy so
-     * a caller mutating the returned buffer cannot corrupt this registry's
-     * cached fencing token.
+     * `workflowId`, for fencing durable writes — `null` if untracked.
      */
     currentEpochBytes(workflowId: string): Uint8Array | null;
     /**
-     * `acquire`: always reads both keys fresh — never assumes absence — then
-     * builds and attempts the fragment from what it read. On a lost CAS,
-     * resolves `heldBy` from the holder bytes already read when they were
-     * non-null; otherwise (a competitor raced in between the read and the
-     * write) re-reads to report the true current holder.
+     * `acquire`: always reads both keys fresh, then builds and attempts the
+     * fragment from what it read. On a lost CAS, resolves `heldBy` from the
+     * already-read holder bytes when non-null; otherwise re-reads.
      */
     acquire(workflowId: string): Promise<WorkflowClaimAcquireResult>;
     /**
@@ -168,60 +164,68 @@ export declare class WorkflowClaimRegistry {
      * `acquire` fragment WITHOUT committing it or updating this registry's
      * tracking — for a caller that folds the fragment into ITS OWN atomic
      * enabling write instead of letting {@link acquire} commit it alone. The
-     * caller merges `fragment.conditions`/`fragment.operations` into its own
-     * operation list, commits ONE atomic `storageConditionalBatch`, and —
-     * ONLY on success — calls {@link recordFoldedAcquire} with this SAME
-     * preparation. Safe to call again on every retry attempt: this always
-     * re-reads fresh bytes, so a stale epoch from an earlier attempt never
-     * dooms a later one.
+     * caller merges the fragment into its own operation list, commits ONE
+     * atomic `storageConditionalBatch`, and — ONLY on success — calls
+     * {@link recordFoldedAcquire} with this SAME preparation. Safe to call
+     * again on every retry: it always re-reads fresh bytes.
      */
     prepareAcquireFragment(workflowId: string): Promise<WorkflowClaimAcquirePreparation>;
     /**
      * Install the tracking entry for a claim acquired via a FOLDED enabling
      * write (see {@link prepareAcquireFragment}) — call ONLY after the
-     * caller's own atomic commit that included `preparation.fragment`'s
-     * conditions and operations has actually succeeded. Extracts the exact
-     * bytes the fragment wrote using the same "never round-trip
-     * encode(decode(raw))" discipline every other grant path in this class
-     * uses.
+     * caller's own atomic commit of `preparation.fragment` has succeeded.
+     * Extracts the exact written bytes, the same "never round-trip
+     * encode(decode(raw))" discipline every other grant path here uses.
      */
     recordFoldedAcquire(workflowId: string, preparation: WorkflowClaimAcquirePreparation): void;
     /**
      * `renew`: conditions on the exact holder bytes this engine last wrote.
      * Concurrent calls for the same id share the one in-flight promise. A
      * CAS-false result marks the claim lost locally and emits
-     * `WeftWorkflowClaimLostWarning` — losing one workflow's claim never
-     * touches any other tracked claim.
+     * `WeftWorkflowClaimLostWarning`.
      */
     renew(workflowId: string): Promise<WorkflowClaimRenewResult>;
     /**
      * `release`: stops new renewals for `workflowId` and awaits any renewal
-     * already in flight (swallowing a thrown rejection — best-effort, never
-     * reject on a renewal's storage error) before building the expected bytes,
-     * so the two can never race the same holder bytes. Deletes only the holder
-     * key — the epoch key is never touched, so a successor's next `acquire`
-     * reads the true prior epoch. A lost CAS means this engine was already
-     * fenced out; the local entry is dropped either way, since there is
-     * nothing left to protect.
+     * already in flight (best-effort — swallows a thrown rejection) before
+     * building the expected bytes, so the two never race the same holder
+     * bytes. Deletes only the holder key, never the epoch key, so a
+     * successor's next `acquire` reads the true prior epoch.
+     *
+     * `expectedEpoch`, when given, makes this a no-op (`'not-held'`) against
+     * any entry but the exact generation the caller means to undo — see the
+     * module doc's "Epoch-guarded release". A thrown storage error during the
+     * CAS still forgets the LOCAL entry (identity-guarded like the
+     * success/failure paths below) before rethrowing, so a caller giving up
+     * after a failed release does not leave the renewal task renewing forever
+     * (WFT-134).
      */
-    release(workflowId: string): Promise<WorkflowClaimReleaseResult>;
+    release(workflowId: string, expectedEpoch?: number): Promise<WorkflowClaimReleaseResult>;
     /**
      * `takeover`: reads the holder and epoch keys fresh, and only attempts the
      * CAS once the holder is not live — either its grace-adjusted `expiresAt`
      * has passed ({@link isWorkflowClaimExpired}), or the holder bytes are
      * foreign/undecodable garbage no valid engine could have written (mirrors
-     * `lease-manager.ts`'s "garbage is not a live owner" treatment: not live,
-     * so it can be stolen via CAS on its exact observed bytes). A holder
-     * present with no epoch key violates the write invariant — the two are
-     * always written together, and the epoch key is never deleted — so it is
-     * treated defensively as nothing safe to fence a takeover against.
+     * `lease-manager.ts`'s "garbage is not a live owner" treatment). A holder
+     * with no epoch key violates the write invariant — the two are always
+     * written together, and the epoch key is never deleted — so it is treated
+     * defensively as nothing safe to fence a takeover against.
      */
     takeover(workflowId: string): Promise<WorkflowClaimTakeoverResult>;
     /**
-     * Best-effort release of every claim this engine currently tracks, for
-     * graceful shutdown. A failed release (thrown or lost-race) is swallowed
-     * per workflow so shutdown proceeds — the reclaim scan (a later stage)
-     * collects any stranded claim once its grace-adjusted expiry passes.
+     * Forget this engine's LOCAL tracking entry for `workflowId` — no durable
+     * write, just `this.#claims.delete`. Caller: `suspendWorkflow` (WFT-134),
+     * whose commit already durably deletes `wf-owner-holder:<id>`, leaving only
+     * this stale cache entry — else {@link currentEpoch} stays non-null for a
+     * gone holder, routing a same-engine `resume()` onto the stale-cache fast
+     * path in `acquireStandaloneClaimBeforeResume`. No-op on an untracked id;
+     * check {@link currentEpoch} first to avoid clobbering a newer generation.
+     */
+    forgetLocalClaim(workflowId: string): void;
+    /**
+     * Best-effort release of every claim this engine tracks, for graceful
+     * shutdown. A failed release (thrown or lost-race) is swallowed per
+     * workflow — the reclaim scan later collects any stranded claim.
      */
     releaseAll(): Promise<void>;
 }

package/dist/core/engine/workflow-claim-registry.js

@@ -125,7 +125,7 @@ export class WorkflowClaimRegistry {
       this.#claims.set(workflowId, { ...entry, holderBytes });
     return { status: "renewed", workflowId };
   }
-  async release(workflowId) {
+  async release(workflowId, expectedEpoch) {
     this.#releasing.add(workflowId);
     try {
       const inFlight = this.#inFlightRenewals.get(workflowId);
@@ -136,11 +136,21 @@ export class WorkflowClaimRegistry {
       const entry = this.#claims.get(workflowId);
       if (entry === void 0)
         return { status: "not-held", workflowId };
+      if (expectedEpoch !== void 0 && entry.epoch !== expectedEpoch)
+        return { status: "not-held", workflowId };
       const fragment = buildWorkflowClaimReleaseTransition({
         workflowId,
         currentEpochBytes: entry.epochBytes,
         currentHolderBytes: entry.holderBytes
-      }), committed = await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations);
+      });
+      let committed;
+      try {
+        committed = await storageConditionalBatch(this.#claimStorage, fragment.conditions, fragment.operations);
+      } catch (error) {
+        if (this.#claims.get(workflowId) === entry)
+          this.#claims.delete(workflowId);
+        throw error;
+      }
       if (this.#claims.get(workflowId) === entry)
         this.#claims.delete(workflowId);
       return { status: committed ? "released" : "lost-race", workflowId };
@@ -187,6 +197,9 @@ export class WorkflowClaimRegistry {
     this.#takeoverCooldown.clear(workflowId);
     return { status: "acquired", workflowId, epoch };
   }
+  forgetLocalClaim(workflowId) {
+    this.#claims.delete(workflowId);
+  }
   async releaseAll() {
     const workflowIds = [...this.#claims.keys()];
     await Promise.all(workflowIds.map(async (workflowId) => {

package/dist/core/engine/workflow-generation-fence.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bump helpers for the durable per-workflow-id generation counter
+ * (`wf-gen:<id>`, WFT-153). See `storage/generation-keys.ts` for the
+ * keyspace's full rationale.
+ *
+ * Mirrors `workflow-claim-transitions.ts`'s epoch-rotation fragment shape
+ * (`nextEpochFromObservedBytes` / `buildWorkflowClaimExternalTerminalRotationTransition`)
+ * deliberately: both are "mint `(observed ?? 0) + 1`, never a literal"
+ * permanently-retained counters bumped in the same atomic batch as the
+ * transition that motivates the bump.
+ *
+ * @module core/engine/workflow-generation-fence
+ */
+import { type BatchOperation } from '../../storage/interface.ts';
+import type { EngineInternals } from './internals.ts';
+import type { WorkflowClaimTransitionFragment } from './workflow-claim-transitions.ts';
+/** Mint the next generation from bytes just read: `(decode(bytes) ?? 0) + 1`, never a literal. */
+export declare function nextGenerationFromObservedBytes(observedGenerationBytes: Uint8Array | null): number;
+/**
+ * Build just the `wf-gen:<id>` bump PUT operation from an ALREADY-OBSERVED
+ * value — no storage read of its own. Used by the `onTerminalConflict:
+ * 'start-new'` restart path (`start-terminal-conflict-purge.ts`), which folds
+ * this operation into its create batch and relies on that batch's own outer
+ * `duplicateIdGenerationCondition` — built from the SAME observed bytes this
+ * function bumps from — as the CAS fence, rather than a second, independent
+ * condition here. Reusing one observed value for both the fence and the bump
+ * amount is what makes the restart's own CAS trivially self-consistent: it
+ * can never fence itself out on its own legitimate restart, because the
+ * value it bumps from is exactly the value its own precondition checks.
+ */
+export declare function buildWorkflowGenerationBumpOperation(workflowId: string, observedGenerationBytes: Uint8Array | null): BatchOperation;
+/**
+ * Read the current `wf-gen:<id>` value, build its bump PUT operation and (CAS
+ * condition permitting) fold BOTH into `base` — the caller's own fragment, in
+ * `purgeWorkflow` the `wf-owner-epoch` rotation fragment
+ * `buildExternalTerminalRotationFragment` already built — for a STANDALONE
+ * purge/retention commit that, unlike the `'start-new'` restart path above,
+ * has no pre-existing duplicate-id-style condition of its own to piggyback
+ * on. Folding happens HERE, not at the call site, so `purgeWorkflow` stays a
+ * flat read-then-commit without its own merge step.
+ *
+ * RESOLVED (chatgpt-codex-connector review, WFT-153): this bump PUT was
+ * previously unconditioned, on the theory that a lost update between two
+ * concurrent purges of the same id was harmless — either purge's bump moves
+ * the value away from whatever an earlier duplicate-id read observed. That
+ * theory misses a THIRD purge landing in between: purge A reads generation
+ * N and (slowly) prepares a bump to N+1; purge B — a later purge of the
+ * SAME id, after the id was reused and purged again — reads the CURRENT
+ * value N+1 and commits a bump to N+2; if A's stale N+1 write then commits
+ * UNCONDITIONED, it overwrites B's N+2 with A's own N+1, rolling the
+ * "monotonic" counter backward. A cross-engine start that captured the
+ * intermediate absent/N+1 pair during the window before B's purge could then
+ * pass its `duplicateIdGenerationCondition` re-check after the rollback, even
+ * though a run genuinely executed and was purged in between — reopening the
+ * exact ABA this key exists to close.
+ *
+ * The condition folded in now closes that: `expectedValue` is the SAME
+ * `observedGenerationBytes` the bump amount is minted from, so a lost race
+ * (another purge already changed `wf-gen:<id>` since this read) fails the
+ * CAS instead of overwriting a newer generation with a stale one. Gated on
+ * `internals.storage.capabilities().conditionalBatch` (the same
+ * capability-conditioned pattern `buildWorkflowStateCommit` uses in
+ * `storage-io.ts`) rather than required unconditionally: a backend that
+ * honestly reports no `conditionalBatch` support keeps the pre-existing
+ * unconditioned bump (a residual, capability-limited ABA window, not a new
+ * regression) instead of newly requiring a capability purge never required
+ * before this fix — purge must keep working, degraded, on such backends.
+ *
+ * Runs under EVERY ownership mode — unlike the `wf-owner-epoch` rotation
+ * fragment, which is a no-op outside `ownership: 'workflow-lease'`, this
+ * always reads and bumps: the ABA hole it closes exists under `'none'` and
+ * `'lease'` too.
+ */
+export declare function foldWorkflowGenerationBumpForPurge(internals: EngineInternals, workflowId: string, base: WorkflowClaimTransitionFragment): Promise<WorkflowClaimTransitionFragment>;

package/dist/core/engine/workflow-generation-fence.js

@@ -0,0 +1,19 @@
+import { KEYS } from "../../storage/interface.js";
+import { decodeGeneration, encodeGeneration } from "./generation-codec.js";
+export function nextGenerationFromObservedBytes(observedGenerationBytes) {
+  return ((observedGenerationBytes === null ? null : decodeGeneration(observedGenerationBytes)) ?? 0) + 1;
+}
+export function buildWorkflowGenerationBumpOperation(workflowId, observedGenerationBytes) {
+  return {
+    type: "put",
+    key: KEYS.workflowGeneration(workflowId),
+    value: encodeGeneration(nextGenerationFromObservedBytes(observedGenerationBytes))
+  };
+}
+export async function foldWorkflowGenerationBumpForPurge(internals, workflowId, base) {
+  const key = KEYS.workflowGeneration(workflowId), observedGenerationBytes = await internals.storage.get(key), operation = buildWorkflowGenerationBumpOperation(workflowId, observedGenerationBytes), condition = internals.storage.capabilities().conditionalBatch ? { key, expectedValue: observedGenerationBytes } : void 0;
+  return {
+    operations: [...base.operations, operation],
+    conditions: base.conditions.concat(condition ?? [])
+  };
+}

package/dist/core/engine/workflow-retention-deadline.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * The timestamp at which `state` becomes eligible for retention-driven
+ * purge, or `null` when it is non-terminal, has no applicable retention
+ * window, or (WFT-19 review round 2) its own pinned revision's retention
+ * policy cannot be resolved on this process right now — an unresolvable pin
+ * is NOT purge-eligible under the engine default; it is re-examined on a
+ * later sweep once the pin becomes resolvable, rather than risking an
+ * irreversible early purge against a shorter policy than the run's own.
+ * Falls back to the resolved dynamic definition's own retention policy for a
+ * `registerSource()`-registered type (see `resolveRetentionPolicyForState()`),
+ * then the engine-wide default for any other type — mirroring `retention.ts`'s
+ * `resolveWorkflowTypeRetention`.
+ */
+export declare function getWorkflowRetentionDeadline(internals: EngineInternals, state: WorkflowState): Promise<number | null>;

package/dist/core/engine/workflow-retention-deadline.js

@@ -0,0 +1,33 @@
+import { DynamicWorkflowSourceUnavailableError } from "./dynamic-source-errors.js";
+import {
+  getResolvedDynamicRegistration,
+  resolveExecutableRegistrationForRevision
+} from "./dynamic-source-execution.js";
+import { WorkflowRevisionUnavailableError } from "./revision-errors.js";
+import { isTerminalWorkflowStatus, resolveRetentionForStatus } from "./validation.js";
+async function resolveRetentionPolicyForState(internals, state) {
+  const eagerOrAlreadyResolved = getResolvedDynamicRegistration(internals, state.type, state.revision)?.retention;
+  if (eagerOrAlreadyResolved !== void 0)
+    return { kind: "resolved", policy: eagerOrAlreadyResolved };
+  if (!internals.sources.byName.has(state.type))
+    return { kind: "resolved", policy: void 0 };
+  try {
+    const { entry } = await resolveExecutableRegistrationForRevision(internals.engine, internals, state.type, state.revision);
+    return { kind: "resolved", policy: entry.retention };
+  } catch (error) {
+    if (error instanceof DynamicWorkflowSourceUnavailableError || error instanceof WorkflowRevisionUnavailableError)
+      return { kind: "unresolvable" };
+    throw error;
+  }
+}
+export async function getWorkflowRetentionDeadline(internals, state) {
+  if (!isTerminalWorkflowStatus(state.status))
+    return null;
+  const resolution = await resolveRetentionPolicyForState(internals, state);
+  if (resolution.kind === "unresolvable")
+    return null;
+  const policy = resolution.policy ?? internals.options.retention, retentionMs = resolveRetentionForStatus(policy, state.status);
+  if (retentionMs === void 0)
+    return null;
+  return state.updatedAt + retentionMs;
+}

package/dist/core/events/event-map.d.ts

@@ -7,6 +7,7 @@ import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.
 import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent, WorkerConnectedEvent, WorkerDisconnectedEvent } from './system-events.ts';
 import type { UpdateCompletedEvent, UpdateReceivedEvent } from './update-events.ts';
 import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowDefinitionRegisteredEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTeardownEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
+import type { WorkflowSourceLoadCancelledEvent, WorkflowSourceLoadFailedEvent, WorkflowSourceLoadReadyEvent, WorkflowSourceLoadStartedEvent } from './workflow-source-events.ts';
 /**
  * Record mapping each event-name string the {@link Engine} dispatches to its
  * corresponding typed `Event` subclass.
@@ -63,6 +64,10 @@ export type WeftEventMap = {
     'catalog:activation-rejected': WorkflowRevisionActivationRejectedEvent;
     'catalog:revision-draining': WorkflowRevisionDrainingEvent;
     'catalog:revision-removed': WorkflowRevisionRemovedEvent;
+    'workflow-source:load-started': WorkflowSourceLoadStartedEvent;
+    'workflow-source:load-ready': WorkflowSourceLoadReadyEvent;
+    'workflow-source:load-failed': WorkflowSourceLoadFailedEvent;
+    'workflow-source:load-cancelled': WorkflowSourceLoadCancelledEvent;
 };
 /**
  * Typed version of the `EventTarget` interface that constrains

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

@@ -7,3 +7,4 @@ export * from './signal-events.ts';
 export * from './system-events.ts';
 export * from './update-events.ts';
 export * from './workflow-events.ts';
+export * from './workflow-source-events.ts';

package/dist/core/events/index.js

@@ -7,3 +7,4 @@ export * from "./signal-events.js";
 export * from "./system-events.js";
 export * from "./update-events.js";
 export * from "./workflow-events.js";
+export * from "./workflow-source-events.js";

package/dist/core/events/workflow-source-events.d.ts

@@ -0,0 +1,102 @@
+import type { FailureCategory } from '../types/identity.ts';
+type WorkflowSourceKind = import('../source/index.ts').WorkflowSourceKind;
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's single-flight
+ * load for `(workflowType, revision)` starts — the loader is about to be
+ * invoked. Never fired for a cache hit (an already-installed revision
+ * `resolveWorkflowSource()` returns without invoking the loader).
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadStartedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadStartedEvent.type, (event) => {
+ *   console.log('loading:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadStartedEvent extends Event {
+    static readonly type: "workflow-source:load-started";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind);
+}
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's load for
+ * `(workflowType, revision)` completes successfully — the loader ran,
+ * validation passed, and the manifest is durably installed.
+ * `loadDurationMs` is measured via the engine's own injected clock.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadReadyEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadReadyEvent.type, (event) => {
+ *   console.log('ready:', event.workflowType, event.revision, event.loadDurationMs);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadReadyEvent extends Event {
+    static readonly type: "workflow-source:load-ready";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    readonly loadDurationMs: number;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind, loadDurationMs: number);
+}
+/**
+ * Fired on the {@link Engine} when a dynamic workflow source's load for
+ * `(workflowType, revision)` fails — the loader threw, validation rejected
+ * the loaded module, or the durable install failed. `failureCategory` is
+ * the closed, low-cardinality {@link FailureCategory} classification, safe
+ * to use as a metric label; the underlying error itself is never included.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadFailedEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadFailedEvent.type, (event) => {
+ *   console.log('failed:', event.workflowType, event.revision, event.failureCategory);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadFailedEvent extends Event {
+    static readonly type: "workflow-source:load-failed";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    readonly loadDurationMs: number;
+    readonly failureCategory: FailureCategory;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind, loadDurationMs: number, failureCategory: FailureCategory);
+}
+/**
+ * Fired on the {@link Engine} when the LAST outstanding
+ * `resolveWorkflowSource()` waiter for `(workflowType, revision)` releases
+ * (its own abort, or engine disposal) while the shared load is still
+ * unsettled. The shared load itself is never aborted — a fresh caller
+ * starting a new attempt for the same key re-fires
+ * {@link WorkflowSourceLoadStartedEvent}, not this event again for the
+ * orphaned attempt.
+ *
+ * @example
+ * ```ts
+ * import { Engine, WorkflowSourceLoadCancelledEvent } from '@lostgradient/weft';
+ *
+ * const engine = new Engine();
+ * engine.addEventListener(WorkflowSourceLoadCancelledEvent.type, (event) => {
+ *   console.log('cancelled:', event.workflowType, event.revision);
+ * });
+ * ```
+ */
+export declare class WorkflowSourceLoadCancelledEvent extends Event {
+    static readonly type: "workflow-source:load-cancelled";
+    readonly workflowType: string;
+    readonly revision: string;
+    readonly kind: WorkflowSourceKind;
+    constructor(workflowType: string, revision: string, kind: WorkflowSourceKind);
+}
+export {};