@lostgradient/weft 0.19.0 → 0.21.0

package/dist/core/engine/fenced-write.d.ts

@@ -1,5 +1,6 @@
 /**
- * Step-2 epoch fencing for `ownership: 'lease'` (issue #470).
+ * Step-2 epoch fencing for `ownership: 'lease'` (issue #470), extended by ADR
+ * 0002 to per-workflow fencing under `ownership: 'workflow-lease'`.
  *
  * Step 1 made a rolling deploy a clean lease handoff but added no correctness
  * backstop: a deposed zombie instance (GC pause, partition) that emerged after
@@ -15,6 +16,20 @@
  * from silently spinning on swallowed write losses, surface the deposition to the
  * operator, and release resources. They are not what makes the system safe.
  *
+ * ADR 0002 adds a SECOND, independent fencing token: `wf-owner-epoch:<workflowId>`.
+ * Every caller of {@link commitFencedEngineWrite} / {@link
+ * commitFencedEngineWriteAllowingPreconditionFailure} now states, via the
+ * required `workflowId` parameter, whether the write is scoped to one
+ * workflow's execution (pass its id) or is engine-scoped/cross-workflow (pass
+ * `null`) — an optional parameter would let a call site silently forget the
+ * fence, which is exactly the correctness hole this mechanism exists to close.
+ * Under `ownership: 'workflow-lease'` with a non-null `workflowId`, the write
+ * is fenced on THAT workflow's claim epoch instead of the global lease epoch;
+ * losing that fence deposes only that one workflow (warn + throw), never the
+ * whole engine. Under `'lease'` and `'none'`, and under `'workflow-lease'`
+ * with `workflowId: null`, behavior is byte-for-byte unchanged from Step 2 —
+ * `workflowId` is only consulted in the one new branch.
+ *
  * This module is allow-listed for import only from `src/core/engine/**`.
  */
 import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
@@ -31,37 +46,53 @@ import type { EngineInternals } from './internals.ts';
  * `pauseSchedule`, `resumeSchedule`, `cancelSchedule`, and `updateSchedule`) would
  * reach `resolveFenceEpochOrHalt` with no held epoch and be misreported as a
  * deposition (warn + teardown) rather than the true "lease not held yet"
- * condition. A no-op under `ownership: 'none'`.
+ * condition. A no-op under `ownership: 'none'` and under `ownership:
+ * 'workflow-lease'` — the analogous "claim not held yet" guard for a
+ * workflow-scoped write is a later stage's concern (folding `acquire()` into
+ * the enabling write), not this global-lease-only assertion.
  */
 export declare function assertLeaseHeldForEngineWork(internals: EngineInternals): void;
 /**
- * Commit an engine-generator-owned durable write, fenced on the held lease epoch
- * under `ownership: 'lease'` (a byte-for-byte no-op under `ownership: 'none'`). A
- * lost CAS race throws the caller-supplied `onLostRace` error so existing retry
- * semantics apply; a deposition halts the engine and throws
- * {@link EngineDeposedError}. The helper owns the batch-vs-conditionalBatch
- * decision — pass plain operations plus whatever base conditions you already need.
+ * Commit an engine-generator-owned durable write, fenced on the applicable
+ * epoch: the global lease epoch under `ownership: 'lease'`, this workflow's
+ * claim epoch under `ownership: 'workflow-lease'` when `workflowId` is
+ * non-null, or — under `'none'` and every other `workflowId`/mode
+ * combination — byte-for-byte unfenced. A lost CAS race throws the
+ * caller-supplied `onLostRace` error so existing retry semantics apply; a
+ * deposition halts (the engine under global `'lease'`, or just this one
+ * workflow under `'workflow-lease'`) and throws {@link EngineDeposedError}.
+ * The helper owns the batch-vs-conditionalBatch decision — pass plain
+ * operations plus whatever base conditions you already need.
  *
- * @param internals - the engine internals (ownership mode, lease manager, deposed flag)
+ * @param internals - the engine internals (ownership mode, lease manager,
+ *   workflow claim registry, deposed flag)
+ * @param workflowId - the workflow this write is scoped to, fenced on that
+ *   workflow's claim epoch under `ownership: 'workflow-lease'`; or `null` for
+ *   an engine-scoped/cross-workflow write, which is never fenced on a
+ *   per-workflow claim regardless of ownership mode. Required — there is no
+ *   default — so every call site states its scope explicitly.
  * @param operations - the durable operations to commit atomically
  * @param baseConditions - CAS conditions the caller already requires (may be empty)
  * @param onLostRace - builds the error thrown on a same-epoch lost CAS race
  */
