@lostgradient/weft 0.24.1 → 0.24.2

package/dist/core/engine/lifecycle/start-terminal-conflict-purge.d.ts

@@ -38,17 +38,41 @@ export type StartDuplicateIdDecision = {
      * capability at `Engine.create()`. A store that cannot honour this condition
      * cannot host an engine that could start a workflow in the first place.
      *
-     * KNOWN LIMITATION (PR #959 review). The condition compares a VALUE, so it cannot
-     * distinguish "this id was never used" from "a run existed here and was purged".
-     * If a racing winner commits, completes, and is purged or swept by retention
-     * before this batch commits, `wf:<id>` is absent again, `expectedValue: null`
-     * matches, and both starts execute. Closing that needs durable per-id generation
-     * or tombstone state a purge cannot restore — a new persisted mechanism, out of
-     * scope here. The window is narrow (a winner's whole lifecycle plus a purge inside
-     * one loser's read-to-commit gap) and the outcome is a duplicate run rather than
-     * the indefinite hang this fence exists to remove.
+     * RESOLVED (PR #959 review; closed by WFT-153). This condition alone compares
+     * only a VALUE, so on its own it cannot distinguish "this id was never used"
+     * from "a run existed here and was purged" — a racing winner that commits,
+     * completes, and is purged (or swept by retention) before this batch commits
+     * would make `wf:<id>` absent again, matching `expectedValue: null`. That gap
+     * is now closed by {@link duplicateIdGenerationCondition} below, an ADDITIONAL
+     * condition on a durable per-id generation counter a purge bumps but never
+     * resets — see its own doc for the mechanism.
      */
     duplicateIdCondition: ConditionalBatchCondition;
+    /**
+     * ADDITIONAL compare-and-swap precondition on the observed `wf-gen:<id>`
+     * bytes, closing the residual ABA hole {@link duplicateIdCondition} cannot
+     * detect (WFT-153, following WFT-152). `duplicateIdCondition` compares a
+     * VALUE, so it cannot tell "this id was never used" from "a run existed
+     * here and was purged" — if a racing winner completes and is purged before
+     * this batch commits, `wf:<id>` looks absent again and `duplicateIdCondition`
+     * alone would match. `wf-gen:<id>` is bumped in the SAME atomic batch that
+     * deletes `wf:<id>` on purge (`workflow-generation-fence.ts`) and is never
+     * otherwise touched, so a purge landing in the read-to-commit gap changes
+     * this key even though `wf:<id>` reads the same — the stale loser's
+     * condition on the pre-purge generation bytes fails where the value-only
+     * comparison could not detect it. See `storage/generation-keys.ts`.
+     */
+    duplicateIdGenerationCondition: ConditionalBatchCondition;
+    /**
+     * The exact `wf-gen:<id>` bytes {@link duplicateIdGenerationCondition} was
+     * built from, threaded through to {@link prepareTerminalRunPurge} so a
+     * `'start-new'` restart's own displacing purge bumps the generation from
+     * this SAME observed value rather than a second, independent read. This 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.
+     */
+    observedGenerationBytes: Uint8Array | null;
 };
 /**
  * The decision for a start whose id was GENERATED rather than caller-supplied. A
@@ -59,6 +83,8 @@ export type StartDuplicateIdDecision = {
 export declare const GENERATED_ID_START_DECISION: {
     readonly terminalRunToPurge: null;
     readonly duplicateIdCondition: undefined;
+    readonly duplicateIdGenerationCondition: undefined;
+    readonly observedGenerationBytes: null;
 };
 /**
  * Decide what a caller-supplied workflow id that already has a persisted record
@@ -86,9 +112,53 @@ export declare const GENERATED_ID_START_DECISION: {
  * batch. The returned {@link StartDuplicateIdDecision} therefore carries a
  * `duplicateIdCondition` holding the exact bytes seen here, so that batch can be
  * conditioned on them — turning that window into a lost compare-and-swap rather
- * than a blind overwrite (WFT-152).
+ * than a blind overwrite (WFT-152). It also reads `wf-gen:<id>` in the SAME pass
+ * and carries `duplicateIdGenerationCondition`/`observedGenerationBytes` (WFT-153),
+ * closing the residual ABA window a value-only condition cannot detect — see that
+ * field's own doc.
  */
 export declare function resolveTerminalConflictForRestart(internals: EngineInternals, workflowId: string, options: StartWorkflowOptions | undefined): Promise<StartDuplicateIdDecision>;
+/**
+ * The `'reattach-only'`/`'bulk-retry-only'` fence for `startWorkflow`'s
+ * `skipAdmissionIdCheck` parameter (WFT-95 TOCTOU fix). Call immediately
+ * after {@link resolveTerminalConflictForRestart} resolves.
+ *
+ * Both call sites reach `startWorkflow` after a separate, non-atomic read
+ * confirmed an already-persisted record they mean to replay or replace — but
+ * that confirmation and `resolveTerminalConflictForRestart`'s own atomic read
+ * are not the same read:
+ *
+ * - `dispatchChildWorkflowStart()`'s crash-reattach retry confirms a matching
+ *   persisted child via `loadWorkflowState()`, then leaves
+ *   `options.onTerminalConflict` unset — so `resolveTerminalConflictForRestart`
+ *   either finds the record still there (throws {@link WorkflowAlreadyExistsError},
+ *   this function is never reached: the expected, unraced reattach) or gone
+ *   (`terminalRunToPurge: null`, the ordinary fresh-create branch).
+ * - `retryFailedWorkflow()`'s checkpoint-absent fallback (`bulk-operations-retry.ts`)
+ *   confirms a `failed` record via its own `loadWorkflowState()`, then always
+ *   sets `options.onTerminalConflict: 'start-new'` — so
+ *   `resolveTerminalConflictForRestart` either finds the SAME terminal record
+ *   still there (returns its bytes as `terminalRunToPurge`, the expected,
+ *   unraced purge-and-replace) or finds it gone (`terminalRunToPurge: null`,
+ *   the same ordinary fresh-create branch).
+ *
+ * Under `ownership: 'workflow-lease'`, another engine can purge the matched
+ * record in the window between either call site's own confirmation read and
+ * `resolveTerminalConflictForRestart`'s. Being called with a `'reattach-only'`
+ * or `'bulk-retry-only'` `skipAdmissionIdCheck` and a `null` `terminalRunToPurge`
+ * therefore means the race happened: there is nothing left to reattach to or
+ * replace, so this re-runs strict admission rather than let a bypassed
+ * `.`/`..` id fall through into a genuinely fresh create. `coerceStartWorkflowId`
+ * throws the same `StartWorkflowValidationError` strict admission would have
+ * thrown on the caller's very first (non-retry) attempt — a clean,
+ * deterministic rejection instead of a silently created reserved-id run.
+ *
+ * A no-op for every other `skipAdmissionIdCheck` value: `true` (schedule
+ * drain) applies unconditionally and never calls this, and `undefined`
+ * (every public start surface) already went through strict admission in
+ * `prepareStartWorkflow`.
+ */
+export declare function enforceReplayOnlyIdFence(skipAdmissionIdCheck: boolean | 'reattach-only' | 'bulk-retry-only' | undefined, workflowId: string, terminalRunToPurge: WorkflowState | null): void;
 /**
  * Prepare a prior terminal run for displacement by a `'start-new'` restart WITHOUT
  * committing the destructive delete. Returns the storage delete operations (for the
@@ -98,5 +168,14 @@ export declare function resolveTerminalConflictForRestart(internals: EngineInter
  * entries. `clearPurgedWorkflowInMemoryState` runs `cleanupWaiters` to settle the
  * old run's pending signal/update/sleep waiters; it only needs
  * `swallowPromiseRejection`, which `LifecycleCallbacks` already exposes.
+ *
+ * Also appends the `wf-gen:<id>` bump PUT operation (WFT-153), built from
+ * `observedGenerationBytes` — the SAME bytes `resolveTerminalConflictForRestart`
+ * already read for `duplicateIdGenerationCondition` — rather than a second,
+ * independent read. Reusing that one observed value for both the outer CAS
+ * condition and the bump amount is what makes this restart's own commit
+ * 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 (see `duplicateIdGenerationCondition`'s doc).
  */
-export declare function prepareTerminalRunPurge(internals: EngineInternals, state: WorkflowState, callbacks: LifecycleCallbacks): Promise<BatchOperation[]>;
+export declare function prepareTerminalRunPurge(internals: EngineInternals, state: WorkflowState, callbacks: LifecycleCallbacks, observedGenerationBytes: Uint8Array | null): Promise<BatchOperation[]>;

package/dist/core/engine/lifecycle/start-terminal-conflict-purge.js

@@ -1,4 +1,5 @@
 import { KEYS, storageHas } from "../../../storage/interface.js";
+import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
 import {
   clearPurgedWorkflowInMemoryState,
   collectWorkflowPurgeDeleteOperations
@@ -6,16 +7,27 @@ import {
 import { WorkflowAlreadyExistsError, WorkflowTeardownPendingError } from "../errors.js";
 import { cleanupWaiters } from "../termination/cleanup.js";
 import { decodeWorkflowState, isTerminalWorkflowStatus } from "../validation.js";
+import { buildWorkflowGenerationBumpOperation } from "../workflow-generation-fence.js";
 export const GENERATED_ID_START_DECISION = {
   terminalRunToPurge: null,
-  duplicateIdCondition: void 0
+  duplicateIdCondition: void 0,
+  duplicateIdGenerationCondition: void 0,
+  observedGenerationBytes: null
 };
 export async function resolveTerminalConflictForRestart(internals, workflowId, options) {
-  const key = KEYS.workflow(workflowId), existingBytes = await internals.storage.get(key);
+  const key = KEYS.workflow(workflowId), generationKey = KEYS.workflowGeneration(workflowId), [existingBytes, observedGenerationBytes] = await Promise.all([
+    internals.storage.get(key),
+    internals.storage.get(generationKey)
+  ]), duplicateIdGenerationCondition = {
+    key: generationKey,
+    expectedValue: observedGenerationBytes
+  };
   if (existingBytes === null)
     return {
       terminalRunToPurge: null,
-      duplicateIdCondition: { key, expectedValue: null }
+      duplicateIdCondition: { key, expectedValue: null },
+      duplicateIdGenerationCondition,
+      observedGenerationBytes
     };
   if (options?.onTerminalConflict !== "start-new")
     throw new WorkflowAlreadyExistsError(workflowId);
@@ -26,13 +38,20 @@ export async function resolveTerminalConflictForRestart(internals, workflowId, o
     throw new WorkflowTeardownPendingError(workflowId);
   return {
     terminalRunToPurge: existingState,
-    duplicateIdCondition: { key, expectedValue: existingBytes }
+    duplicateIdCondition: { key, expectedValue: existingBytes },
+    duplicateIdGenerationCondition,
+    observedGenerationBytes
   };
 }
-export async function prepareTerminalRunPurge(internals, state, callbacks) {
+export function enforceReplayOnlyIdFence(skipAdmissionIdCheck, workflowId, terminalRunToPurge) {
+  if ((skipAdmissionIdCheck === "reattach-only" || skipAdmissionIdCheck === "bulk-retry-only") && terminalRunToPurge === null)
+    coerceStartWorkflowId(workflowId, "options.id");
+}
+export async function prepareTerminalRunPurge(internals, state, callbacks, observedGenerationBytes) {
   const cleanupWaitersForStart = (id) => cleanupWaiters(internals, id, {
     swallowPromiseRejection: callbacks.swallowPromiseRejection
   }), deleteOperations = await collectWorkflowPurgeDeleteOperations(internals, state);
+  deleteOperations.push(buildWorkflowGenerationBumpOperation(state.id, observedGenerationBytes));
   clearPurgedWorkflowInMemoryState(internals, state.id, cleanupWaitersForStart);
   return deleteOperations;
 }

package/dist/core/engine/lifecycle/start.d.ts

@@ -1,5 +1,5 @@
 import type { BatchOperation } from '../../../storage/interface.ts';
-import type { StartOptions, StartWorkflowOptions } from '../../types.ts';
+import type { StartWorkflowOptions } from '../../types.ts';
 import { type WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
 import { type LifecycleCallbacks } from './shared.ts';
@@ -19,5 +19,42 @@ export declare function startWorkflow(internals: EngineInternals, type: string,
  * `undefined` (the default, every non-schedule start) is byte-for-byte
  * the pre-WFT-20 admission path.
  */
-revisionOverride?: string): Promise<WorkflowHandle>;
-export declare function resolveScheduledStartAt(internals: EngineInternals, options: StartOptions | undefined, submissionTime: number, callbacks: LifecycleCallbacks): number | undefined;
+revisionOverride?: string, 
+/**
+ * Internal-only, never part of the public `StartOptions` type (WFT-95).
+ * When truthy, `options.id` skips strict fresh-admission validation
+ * (`assertValidWorkflowId`'s `.`/`..` rejection) and is instead validated
+ * with the decode-compatible `assertDecodableWorkflowId`. This exists
+ * ONLY to replay an id that was already durably accepted before strict
+ * admission existed — never to let a genuinely fresh caller admit `.`/`..`.
+ *
+ * Set from exactly three internal call sites, all replaying an
+ * already-persisted id rather than admitting a new one:
+ *   - `drainQueuedScheduleRun()` (via `ScheduledRunStartOptions.skipAdmissionIdCheck`,
+ *     threaded through `startScheduledRun()`), which restarts a schedule's
+ *     persisted `queuedRuns[].workflowId` — safe unconditionally (`true`),
+ *     since a queued run created after this fix was already validated as
+ *     non-`.`/`..` at schedule-admission time, so relaxing the check here
+ *     is a no-op for it and only matters for a historical pre-WFT-95 queued run.
+ *   - `retryFailedWorkflow()`'s checkpoint-absent fallback (`bulk-operations-retry.ts`),
+ *     which rebuilds an already-persisted, already-validated-at-the-time
+ *     `workflowId` from its stored input via `onTerminalConflict: 'start-new'`.
+ *     Passes the literal `'bulk-retry-only'` rather than `true` — see
+ *     {@link enforceReplayOnlyIdFence}'s doc comment for the TOCTOU race that
+ *     value fences: the retry's own confirmation read and
+ *     `resolveTerminalConflictForRestart`'s atomic read are not the same
+ *     read, so a concurrent purge under `ownership: 'workflow-lease'` can
+ *     leave nothing to purge-and-replace by the time this runs.
+ *   - `dispatchChildWorkflowStart()`'s crash-reattach retry, which passes
+ *     the literal `'reattach-only'` rather than `true` — see
+ *     {@link enforceReplayOnlyIdFence}'s doc comment for the same TOCTOU
+ *     race (this one only *speculatively* matched an existing record
+ *     before this call, unlike the schedule-drain site above).
+ *
+ * Every other caller (REST, JSON-RPC, direct `engine.start()`,
+ * `engine.startOrSignal()`, a fresh `ctx.startChild()`) omits this
+ * parameter and gets the strict check, because it is not part of
+ * `StartOptions`/`StartWorkflowOptions` and therefore cannot be set from
+ * any public surface.
+ */
+skipAdmissionIdCheck?: boolean | 'reattach-only' | 'bulk-retry-only'): Promise<WorkflowHandle>;

package/dist/core/engine/lifecycle/start.js

@@ -1,11 +1,8 @@
 import { assertPayloadWithinLimit } from "../../payload-size.js";
-import { normalizeStorageTimestamp } from "../../scheduler.js";
 import {
-  StartWorkflowValidationError,
-  assertExclusiveStartWorkflowOptions,
   assertValidOnTerminalConflict,
-  coerceStartWorkflowId,
-  coerceStartWorkflowTimestamp
+  coerceReplayWorkflowId,
+  coerceStartWorkflowId
 } from "../../start-workflow-validation.js";
 import {
   releaseInFlightStart,
@@ -33,6 +30,7 @@ import {
   resolveCachedStartRevision,
   resolveStartRevisionUncached
 } from "./start-revision-resolution.js";
+import { resolveScheduledStartAt } from "./start-schedule-timing.js";
 import {
   applyRestartLineage,
   createInitialCheckpoint,
@@ -40,6 +38,7 @@ import {
   parseStartOptionDuration
 } from "./start-state.js";
 import {
+  enforceReplayOnlyIdFence,
   GENERATED_ID_START_DECISION,
   prepareTerminalRunPurge,
   resolveTerminalConflictForRestart
@@ -47,8 +46,8 @@ import {
 export async function start(internals, type, input, options, callbacks) {
   return startWorkflow(internals, type, input, options, void 0, callbacks);
 }
-function prepareStartWorkflow(internals, options, callbacks) {
-  const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
+function prepareStartWorkflow(internals, options, callbacks, skipAdmissionIdCheck) {
+  const callerProvidedId = options?.id !== void 0, workflowId = options?.id !== void 0 ? skipAdmissionIdCheck ? coerceReplayWorkflowId(options.id, "options.id") : coerceStartWorkflowId(options.id, "options.id") : crypto.randomUUID(), parentHeaders = internals.pendingParentHeaders;
   internals.pendingParentHeaders = void 0;
   const pendingExecutionStateOwnerId = internals.pendingExecutionStateOwnerId, executionStateOwnerId = pendingExecutionStateOwnerId === null ? void 0 : pendingExecutionStateOwnerId ?? workflowId;
   internals.pendingExecutionStateOwnerId = void 0;
@@ -92,10 +91,10 @@ function resolveAndReserveStartRegistration(internals, type, revisionOverride, c
     resolvedRevision: revisionOverride
   }));
 }
-export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations, revisionOverride) {
+export async function startWorkflow(internals, type, input, options, additionalStartOperations, callbacks, buildIdempotentStartOperations, revisionOverride, skipAdmissionIdCheck) {
   assertServicesSupportedForMode(internals, options);
   assertValidOnTerminalConflict(options);
-  const preparation = prepareStartWorkflow(internals, options, callbacks), {
+  const preparation = prepareStartWorkflow(internals, options, callbacks, Boolean(skipAdmissionIdCheck)), {
     workflowId,
     callerProvidedId,
     parentHeaders,
@@ -117,9 +116,16 @@ export async function startWorkflow(internals, type, input, options, additionalS
       resolvedRevision
     } = await resolveAndReserveStartRegistration(internals, type, revisionOverride, callbacks);
     inFlightRevision = reservedRevision;
-    const workflowConcurrency = registration.concurrency, revision = resolveCachedStartRevision(internals, type, resolvedRevision) ?? await resolveStartRevisionUncached(internals, type), { terminalRunToPurge, duplicateIdCondition } = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : GENERATED_ID_START_DECISION, versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, revision, options, preparation.normalizedTags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks);
+    const workflowConcurrency = registration.concurrency, revision = resolveCachedStartRevision(internals, type, resolvedRevision) ?? await resolveStartRevisionUncached(internals, type), {
+      terminalRunToPurge,
+      duplicateIdCondition,
+      duplicateIdGenerationCondition,
+      observedGenerationBytes
+    } = callerProvidedId ? await resolveTerminalConflictForRestart(internals, workflowId, options) : GENERATED_ID_START_DECISION;
+    enforceReplayOnlyIdFence(skipAdmissionIdCheck, workflowId, terminalRunToPurge);
+    const versionTuple = createWorkflowVersionTuple(internals, registration, callbacks), state = createInitialWorkflowState(internals, workflowId, type, input, versionTuple, revision, options, preparation.normalizedTags, executionStateOwnerId, parentWorkflowId, parentWorkflowExecutionToken, delayedStartTimer, callbacks);
     applyRestartLineage(state, terminalRunToPurge);
-    const checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks) : void 0;
+    const checkpoint = createInitialCheckpoint(internals, workflowId, versionTuple.workflowVersion, options, callbacks), workflowStartHeaders = runWorkflowStartInterceptor(internals, workflowId, type, input, parentHeaders, callbacks), persistedWorkflowStartHeaders = selectPersistedWorkflowStartHeaders(workflowStartHeaders), purgeDeleteOperations = terminalRunToPurge !== null ? await prepareTerminalRunPurge(internals, terminalRunToPurge, callbacks, observedGenerationBytes) : void 0;
     internals.checkpoints.set(workflowId, checkpoint);
     setWorkflowStartHeaders(internals, workflowId, workflowStartHeaders, callbacks);
     internals.workflowVersionTuples.set(workflowId, versionTuple);
@@ -136,7 +142,8 @@ export async function startWorkflow(internals, type, input, options, additionalS
       buildWorkflowConcurrencyStartOperations: workflowConcurrency === void 0 ? void 0 : () => buildWorkflowConcurrencyStartOperations(internals, type, workflowId, input, workflowConcurrency),
       callbacks,
       purgeDeleteOperations,
-      duplicateIdCondition
+      duplicateIdCondition,
+      duplicateIdGenerationCondition
     }, buildIdempotentStartOperations);
     if (options?.services !== void 0) {
       internals.workflowServices.set(workflowId, options.services);
@@ -163,17 +170,3 @@ export async function startWorkflow(internals, type, input, options, additionalS
       rollbackTransientStartState(internals, workflowId);
   }
 }
-export function resolveScheduledStartAt(internals, options, submissionTime, callbacks) {
-  assertExclusiveStartWorkflowOptions(options?.startAt, options?.startAfter);
-  if (options?.startAt !== void 0)
-    return coerceStartWorkflowTimestamp(options.startAt, "options.startAt");
-  if (options?.startAfter !== void 0) {
-    const startAfterMilliseconds = parseStartOptionDuration(internals, options.startAfter, "options.startAfter", callbacks);
-    try {
-      return normalizeStorageTimestamp(submissionTime + startAfterMilliseconds, "options.startAfter");
-    } catch {
-      throw new StartWorkflowValidationError("options.startAfter must resolve to a finite, non-negative start time");
-    }
-  }
-  return;
-}

package/dist/core/engine/lifecycle/transition.d.ts

@@ -1,6 +1,7 @@
 import type { ForkOptions } from '../../types.ts';
 import type { WorkflowHandle } from '../handles.ts';
 import type { EngineInternals } from '../internals.ts';
+import { type FreshResumeClaimTracker } from './resume.ts';
 import { type LifecycleCallbacks, type RecoverAllOptions } from './shared.ts';
 export declare function recoverAll(internals: EngineInternals, callbacks: LifecycleCallbacks, options?: RecoverAllOptions): Promise<WorkflowHandle[]>;
 /** Options for {@link resume}. */
@@ -16,6 +17,14 @@ export type ResumeOptions = {
      * `engine.resume()` leaves it `false` — nothing was deposed there.
      */
     readonly forceReplayFromStorage?: boolean;
+    /**
+     * Forwarded to `resumeWorkflowFromStorage()`'s matching options — see
+     * `ResumeFromStorageOptions` (WFT-134 issue D). Set by
+     * `recoverEntryOrIsolateFailure` only; unset for the local-ownership fast
+     * path above, which never reaches that function.
+     */
+    readonly deferClaimReleaseOnRejection?: boolean;
+    readonly freshClaimTracker?: FreshResumeClaimTracker;
 };
 export declare function resume(internals: EngineInternals, workflowId: string, callbacks: LifecycleCallbacks, onRecoveredWorkflow?: RecoverAllOptions['onRecoveredWorkflow'], options?: ResumeOptions): Promise<WorkflowHandle>;
 export declare function fork(internals: EngineInternals, sourceWorkflowId: string, options: ForkOptions | undefined, callbacks: LifecycleCallbacks): Promise<WorkflowHandle>;

package/dist/core/engine/lifecycle/transition.js

@@ -1,17 +1,12 @@
 import { KEYS } from "../../../storage/interface.js";
 import { deserializeCheckpoint, serializeCheckpoint } from "../../checkpoint.js";
-import { RegExpExtensionDecodeError } from "../../codec/extension-codec.js";
 import { EMPTY_EVENT_HEAD } from "../../event-log.js";
 import { WorkflowRecoverySkippedEvent } from "../../events.js";
-import { VersionMismatchError } from "../../versioning.js";
 import { forgetCommittedCheckpointBytes } from "../checkpoint-commit-snapshots.js";
 import { hydrateCheckpointReplayState } from "../checkpoint-replay.js";
-import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.js";
 import { resolveExecutableRegistrationOrRenamedNotFound } from "../dynamic-source-execution.js";
 import { WorkflowTypeNotRegisteredForRecoveryError } from "../errors.js";
 import { commitFencedEngineWrite } from "../fenced-write.js";
-import { WorkflowClaimUnavailableError } from "../lease-errors.js";
-import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
 import { normalizeForkStep, selectPersistedWorkflowStartHeaders } from "../state-utilities.js";
 import { loadWorkflowState } from "../storage-io.js";
 import { decodeWorkflowState } from "../validation.js";
@@ -23,6 +18,7 @@ import {
   createForkedWorkflowState
 } from "./fork-helpers.js";
 import { derivePreparedExecutionState } from "./persist.js";
+import { isolateRecoveryFailure } from "./recovery-isolation.js";
 import {
   buildRecoveryRevisionGroups,
   classifyRevisionGroups,
@@ -34,6 +30,7 @@ import {
   loadWorkflowStartHeaders,
   setWorkflowStartHeaders
 } from "./shared.js";
+import { releaseFreshlyAcquiredResumeClaim } from "./standalone-claim-acquire.js";
 function isWorkflowSideRecordKey(key) {
   return key.includes(":ckpt") || key.includes(":offload") || key.includes(":archive") || key.includes(":timeline:");
 }
@@ -67,28 +64,19 @@ async function preflightRecoverAll(internals, callbacks) {
   return result;
 }
 async function recoverEntryOrIsolateFailure(internals, workflowId, callbacks, options) {
+  const freshClaimTracker = { epoch: null };
   try {
-    return await resume(internals, workflowId, callbacks, options?.onRecoveredWorkflow);
+    return await resume(internals, workflowId, callbacks, options?.onRecoveredWorkflow, {
+      deferClaimReleaseOnRejection: !0,
+      freshClaimTracker
+    });
   } catch (error) {
-    if (error instanceof RegExpExtensionDecodeError) {
-      await callbacks.failWorkflowForCheckpointDecodeError(workflowId, error);
-      return null;
-    }
-    if (error instanceof VersionMismatchError && options?.versionMismatchPolicy !== "throw") {
-      await callbacks.failWorkflowForVersionMismatch(workflowId, error);
-      return null;
-    }
-    if (error instanceof WorkflowClaimUnavailableError)
-      return null;
-    if (error instanceof WorkflowRevisionUnavailableError) {
-      await callbacks.failWorkflowForRevisionUnavailable(workflowId, error);
-      return null;
+    try {
+      return await isolateRecoveryFailure(workflowId, callbacks, options, error);
+    } finally {
+      if (freshClaimTracker.epoch !== null)
+        await releaseFreshlyAcquiredResumeClaim(internals, workflowId, freshClaimTracker.epoch);
     }
-    if (error instanceof DynamicWorkflowSourceUnavailableError) {
-      await callbacks.failWorkflowForUnavailableDynamicSource(workflowId, error);
-      return null;
-    }
-    throw error;
   }
 }
 export async function recoverAll(internals, callbacks, options) {
@@ -125,7 +113,14 @@ export async function resume(internals, workflowId, callbacks, onRecoveredWorkfl
       return callbacks.getHandle(workflowId);
     }
   }
-  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks, onRecoveredWorkflow);
+  return resumeWorkflowFromStorage(internals, workflowId, !0, callbacks, onRecoveredWorkflow, {
+    ...options?.deferClaimReleaseOnRejection !== void 0 && {
+      deferClaimReleaseOnRejection: options.deferClaimReleaseOnRejection
+    },
+    ...options?.freshClaimTracker !== void 0 && {
+      freshClaimTracker: options.freshClaimTracker
+    }
+  });
 }
 export async function fork(internals, sourceWorkflowId, options, callbacks) {
   const sourceState = await loadWorkflowState(internals, sourceWorkflowId);

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

@@ -1,6 +1,7 @@
 export { EMPTY_STORAGE_VALUE, createWorkflowHandle, loadTerminalCleanupTrackedState, loadWorkflowStartHeaders, normalizeStartWorkflowTags, processPendingUpdatesAfterReplay, setWorkflowStartHeaders, type LifecycleCallbacks, type RecoverAllOptions, type RecoveredWorkflowInfo, } from './lifecycle/shared.ts';
 export { createWorkflowVersionTuple, derivePreparedExecutionState, prepareResumeState, throwVersionMismatch, workflowStateWithVersionTuple, workflowVersionTupleFromState, } from './lifecycle/persist.ts';
-export { resolveScheduledStartAt, start, startWorkflow } from './lifecycle/start.ts';
+export { resolveScheduledStartAt } from './lifecycle/start-schedule-timing.ts';
+export { start, startWorkflow } from './lifecycle/start.ts';
 export { applyRestartLineage, createInitialCheckpoint, createInitialWorkflowState, parseStartOptionDuration, } from './lifecycle/start-state.ts';
 export { startOrSignal, startWithIdempotency, type StartOrSignalCallbacks, type StartOrSignalResult, } from './lifecycle/start-or-signal.ts';
 export { buildInitialSearchAttributeOperations, buildStartBatchOperations, validateSearchAttributes, } from './lifecycle/start-batch.ts';

package/dist/core/engine/lifecycle.js

@@ -15,7 +15,8 @@ export {
   workflowStateWithVersionTuple,
   workflowVersionTupleFromState
 } from "./lifecycle/persist.js";
-export { resolveScheduledStartAt, start, startWorkflow } from "./lifecycle/start.js";
+export { resolveScheduledStartAt } from "./lifecycle/start-schedule-timing.js";
+export { start, startWorkflow } from "./lifecycle/start.js";
 export {
   applyRestartLineage,
   createInitialCheckpoint,

package/dist/core/engine/schedule-overlap.js

@@ -44,7 +44,8 @@ export async function drainQueuedScheduleRun(state, callbacks, completedWorkflow
     workflowId: queuedRun.workflowId,
     ...queuedRun.occurrence !== void 0 && { occurrence: queuedRun.occurrence },
     scheduleStateAfterStart: stateAfterStart,
-    ...completedWorkflowId !== void 0 && { completedWorkflowId }
+    ...completedWorkflowId !== void 0 && { completedWorkflowId },
+    skipAdmissionIdCheck: !0
   });
   return stateAfterStart;
 }

package/dist/core/engine/schedule-run.d.ts

@@ -9,6 +9,16 @@ export type ScheduledRunStartOptions = {
     scheduleStateAfterStart?: ScheduleState;
     /** Prior terminal run whose transient schedule metadata is now settled. */
     completedWorkflowId?: string;
+    /**
+     * Internal only (WFT-95). Set by `drainQueuedScheduleRun()` when `workflowId`
+     * is a persisted `queuedRuns[].workflowId` being replayed, not a freshly
+     * minted one — safe unconditionally, since a post-fix queued run was already
+     * validated as non-`.`/`..` at schedule-admission time (relaxing the check
+     * here is then a no-op), and it is what lets a legacy pre-WFT-95 queued run
+     * whose id is `.`/`..` keep draining instead of pausing the schedule.
+     * Threaded straight through to `startWorkflow`'s `skipAdmissionIdCheck`.
+     */
+    skipAdmissionIdCheck?: boolean;
 };
 /**
  * Launch one scheduled occurrence's workflow run and emit `schedule:fired`.

package/dist/core/engine/schedule-run.js

@@ -50,7 +50,7 @@ export async function startScheduledRun(internals, state, callbacks, options = {
       internals.workflowServices.set(workflowId, resolution.services);
   }
   internals.workflowsNeedingTerminalCleanup.add(workflowId);
-  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations, buildPinnedRevisionOverride(state));
+  await callbacks.startWorkflow(state.workflowType, state.input, { id: workflowId }, scheduleRunOperations, buildPinnedRevisionOverride(state), options.skipAdmissionIdCheck);
   internals.engine.dispatchEvent(new ScheduleFiredEvent(state.id, workflowId, internals.options.getNow(), occurrence));
   if (resolution !== null && resolution.status === "unavailable") {
     const unavailableError = unavailableServicesError(workflowId, resolution.reason);

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

@@ -10,10 +10,19 @@ export type RefreshedScheduleState = {
     currentWorkflowState: WorkflowState | null;
 };
 export type ScheduleCallbacks = {
-    /** `revisionOverride` (WFT-20) is the exact revision a `revisionPolicy: 'pinned'` occurrence must resolve against; `undefined` for an `'active-at-fire'` schedule. */
+    /**
+     * `revisionOverride` (WFT-20) is the exact revision a `revisionPolicy: 'pinned'`
+     * occurrence must resolve against; `undefined` for an `'active-at-fire'` schedule.
+     *
+     * `skipAdmissionIdCheck` (WFT-95, internal only) is threaded straight through to
+     * `startWorkflow`'s parameter of the same name — see its doc comment. Set only when
+     * replaying a schedule's already-persisted `queuedRuns[].workflowId` via
+     * `drainQueuedScheduleRun()`; every other schedule-run start (a fresh cadence tick,
+     * a `cancel-running` replacement) omits it and gets strict id admission.
+     */
     startWorkflow: (type: string, input: unknown, options: {
         id: string;
-    }, additionalStartOperations?: BatchOperation[], revisionOverride?: string) => Promise<void>;
+    }, additionalStartOperations?: BatchOperation[], revisionOverride?: string, skipAdmissionIdCheck?: boolean) => Promise<void>;
     loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null | undefined>;
     cancelWorkflow: (workflowId: string) => Promise<void>;
     getWorkflowResult: (workflowId: string) => Promise<unknown>;

package/dist/core/engine/termination/complete.js

@@ -177,7 +177,7 @@ async function releaseWorkflowClaimAfterTerminalSettlement(internals, workflowId
   if (registry.currentEpoch(workflowId) !== capturedEpoch)
     return;
   try {
-    await registry.release(workflowId);
+    await registry.release(workflowId, capturedEpoch);
   } catch {}
 }
 export async function completeWorkflow(internals, workflowId, result, callbacks) {

package/dist/core/engine/termination/suspend.js

@@ -6,6 +6,7 @@ import { dropQueuedInlineWorkflowStart } from "../inline-launch-queue.js";
 import { buildWorkflowVisibilityIndexTransition } from "../workflow-indexes.js";
 import { evictSuspendedWorkflowWaiters } from "./cleanup.js";
 export async function suspendWorkflow(internals, workflowId, callbacks) {
+  const capturedClaimEpochForForget = internals.workflowClaimRegistry?.currentEpoch(workflowId) ?? null;
   if (!await callbacks.runSerializedWorkflowStateWrite(workflowId, async () => {
     const state = await callbacks.loadWorkflowState(workflowId);
     if (!state || state.status !== "running")
@@ -26,6 +27,8 @@ export async function suspendWorkflow(internals, workflowId, callbacks) {
     return !0;
   }))
     return;
+  if (internals.workflowClaimRegistry !== null && capturedClaimEpochForForget !== null && internals.workflowClaimRegistry.currentEpoch(workflowId) === capturedClaimEpochForForget)
+    internals.workflowClaimRegistry.forgetLocalClaim(workflowId);
   const event = new WorkflowSuspendedEvent(workflowId);
   callbacks.dispatchEvent(event);
   callbacks.forwardEventToHandle(workflowId, event);

package/dist/core/engine/validation/schedule.d.ts

@@ -6,8 +6,32 @@ export declare function isValidScheduleTimestamp(value: unknown): value is numbe
 export declare function isValidScheduleStatus(value: unknown): value is ScheduleStatus;
 export declare function isValidScheduleOverlapPolicy(value: unknown): value is ScheduleOverlapPolicy;
 export declare function isValidScheduleRevisionPolicy(value: unknown): value is ScheduleRevisionPolicy;
+/**
+ * Whether `value` is a schedule-related workflow id that decoded persisted
+ * data may still carry. Deliberately reuses the pre-WFT-95 decode predicate
+ * (not the fresh-admission `.`/`..` rejection), because every caller of this
+ * function — `decodeScheduleIdentityFields`, `decodeScheduleRunMetadata`,
+ * and the persisted `currentWorkflowId`/`queuedRuns[].workflowId` fields in
+ * this module — reads already-persisted data. A schedule created before
+ * WFT-95 with `id: '.'` or `'..'` must remain decodable and keep firing
+ * after upgrade.
+ */
 export declare function isValidScheduleIdentifier(value: unknown): value is string;
-export declare function coerceScheduleId(scheduleId: string, fieldName: string): string;
+/**
+ * Coerce a caller-supplied `scheduleId` used to look up or control an
+ * already-persisted schedule — `getSchedule`, `pauseSchedule`,
+ * `resumeSchedule`, `cancelSchedule`, and `updateSchedule` all call this,
+ * never schedule creation (that admission path is
+ * `normalizeScheduleOptions`'s direct `coerceStartWorkflowId(options.id, …)`
+ * call, which keeps the strict `.`/`..` rejection). Deliberately uses the
+ * decode-compatible `assertDecodableWorkflowId`, not the admission-only
+ * `.`/`..` rejection (WFT-95 review): a schedule created before that
+ * rejection landed may already carry `id: '.'` or `'..'`, and callers must
+ * still be able to inspect, pause, resume, cancel, or update it instead of
+ * having every control operation reject a schedule they can't otherwise
+ * reach.
+ */
+export declare function coerceScheduleId(scheduleId: unknown, fieldName: string): string;
 /**
  * A recurrence specification normalized into the discriminated cadence the
  * engine persists. Interval periods are resolved to whole milliseconds.

package/dist/core/engine/validation/schedule.js

@@ -2,7 +2,7 @@ import { decode } from "../../codec.js";
 import { isRecord } from "../../debug-output.js";
 import { parseCronExpression } from "../../schedule.js";
 import { parseDuration } from "../../scheduler.js";
-import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
+import { assertDecodableWorkflowId, isDecodableWorkflowId } from "../../workflow-identifiers.js";
 import { decodeScheduleCadence } from "./schedule-cadence.js";
 import { SCHEDULE_OVERLAP_POLICIES, SCHEDULE_REVISION_POLICIES } from "./schedule-options.js";
 import { decodeScheduleRevisionPolicyFields } from "./schedule-revision.js";
@@ -28,17 +28,11 @@ export function isValidScheduleRevisionPolicy(value) {
   return typeof value === "string" && SCHEDULE_REVISION_POLICIES.has(value);
 }
 export function isValidScheduleIdentifier(value) {
-  if (typeof value !== "string")
-    return !1;
-  try {
-    coerceStartWorkflowId(value, "schedule id");
-    return !0;
-  } catch {
-    return !1;
-  }
+  return typeof value === "string" && isDecodableWorkflowId(value);
 }
 export function coerceScheduleId(scheduleId, fieldName) {
-  return coerceStartWorkflowId(scheduleId, fieldName);
+  assertDecodableWorkflowId(scheduleId, fieldName);
+  return scheduleId;
 }
 function normalizeIntervalEvery(every) {
   if (typeof every !== "string" && typeof every !== "number")