@lostgradient/weft 0.24.1 → 0.24.2

package/dist/core/engine/validation.js

@@ -1,8 +1,9 @@
 import { decode } from "../codec.js";
 import { isRecord } from "../debug-output.js";
 import { normalizeFailureCategory } from "../failure-categories.js";
-import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
+import { parseStartWorkflowDuration } from "../start-workflow-validation.js";
 import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
+import { isDecodableWorkflowId } from "../workflow-identifiers.js";
 import { isWorkflowTagArray } from "../workflow-tags.js";
 import { sanitizeDecodedRevision } from "./decode-revision.js";
 import {
@@ -133,25 +134,18 @@ export function decodeWorkflowState(bytes) {
     else
       state.failureCategory = normalizedFailureCategory;
   }
-  if (state.executionStateOwnerId !== void 0)
-    try {
-      coerceStartWorkflowId(state.executionStateOwnerId, "executionStateOwnerId");
-    } catch {
-      console.warn(`[weft] Decoded workflow state for "${state.id}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
-      delete state.executionStateOwnerId;
-    }
+  if (state.executionStateOwnerId !== void 0 && !isDecodableWorkflowId(state.executionStateOwnerId)) {
+    console.warn(`[weft] Decoded workflow state for "${state.id}" has an invalid executionStateOwnerId field; falling back to the workflow id as the execution owner. This usually indicates corruption or tampering of the storage record.`);
+    delete state.executionStateOwnerId;
+  }
   sanitizeDecodedParentLineage(state);
   sanitizeDecodedRestartLineage(state);
   sanitizeDecodedRevision(state);
   return decodedRecord === void 0 ? state : stripUnknownWorkflowStateFields(state, decodedRecord);
 }
 function sanitizeDecodedParentLineage(state) {
-  if (state.parentWorkflowId !== void 0)
-    try {
-      coerceStartWorkflowId(state.parentWorkflowId, "parentWorkflowId");
-    } catch {
-      delete state.parentWorkflowId;
-    }
+  if (state.parentWorkflowId !== void 0 && !isDecodableWorkflowId(state.parentWorkflowId))
+    delete state.parentWorkflowId;
   if (typeof state.parentWorkflowExecutionToken !== "string" || state.parentWorkflowExecutionToken.length === 0 || state.parentWorkflowId === void 0)
     delete state.parentWorkflowExecutionToken;
 }
@@ -161,9 +155,8 @@ function sanitizeDecodedRestartLineage(state) {
     delete state.restartedFrom;
     return;
   }
-  try {
-    coerceStartWorkflowId(restartedFrom.workflowId, "restartedFrom.workflowId");
-  } catch {
+  const restartWorkflowId = restartedFrom.workflowId;
+  if (typeof restartWorkflowId !== "string" || !isDecodableWorkflowId(restartWorkflowId)) {
     delete state.restartedFrom;
     return;
   }

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

@@ -53,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 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) {
@@ -69,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)
@@ -90,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))
@@ -100,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/start-workflow-validation.d.ts

@@ -14,6 +14,21 @@ export declare class StartWorkflowValidationError extends WeftError<'StartWorkfl
 }
 export declare const assertExclusiveStartWorkflowOptions: (startAt: unknown, startAfter: unknown) => void;
 export declare const coerceStartWorkflowId: (value: unknown, fieldName: string) => string;
+/**
+ * Coerce a caller-supplied `options.id` for an internal REPLAY of a start
+ * that was already accepted once before (WFT-95). Deliberately uses the
+ * decode-compatible {@link assertDecodableWorkflowId}, not the strict
+ * `.`/`..`-rejecting {@link assertValidWorkflowId} that
+ * {@link coerceStartWorkflowId} enforces: this path exists only for the three
+ * internal callers that replay an id which was already durably admitted
+ * before strict admission existed (a drained schedule queued-run, a bulk
+ * failed-workflow retry rebuilding from persisted input, or a child-workflow
+ * crash-reattach) — see `startWorkflow`'s `skipAdmissionIdCheck` parameter.
+ * It must never be reachable from a public start surface (REST, JSON-RPC,
+ * `engine.start`, `ctx.startChild`), because that would let a genuinely
+ * fresh caller admit `.`/`..` again.
+ */
+export declare const coerceReplayWorkflowId: (value: unknown, fieldName: string) => string;
 /**
  * Coerce a transport-supplied idempotency key to a non-empty string. The key is
  * a caller-chosen dedup token (it becomes part of a `start-idem:` storage key),

package/dist/core/start-workflow-validation.js

@@ -1,6 +1,6 @@
 import { parseDuration } from "./scheduler.js";
 import { WeftError } from "./weft-error.js";
-import { assertValidWorkflowId } from "./workflow-identifiers.js";
+import { assertDecodableWorkflowId, assertValidWorkflowId } from "./workflow-identifiers.js";
 export const MAX_WORKFLOW_TAGS = 32, MAX_WORKFLOW_TAG_BYTES = 128, MAX_IDEMPOTENCY_KEY_BYTES = 117;
 const textEncoder = new TextEncoder, EXCLUSIVE_START_WORKFLOW_OPTIONS_ERROR = "Provide only one of startAt or startAfter";
 
@@ -22,6 +22,16 @@ export const assertExclusiveStartWorkflowOptions = (startAt, startAfter) => {
     const message = error instanceof Error ? error.message : String(error);
     throw new StartWorkflowValidationError(message);
   }
+}, coerceReplayWorkflowId = (value, fieldName) => {
+  if (typeof value !== "string")
+    throw new StartWorkflowValidationError(`${fieldName} must be a string`);
+  try {
+    assertDecodableWorkflowId(value, fieldName);
+    return value;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new StartWorkflowValidationError(message);
+  }
 }, coerceStartWorkflowIdempotencyKey = (value, fieldName) => {
   if (typeof value !== "string")
     throw new StartWorkflowValidationError(`${fieldName} must be a string`);

package/dist/core/workflow-identifiers.d.ts

@@ -1 +1,38 @@
+/**
+ * Assert every workflow-id constraint that predates WFT-95: a string,
+ * non-empty, at most {@link MAX_WORKFLOW_ID_LENGTH} characters, and free of
+ * control characters. Deliberately does NOT reject the exact strings `.` or
+ * `..` — those were valid workflow ids before WFT-95 and may already be
+ * durably persisted (a schedule id, a persisted `currentWorkflowId`, a
+ * queued run's `workflowId`, schedule-run metadata, an `executionStateOwnerId`
+ * or `parentWorkflowId`/`restartedFrom.workflowId` on a decoded
+ * `WorkflowState`). Decode and schedule-control (lookup, pause, resume,
+ * cancel, update) paths must keep accepting them so an upgrade doesn't
+ * strand pre-existing data or make a pre-existing schedule/workflow
+ * unmanageable; only fresh admission ({@link assertValidWorkflowId}) adds
+ * the `.`/`..` rejection.
+ *
+ * Takes `unknown`, not `string` (WFT-95 review): every caller passes an
+ * already-decoded field whose static `WorkflowState`/`ScheduleState` type
+ * says `string` but whose runtime shape is untrusted — the storage record
+ * could be corrupted. Without an explicit `typeof` guard here, a decoded
+ * array of strings would pass (`.length`, iteration, and
+ * `containsControlCharacter()`'s per-element `codePointAt()` all succeed on
+ * an array too), silently accepting a malformed field instead of dropping
+ * it — the same guard `coerceStartWorkflowId()` performed before this
+ * predicate existed.
+ */
+export declare function assertDecodableWorkflowId(id: unknown, fieldName?: string): asserts id is string;
+/** Whether `id` satisfies {@link assertDecodableWorkflowId}. */
+export declare function isDecodableWorkflowId(id: unknown): boolean;
+/**
+ * Whether `id` is exactly `.` or `..` — the two literals
+ * {@link assertValidWorkflowId} rejects at fresh admission (WFT-95). Exported
+ * so callers that need to recognize "this id is the one strict admission
+ * would reject" without re-running the full assertion (for example, to
+ * decide whether a caller-facing id MIGHT be a legacy pre-WFT-95 record
+ * worth checking storage for) share one definition instead of re-deriving
+ * the literal comparison.
+ */
+export declare function isReservedWorkflowIdLiteral(id: string): boolean;
 export declare function assertValidWorkflowId(id: string, fieldName?: string): void;

package/dist/core/workflow-identifiers.js

@@ -9,7 +9,9 @@ function containsControlCharacter(value) {
   }
   return !1;
 }
-export function assertValidWorkflowId(id, fieldName = "options.id") {
+export function assertDecodableWorkflowId(id, fieldName = "options.id") {
+  if (typeof id !== "string")
+    throw Error(`${fieldName} must be a string`);
   if (id.length === 0)
     throw Error(`${fieldName} must not be an empty string`);
   if (id.length > MAX_WORKFLOW_ID_LENGTH)
@@ -17,3 +19,19 @@ export function assertValidWorkflowId(id, fieldName = "options.id") {
   if (containsControlCharacter(id))
     throw Error(`${fieldName} must not contain control characters`);
 }
+export function isDecodableWorkflowId(id) {
+  try {
+    assertDecodableWorkflowId(id);
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export function isReservedWorkflowIdLiteral(id) {
+  return id === "." || id === "..";
+}
+export function assertValidWorkflowId(id, fieldName = "options.id") {
+  if (isReservedWorkflowIdLiteral(id))
+    throw Error(`${fieldName} must not be "." or ".."`);
+  assertDecodableWorkflowId(id, fieldName);
+}