-export declare function commitFencedEngineWrite(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
+export declare function commitFencedEngineWrite(internals: EngineInternals, workflowId: string | null, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[], onLostRace: () => Error): Promise<void>;
 /**
  * Like {@link commitFencedEngineWrite}, but the caller treats a base-precondition
  * failure as a legitimate outcome rather than an error — used by the idempotent
  * start path, where a `false` means a concurrent same-key caller already wrote the
  * record (resolve to the existing run) rather than "retry". Returns `true` when the
  * batch committed and `false` when a base condition failed. Deposition is still a
- * hard halt: if the epoch condition is the one that failed, this drives
- * {@link handleDeposition} and throws {@link EngineDeposedError} — a deposed engine
- * must never report a precondition-failure the caller would read as "already exists"
- * and silently move on.
+ * hard halt: if the epoch condition is the one that failed, this drives the
+ * applicable deposition path and throws {@link EngineDeposedError} — a deposed
+ * engine (or a deposed single workflow, under `workflow-lease`) must never report a
+ * precondition-failure the caller would read as "already exists" and silently
+ * move on.
  *
  * @param internals - the engine internals
+ * @param workflowId - see {@link commitFencedEngineWrite} — the workflow this
+ *   write is scoped to, or `null` for an engine-scoped write
  * @param operations - the durable operations to commit atomically
  * @param baseConditions - the caller's required CAS conditions (non-empty in
  *   practice — this path is for conditional starts, which always carry one)
  */
-export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;
+export declare function commitFencedEngineWriteAllowingPreconditionFailure(internals: EngineInternals, workflowId: string | null, operations: BatchOperation[], baseConditions: ConditionalBatchCondition[]): Promise<boolean>;

package/dist/core/engine/fenced-write.js

@@ -1,6 +1,6 @@
 import { KEYS, storageConditionalBatch } from "../../storage/interface.js";
 import { decodeEpoch } from "./lease-codec.js";
-import { handleDeposition } from "./lease-deposition.js";
+import { emitWorkflowClaimLostWarning, handleDeposition } from "./lease-deposition.js";
 import { EngineDeposedError, EngineLeaseNotHeldError } from "./lease-errors.js";
 export function assertLeaseHeldForEngineWork(internals) {
   if (internals.options.ownershipMode !== "lease")
@@ -8,7 +8,9 @@ export function assertLeaseHeldForEngineWork(internals) {
   if (!(!internals.deposed && internals.leaseManager !== null && internals.leaseManager.currentEpochBytes() !== null))
     throw new EngineLeaseNotHeldError;
 }
-async function fencedCommit(internals, operations, baseConditions) {
+async function fencedCommit(internals, workflowId, operations, baseConditions) {
+  if (internals.options.ownershipMode === "workflow-lease" && workflowId !== null)
+    return fencedCommitForWorkflow(internals, workflowId, operations, baseConditions);
   const epochBytes = resolveFenceEpochOrHalt(internals);
   if (epochBytes === null) {
     if (baseConditions.length === 0) {
@@ -41,12 +43,30 @@ function resolveFenceEpochOrHalt(internals) {
   }
   return epochBytes;
 }
-export async function commitFencedEngineWrite(internals, operations, baseConditions, onLostRace) {
-  if (await fencedCommit(internals, operations, baseConditions) === "lost-race")
+async function fencedCommitForWorkflow(internals, workflowId, operations, baseConditions) {
+  const epochBytes = internals.workflowClaimRegistry?.currentEpochBytes(workflowId) ?? null;
+  if (epochBytes === null)
+    haltWorkflowClaim(workflowId);
+  const conditions = [
+    ...baseConditions,
+    { key: KEYS.workflowOwnerEpoch(workflowId), expectedValue: epochBytes }
+  ];
+  if (await storageConditionalBatch(internals.storage, conditions, operations))
+    return "committed";
+  if (await isWorkflowDeposed(internals, workflowId, epochBytes))
+    haltWorkflowClaim(workflowId);
+  return "lost-race";
+}
+function haltWorkflowClaim(workflowId) {
+  emitWorkflowClaimLostWarning(workflowId);
+  throw new EngineDeposedError(workflowId);
+}
+export async function commitFencedEngineWrite(internals, workflowId, operations, baseConditions, onLostRace) {
+  if (await fencedCommit(internals, workflowId, operations, baseConditions) === "lost-race")
     throw onLostRace();
 }
-export async function commitFencedEngineWriteAllowingPreconditionFailure(internals, operations, baseConditions) {
-  return await fencedCommit(internals, operations, baseConditions) === "committed";
+export async function commitFencedEngineWriteAllowingPreconditionFailure(internals, workflowId, operations, baseConditions) {
+  return await fencedCommit(internals, workflowId, operations, baseConditions) === "committed";
 }
 function epochBytesEqual(a, b) {
   if (b === null || a.byteLength !== b.byteLength)
@@ -69,3 +89,16 @@ async function isDeposed(internals, heldEpochBytes) {
     return !0;
   return !epochBytesEqual(heldEpochBytes, currentEpochRaw);
 }
+async function isWorkflowDeposed(internals, workflowId, heldEpochBytes) {
+  let currentEpochRaw;
+  try {
+    currentEpochRaw = await internals.storage.get(KEYS.workflowOwnerEpoch(workflowId));
+  } catch {
+    return !0;
+  }
+  if (currentEpochRaw === null)
+    return !0;
+  if (decodeEpoch(currentEpochRaw) === null)
+    return !0;
+  return !epochBytesEqual(heldEpochBytes, currentEpochRaw);
+}

package/dist/core/engine/finalizer-state.d.ts

@@ -16,7 +16,9 @@ import type { EngineInternals } from './internals.ts';
  * the next checkpoint still flushes the staged op in the terminal batch, so the
  * finalizer always sees the resource id. The staged op inherits the lease-epoch
  * fence (#470) for free, since checkpoint and terminal commits route through
- * `commitFencedWorkflowStateOperations`.
+ * `commitSelfWorkflowStateOperations` (completion) or
+ * `commitExternalTerminalWorkflowStateOperations` (cancel/timeout/suspend —
+ * ADR 0002), both in `storage-io.ts`.
  *
  * Oversized payloads are rejected before staging (the same hostile-input guard
  * activity results use). A call made once the workflow is already terminalizing

package/dist/core/engine/handle-result.d.ts

@@ -4,5 +4,53 @@ import type { EngineInternals } from './internals.ts';
 export declare function createWorkflowHandleWithResultPromise(internals: EngineInternals, workflowId: string): WorkflowHandle;
 export declare function createWorkflowResultWaiter(internals: EngineInternals, workflowId: string): WorkflowResultWaiter;
 export declare function getWorkflowResultPromise(internals: EngineInternals, workflowId: string): Promise<unknown>;
-export declare function bootstrapWorkflowResultResolver(internals: EngineInternals, workflowId: string, waiter: WorkflowResultWaiter): Promise<void>;
+/**
+ * Result promise for a parent generator parked on `ctx.startChild()`'s
+ * default `parentClosePolicy: 'await'` — the ONLY intended caller (see
+ * `child-workflow.ts`'s `executeChildWorkflow`, which must call this instead
+ * of the plain `childHandle.result()` / `handle.result()` path). Identical to
+ * {@link getWorkflowResultPromise} except the waiter this settles is marked
+ * generator-owned for `parentWorkflowId`: under `ownership: 'workflow-lease'`
+ * a settle attempt first confirms `parentWorkflowId` still holds the claim
+ * generation it parked under (`confirmWakeOwnership`, `'child-completion'`),
+ * fencing duplicate generator advancement (WFT-79 F1) — see
+ * {@link bootstrapWorkflowResultResolver}. Top-level, non-generator callers
+ * must keep using {@link getWorkflowResultPromise}, which stays unfenced by
+ * design: cross-engine `handle.result()` polling has no generator to
+ * duplicate and must remain settleable from durable state alone.
+ *
+ * If `internals.resultResolvers` already holds a waiter for `workflowId` —
+ * e.g. an observational `handle.result()` caller got there first — that
+ * SHARED waiter is untouched: {@link fenceResultOnParentGeneration} wraps
+ * only THIS caller's derived promise, so the observational caller's own
+ * promise settles normally from the shared waiter regardless of the parent's
+ * claim generation. See that function's doc for why fencing lives on the
+ * parent's view instead of the shared waiter itself.
+ */
+export declare function getGeneratorOwnedWorkflowResultPromise(internals: EngineInternals, workflowId: string, parentWorkflowId: string): Promise<unknown>;
+/**
+ * Settle result waiters for workflows this engine does not own, whose terminal
+ * transition lands on another engine and so never touches this engine's
+ * in-memory resolver map.
+ *
+ * Exported for `backgroundTasks: 'manual'`, where no timer runs and the host
+ * drives every background step through an awaited `runMaintenance()`.
+ */
+export declare function pollPendingCrossEngineResultWaiters(internals: EngineInternals): Promise<void>;
+/**
+ * Outcome of one {@link bootstrapWorkflowResultResolver} attempt, used by
+ * this file's callers to decide whether to keep polling:
+ *
+ * - `'settled'`: the waiter was resolved or rejected.
+ * - `'pending'`: no terminal result yet (still running, or a transient read
+ *   failure under a guaranteed-retry ownership mode). Keep polling.
+ *
+ * A generator-owned caller's discarded parent generation needs no outcome
+ * here at all: `fenceResultOnParentGeneration` withholds settlement on that
+ * caller's own derived promise, independent of whether the SHARED waiter
+ * this function settles ever resolves.
+ */
+type ResultResolutionOutcome = 'settled' | 'pending';
+export declare function bootstrapWorkflowResultResolver(internals: EngineInternals, workflowId: string, waiter: WorkflowResultWaiter): Promise<ResultResolutionOutcome>;
 export declare function cacheHandle(internals: EngineInternals, workflowId: string, handle: WorkflowHandle): void;
+export {};

package/dist/core/engine/handle-result.js

@@ -1,6 +1,7 @@
 import { EngineDisposedError } from "./errors.js";
 import { WorkflowHandle } from "./handles.js";
-import { loadWorkflowResult, loadWorkflowState } from "./storage-io.js";
+import { deriveWorkflowResultFromState, loadWorkflowState } from "./storage-io.js";
+import { confirmWakeOwnership } from "./wake-ownership-guard.js";
 export function createWorkflowHandleWithResultPromise(internals, workflowId) {
   const handle = new WorkflowHandle(workflowId, internals.engine);
   cacheHandle(internals, workflowId, handle);
@@ -22,32 +23,106 @@ export function getWorkflowResultPromise(internals, workflowId) {
     return rejected;
   }
   const waiter = createWorkflowResultWaiter(internals, workflowId);
-  bootstrapWorkflowResultResolver(internals, workflowId, waiter);
+  bootstrapWorkflowResultResolver(internals, workflowId, waiter).then(() => scheduleCrossEngineResultPollIfPending(internals, workflowId, waiter));
   return waiter.promise;
 }
-export async function bootstrapWorkflowResultResolver(internals, workflowId, waiter) {
+export function getGeneratorOwnedWorkflowResultPromise(internals, workflowId, parentWorkflowId) {
+  return fenceResultOnParentGeneration(internals, parentWorkflowId, getWorkflowResultPromise(internals, workflowId));
+}
+function fenceResultOnParentGeneration(internals, parentWorkflowId, promise) {
+  const gate = Promise.withResolvers();
+  promise.then(async (value) => {
+    if (await parentStillOwnsGeneration(internals, parentWorkflowId))
+      gate.resolve(value);
+  }, async (error) => {
+    if (await parentStillOwnsGeneration(internals, parentWorkflowId))
+      gate.reject(error);
+  });
+  return gate.promise;
+}
+async function parentStillOwnsGeneration(internals, parentWorkflowId) {
   try {
-    const state = await loadWorkflowState(internals, workflowId);
-    if (linkToReplacementWaiter(internals, workflowId, waiter))
-      return;
-    if (!state) {
-      internals.resultResolvers.delete(workflowId);
-      waiter.reject(Error(`Workflow "${workflowId}" not found in storage`));
-      return;
-    }
-    if (state.status === "running" || state.status === "pending" || state.status === "suspended")
-      return;
+    return await confirmWakeOwnership(internals, parentWorkflowId, "child-completion") === "proceed";
+  } catch {
+    return !0;
+  }
+}
+function scheduleCrossEngineResultPollIfPending(internals, workflowId, waiter) {
+  if (internals.workflowClaimRegistry === null)
+    return;
+  if (internals.resultResolvers.get(workflowId) !== waiter)
+    return;
+  if (internals.options.backgroundTaskMode !== "automatic")
+    return;
+  const handle = setTimeout(() => {
+    internals.pendingResultPollTimers.delete(handle);
+    bootstrapWorkflowResultResolver(internals, workflowId, waiter).then(() => scheduleCrossEngineResultPollIfPending(internals, workflowId, waiter));
+  }, internals.options.workflowClaimRenewIntervalMs);
+  internals.pendingResultPollTimers.add(handle);
+  handle.unref?.();
+}
+export async function pollPendingCrossEngineResultWaiters(internals) {
+  if (internals.workflowClaimRegistry === null)
+    return;
+  const pending = Array.from(internals.resultResolvers.entries());
+  for (const [workflowId, waiter] of pending) {
+    if (await deferToLocalTerminalDeliveryIfPending(internals, workflowId, waiter))
+      continue;
     try {
-      const result = await loadWorkflowResult(internals, workflowId);
-      clearResultWaiter(internals, workflowId, waiter);
-      waiter.resolve(result);
-    } catch (error) {
-      clearResultWaiter(internals, workflowId, waiter);
-      waiter.reject(error);
-    }
+      await bootstrapWorkflowResultResolver(internals, workflowId, waiter);
+    } catch {}
+  }
+}
+function settleOrRetryOnTransientReadFailure(internals, workflowId, waiter, error) {
+  if (internals.workflowClaimRegistry === null) {
+    clearResultWaiter(internals, workflowId, waiter);
+    waiter.reject(error);
+    return "settled";
+  }
+  return "pending";
+}
+async function deferToLocalTerminalDeliveryIfPending(internals, workflowId, waiter) {
+  if (internals.workflowClaimRegistry?.currentEpoch(workflowId) == null)
+    return !1;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  return internals.resultResolvers.get(workflowId) !== waiter;
+}
+async function prepareToSettleTerminalWaiter(internals, workflowId, waiter) {
+  if (await deferToLocalTerminalDeliveryIfPending(internals, workflowId, waiter))
+    return "settled";
+  return "proceed";
+}
+export async function bootstrapWorkflowResultResolver(internals, workflowId, waiter) {
+  let state;
+  try {
+    state = await loadWorkflowState(internals, workflowId);
+  } catch (error) {
+    return settleOrRetryOnTransientReadFailure(internals, workflowId, waiter, error);
+  }
+  if (linkToReplacementWaiter(internals, workflowId, waiter))
+    return "settled";
+  if (!state) {
+    const outcome = await prepareToSettleTerminalWaiter(internals, workflowId, waiter);
+    if (outcome !== "proceed")
+      return outcome;
+    internals.resultResolvers.delete(workflowId);
+    waiter.reject(Error(`Workflow "${workflowId}" not found in storage`));
+    return "settled";
+  }
+  if (state.status === "running" || state.status === "pending" || state.status === "suspended")
+    return "pending";
+  const outcome = await prepareToSettleTerminalWaiter(internals, workflowId, waiter);
+  if (outcome !== "proceed")
+    return outcome;
+  try {
+    const result = deriveWorkflowResultFromState(state);
+    clearResultWaiter(internals, workflowId, waiter);
+    waiter.resolve(result);
+    return "settled";
   } catch (error) {
     clearResultWaiter(internals, workflowId, waiter);
     waiter.reject(error);
+    return "settled";
   }
 }
 function linkToReplacementWaiter(internals, workflowId, waiter) {

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

@@ -27,7 +27,9 @@ export type { PendingAsyncActivity } from './async-activity-records.ts';
 export type { PendingTimelineEntry, RegistrationEntry, ResolvedOptions, TrackedWaiterKeys, WorkflowResultWaiter, } from './engine-internal-types.ts';
 export { ActivityResolutionError, BulkDeleteRequiresTerminalWorkflowsError, BulkOperationConfirmationError, EngineCreateNameMismatchError, EngineDisposalError, EngineDisposedError, IdempotencyKeyPurgedError, PersistedDataIncompatibleError, StartOrSignalConflictError, WorkflowAlreadyExistsError, WorkflowConcurrencyLimitExceededError, WorkflowNotFoundError, WorkflowNotRegisteredError, WorkflowSuspendNotSupportedError, WorkflowTeardownPendingError, WorkflowTypeNotRegisteredForRecoveryError, } from './errors.ts';
 export { HANDLE_RESULT_PROMISE, WorkflowHandle } from './handles.ts';
-export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, } from './lease-errors.ts';
+export { WeftWorkflowClaimLostWarning, WeftWorkflowWakeDiscardedWarning, WORKFLOW_CLAIM_LOST_WARNING_NAME, WORKFLOW_WAKE_DISCARDED_WARNING_NAME, } from './lease-deposition.ts';
+export type { WorkflowWakeKind } from './lease-deposition.ts';
+export { EngineLeaseAcquisitionTimeoutError, EngineLeaseCorruptedError, EngineLeaseNotHeldError, OwnershipModeMismatchError, WorkflowClaimUnavailableError, } from './lease-errors.ts';
 export type { EngineLeaseHealth, LeaseLostReason } from './lease-health.ts';
 export type { RecoverAllOptions, RecoveredWorkflowInfo } from './lifecycle.ts';
 export { ScheduleHandle } from './schedule-handle.ts';
@@ -272,13 +274,19 @@ export declare class Engine<TWorkflows extends object = DefaultWorkflowRegistry,
     aggregate(filter: ListFilter | undefined, options: AggregateOptions): Promise<AggregateResult>;
     getRetentionOverview(): RetentionOverview;
     /**
-     * Run one host-driven maintenance cycle. This fires due durable timers,
-     * deletes expired update responses, applies configured retention, and
-     * re-evaluates alert rules without relying on process-local intervals.
+     * Run one host-driven maintenance cycle. This runs the `ownership:
+     * 'workflow-lease'` construction gates (idempotent — a no-op once already
+     * bootstrapped) and one per-workflow claim-renewal pass, fires due durable
+     * timers, deletes expired update responses, applies configured retention,
+     * and re-evaluates alert rules without relying on process-local intervals.
      *
      * Use with `backgroundTasks: 'manual'` from a serverless alarm, Cron trigger,
      * or another externally scheduled wake-up. Concurrent calls are safe, but a
-     * host should await each cycle before scheduling another.
+     * host should await each cycle before scheduling another. Under `ownership:
+     * 'workflow-lease'`, this is also the ONLY thing that renews this engine's
+     * per-workflow claims in manual mode — no interval is ever started for
+     * `backgroundTasks: 'manual'`, so a host that calls this less often than
+     * `workflowClaimRenewInterval` will see its own live claims lapse.
      */
     runMaintenance(now?: number): Promise<void>;
     purge(filter?: ListFilter): Promise<PurgeResult>;