@lostgradient/weft 0.3.0 → 0.4.0

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

@@ -0,0 +1,159 @@
+import { KEYS } from "../../../storage/interface.js";
+import { decode } from "../../codec.js";
+import { WorkflowTeardownEvent } from "../../events.js";
+import { isTeardownClaim, parseTeardownTimerId } from "../state-utilities.js";
+import { runFinalizerActivity } from "./finalizer-activity.js";
+import {
+  claimTeardownMarker,
+  clearTeardownMarker,
+  deadLetterTeardown,
+  encodeOwedClaim,
+  MAX_TEARDOWN_ATTEMPTS,
+  rearmTeardownTimer,
+  runningClaimIsStale,
+  settleOnRunningClaim,
+  TEARDOWN_SELF_HEAL_DELAY_MS,
+  teardownBackoffMs,
+  teardownStaleThresholdMs,
+  teardownTimerOperations
+} from "./finalizer-claim.js";
+export { teardownStaleThresholdMs } from "./finalizer-claim.js";
+const TERMINAL_STATUSES_OWED_TEARDOWN = new Set([
+  "cancelled",
+  "timed-out"
+]);
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function rearmOnLostSettle(internals, workflowId, token) {
+  await rearmTeardownTimer(internals, workflowId, token, TEARDOWN_SELF_HEAL_DELAY_MS);
+}
+async function clearOrRearm(internals, workflowId, token, markerBytes) {
+  return await clearTeardownMarker(internals, workflowId, markerBytes) ? { kind: "cleared" } : { kind: "rearm", token };
+}
+async function readDriveableClaim(internals, workflowId, token, markerBytes) {
+  let decoded;
+  try {
+    decoded = decode(markerBytes);
+  } catch {
+    return clearOrRearm(internals, workflowId, token, markerBytes);
+  }
+  if (!isTeardownClaim(decoded))
+    return clearOrRearm(internals, workflowId, token, markerBytes);
+  return { kind: "claim", claim: decoded };
+}
+async function resolveTeardownDrive(internals, workflowId, token, callbacks) {
+  const markerBytes = await internals.storage.get(KEYS.teardownOwed(workflowId));
+  if (markerBytes === null)
+    return { kind: "cleared" };
+  const resolution = await readDriveableClaim(internals, workflowId, token, markerBytes);
+  if (resolution.kind !== "claim")
+    return resolution;
+  const claim = resolution.claim;
+  if (claim.token !== token)
+    return { kind: "cleared" };
+  const state = await callbacks.loadWorkflowState(workflowId);
+  if (state === null || !TERMINAL_STATUSES_OWED_TEARDOWN.has(state.status))
+    return clearOrRearm(internals, workflowId, token, markerBytes);
+  const registeredFinalizer = internals.registrations.get(state.type)?.finalizer;
+  if (registeredFinalizer === void 0)
+    return { kind: "rearm", token };
+  const finalizer = registeredFinalizer;
+  if (!runningClaimIsStale(internals, claim, finalizer))
+    return { kind: "rearm", token };
+  const finalizerStateBytes = await internals.storage.get(KEYS.finalizerState(workflowId));
+  if (finalizerStateBytes === null) {
+    await deadLetterMissingState(internals, workflowId, state.type, claim.attempts, markerBytes, callbacks);
+    return { kind: "cleared" };
+  }
+  return {
+    kind: "run",
+    drive: { state, claim, markerBytes, finalizer, finalizerInput: decode(finalizerStateBytes) }
+  };
+}
+async function deadLetterMissingState(internals, workflowId, workflowType, attempts, expectedBytes, callbacks) {
+  const lastError = "finalizer state missing \u2014 recorded resource cannot be torn down";
+  if (await deadLetterTeardown(internals, workflowId, workflowType, attempts, expectedBytes, {
+    lastError,
+    finalizerInput: void 0
+  }))
+    callbacks.dispatchEvent(new WorkflowTeardownEvent(workflowId, workflowType, "dead-lettered", attempts, lastError));
+}
+export async function runWorkflowFinalizer(internals, workflowId, timerId, callbacks) {
+  const token = parseTeardownTimerId(timerId);
+  if (token === null)
+    return;
+  try {
+    const resolution = await resolveTeardownDrive(internals, workflowId, token, callbacks);
+    if (resolution.kind === "cleared")
+      return;
+    if (resolution.kind === "rearm") {
+      await rearmTeardownTimer(internals, workflowId, resolution.token, TEARDOWN_SELF_HEAL_DELAY_MS);
+      return;
+    }
+    await driveResolvedTeardown(internals, workflowId, token, resolution.drive, callbacks);
+  } catch (error) {
+    await rearmTeardownTimer(internals, workflowId, token, TEARDOWN_SELF_HEAL_DELAY_MS);
+    callbacks.handleCleanupError("runWorkflowFinalizer", error, workflowId);
+  }
+}
+async function driveResolvedTeardown(internals, workflowId, token, drive, callbacks) {
+  const { state, claim, markerBytes, finalizer, finalizerInput } = drive, attempt = claim.attempts + 1, runningBytes = await claimTeardownMarker(internals, workflowId, markerBytes, claim.attempts, token);
+  if (runningBytes === null) {
+    await rearmTeardownTimer(internals, workflowId, token, TEARDOWN_SELF_HEAL_DELAY_MS);
+    return;
+  }
+  const result = await runFinalizerActivity(finalizer, finalizerInput, attempt, internals.abortController.signal);
+  if (result.ok) {
+    await settleTeardownSuccess(internals, workflowId, state.type, token, attempt, runningBytes, callbacks);
+    return;
+  }
+  if (result.abortedByShutdown) {
+    const fireAt = internals.options.getNow() + TEARDOWN_SELF_HEAL_DELAY_MS;
+    if (!await settleOnRunningClaim(internals, workflowId, runningBytes, [
+      {
+        type: "put",
+        key: KEYS.teardownOwed(workflowId),
+        value: encodeOwedClaim(claim.attempts, token)
+      },
+      ...teardownTimerOperations(token, workflowId, fireAt)
+    ]))
+      await rearmOnLostSettle(internals, workflowId, token);
+    return;
+  }
+  await settleTeardownFailure(internals, workflowId, state, attempt, token, runningBytes, result.error, callbacks);
+}
+async function settleTeardownSuccess(internals, workflowId, workflowType, token, attempt, runningBytes, callbacks) {
+  if (!await settleOnRunningClaim(internals, workflowId, runningBytes, [
+    { type: "delete", key: KEYS.teardownOwed(workflowId) },
+    { type: "delete", key: KEYS.finalizerState(workflowId) }
+  ])) {
+    await rearmOnLostSettle(internals, workflowId, token);
+    return;
+  }
+  callbacks.dispatchEvent(new WorkflowTeardownEvent(workflowId, workflowType, "completed", attempt));
+}
+async function settleTeardownFailure(internals, workflowId, state, attempt, token, runningBytes, error, callbacks) {
+  const message = errorMessage(error);
+  if (attempt >= MAX_TEARDOWN_ATTEMPTS) {
+    const finalizerStateBytes = await internals.storage.get(KEYS.finalizerState(workflowId));
+    if (!await deadLetterTeardown(internals, workflowId, state.type, attempt, runningBytes, {
+      lastError: message,
+      finalizerInput: finalizerStateBytes === null ? void 0 : decode(finalizerStateBytes)
+    })) {
+      await rearmOnLostSettle(internals, workflowId, token);
+      return;
+    }
+    callbacks.dispatchEvent(new WorkflowTeardownEvent(workflowId, state.type, "dead-lettered", attempt, message));
+    return;
+  }
+  const fireAt = internals.options.getNow() + teardownBackoffMs(attempt);
+  if (!await settleOnRunningClaim(internals, workflowId, runningBytes, [
+    { type: "put", key: KEYS.teardownOwed(workflowId), value: encodeOwedClaim(attempt, token) },
+    ...teardownTimerOperations(token, workflowId, fireAt)
+  ])) {
+    await rearmOnLostSettle(internals, workflowId, token);
+    return;
+  }
+  callbacks.dispatchEvent(new WorkflowTeardownEvent(workflowId, state.type, "failed", attempt, message));
+}

package/dist/core/engine/termination/suspend.d.ts

@@ -13,7 +13,9 @@ import { type TerminationCallbacks } from './cleanup.ts';
  *   cancellation, so user code observing `ctx.signal.aborted` or registered
  *   abort listeners must not fire. The live inline run is *parked*
  *   (`parkWorkflow`: evict execution state without aborting), the same primitive
- *   the engine uses for signal-parking,
+ *   the engine uses for signal-parking — but with the default eviction, not the
+ *   `retainContext` form signal-parking uses, so suspend leaves no queryable
+ *   Context behind,
  * - does NOT run cancel handlers,
  * - does NOT settle the result promise (`handle.result()` stays pending until a
  *   later `resume()` drives the run to completion, or a `cancel()` terminates it),

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

@@ -6,4 +6,5 @@
  */
 export { TERMINAL_WORKFLOW_STATUSES, cleanupTerminalWorkflowDurableState, cleanupTerminalWorkflowImmediately, cleanupTerminalWorkflowMemory, cleanupTerminalWorkflowSynchronously, cleanupWaiters, cleanupWorkflowStorage, evictSuspendedWorkflowWaiters, finalizeScheduledWorkflowTerminal, handleCleanupError, runDeferredTerminalCleanup, type TerminationCallbacks, } from './termination/cleanup.ts';
 export { buildPendingTimelineOperation, buildTerminalCleanupTimerOperations, cancelWorkflow, completeWorkflow, ensureTerminalCleanupTracked, failWorkflow, finalizePendingTimelineEntry, terminateWorkflow, timeoutWorkflow, } from './termination/complete.ts';
+export { runWorkflowFinalizer, teardownStaleThresholdMs, type FinalizerDriveCallbacks, type TeardownDeadLetterRecord, } from './termination/finalizer.ts';
 export { suspendWorkflow } from './termination/suspend.ts';

package/dist/core/engine/termination.js

@@ -22,4 +22,8 @@ export {
   terminateWorkflow,
   timeoutWorkflow
 } from "./termination/complete.js";
+export {
+  runWorkflowFinalizer,
+  teardownStaleThresholdMs
+} from "./termination/finalizer.js";
 export { suspendWorkflow } from "./termination/suspend.js";

package/dist/core/engine/updates.js

@@ -1,10 +1,9 @@
 import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
 import { isGeneratorResult } from "../step-context.js";
-import {
-  UpdateTimeoutError,
-  UpdateValidationError
-} from "../updates.js";
+import { UpdateValidationError } from "../updates.js";
+import { notifyConditionWaiters } from "./condition-waiters.js";
 import { trackWaiterKey, untrackWaiterKey } from "./signals.js";
+import { waitForUpdateResponse } from "./waiting-update-response.js";
 export async function update(internals, workflowId, name, payload, options, callbacks) {
   const timeout = options?.timeout ?? 30000;
   await runUpdateValidator(internals, workflowId, name, payload);
@@ -27,11 +26,13 @@ async function tryInlineUpdateHandler(internals, workflowId, name, payload, call
     const result = await invokeUpdateHandler(internals, name, handler, payload);
     callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, result));
     callbacks.broadcast({ type: "update:completed", workflowId, updateId });
+    notifyConditionWaiters(internals, workflowId);
     return { handled: !0, value: result };
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
     callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, void 0, errorMessage));
     callbacks.broadcast({ type: "update:completed", workflowId, updateId });
+    notifyConditionWaiters(internals, workflowId);
     throw error;
   }
 }
@@ -51,27 +52,6 @@ async function tryWaitingUpdateHandler(internals, workflowId, name, payload, tim
   callbacks.broadcast({ type: "update:completed", workflowId, updateId });
   return { handled: !0, value: result };
 }
-async function waitForUpdateResponse(updateId, payload, timeout, updateWaiter) {
-  const { promise: respondPromise, resolve: resolveRespond } = Promise.withResolvers();
-  let responded = !1;
-  updateWaiter({ payload, respond: (value) => {
-    if (responded)
-      return;
-    responded = !0;
-    resolveRespond(value);
-  } });
-  let timeoutId;
-  try {
-    return await Promise.race([
-      respondPromise,
-      new Promise((_resolve, reject) => {
-        timeoutId = setTimeout(() => reject(new UpdateTimeoutError(updateId, timeout)), timeout);
-      })
-    ]);
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}
 async function runCoordinatedUpdate(internals, workflowId, name, payload, timeout, callbacks) {
   const updateId = await internals.updateCoordinator.createRequest(workflowId, name, payload);
   callbacks.schedulePendingInlineUpdateDrain(workflowId);

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

@@ -8,6 +8,7 @@ export declare function isValidScheduleIdentifier(value: unknown): value is stri
 export declare function coerceScheduleId(scheduleId: string, fieldName: string): string;
 export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
     id?: string;
+    jitterMs?: number;
 };
 /**
  * A recurrence specification normalized into the discriminated cadence the
@@ -32,7 +33,7 @@ export declare function decodeScheduleIdentityFields(decoded: Record<string, unk
     cronExpression?: string;
     intervalMs?: number;
 }) | null;
-type ScheduleRuntimeFields = Pick<ScheduleState, 'backfill' | 'createdAt' | 'updatedAt' | 'lastFireAt' | 'nextFireAt' | 'currentWorkflowId' | 'queuedRuns'>;
+type ScheduleRuntimeFields = Pick<ScheduleState, 'backfill' | 'jitterMs' | 'createdAt' | 'updatedAt' | 'lastFireAt' | 'lastMissedFireAt' | 'nextFireAt' | 'currentWorkflowId' | 'missedFireCount' | 'queuedRuns'>;
 export declare function decodeScheduleRuntimeFields(decoded: Record<string, unknown>, scheduleId: string): ScheduleRuntimeFields | null;
 export declare function decodeScheduleState(bytes: Uint8Array): ScheduleState | null;
 export {};

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

@@ -36,7 +36,7 @@ export function normalizeScheduleOptions(options) {
     return { overlap: "skip", backfill: !1 };
   if (typeof options !== "object" || options === null)
     throw Error("options must be an object when provided");
-  const { id, overlap, backfill } = options, normalizedOptions = {
+  const { id, overlap, backfill, jitter } = options, normalizedOptions = {
     overlap: "skip",
     backfill: !1
   };
@@ -52,8 +52,25 @@ export function normalizeScheduleOptions(options) {
       throw Error("options.backfill must be a boolean when provided");
     normalizedOptions.backfill = backfill;
   }
+  if (jitter !== void 0)
+    normalizedOptions.jitterMs = normalizeScheduleJitter(jitter, "options.jitter");
   return normalizedOptions;
 }
+function normalizeScheduleJitter(value, fieldName) {
+  if (typeof value !== "string" && typeof value !== "number")
+    throw Error(`${fieldName} must be a duration string or a number of milliseconds`);
+  let milliseconds;
+  try {
+    milliseconds = parseDuration(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw Error(`Invalid ${fieldName}: ${message}`, { cause: error });
+  }
+  const jitterMs = Math.ceil(milliseconds);
+  if (!Number.isSafeInteger(jitterMs) || jitterMs <= 0)
+    throw Error(`${fieldName} must resolve to a positive number of milliseconds`);
+  return jitterMs;
+}
 function normalizeIntervalEvery(every) {
   if (typeof every !== "string" && typeof every !== "number")
     throw Error('Schedule interval "every" must be a duration string or a number of milliseconds');
@@ -171,6 +188,16 @@ function decodeScheduleBackfill(decoded, scheduleId) {
   }
   return backfill;
 }
+function decodeScheduleJitterMs(decoded, scheduleId) {
+  const jitterMs = decoded.jitterMs;
+  if (jitterMs === void 0)
+    return;
+  if (typeof jitterMs !== "number" || !Number.isSafeInteger(jitterMs) || jitterMs <= 0) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid jitterMs");
+    return null;
+  }
+  return jitterMs;
+}
 function decodeScheduleTimestamps(decoded, scheduleId) {
   const { createdAt, updatedAt } = decoded;
   if (!isValidScheduleTimestamp(createdAt) || !isValidScheduleTimestamp(updatedAt))
@@ -178,10 +205,14 @@ function decodeScheduleTimestamps(decoded, scheduleId) {
   const lastFireAt = decoded.lastFireAt;
   if (lastFireAt !== void 0 && !isValidScheduleTimestamp(lastFireAt))
     return rejectInvalidScheduleRecord(scheduleId, "with invalid lastFireAt");
+  const lastMissedFireAt = decoded.lastMissedFireAt;
+  if (lastMissedFireAt !== void 0 && !isValidScheduleTimestamp(lastMissedFireAt))
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid lastMissedFireAt");
   return {
     createdAt,
     updatedAt,
-    ...lastFireAt !== void 0 && { lastFireAt }
+    ...lastFireAt !== void 0 && { lastFireAt },
+    ...lastMissedFireAt !== void 0 && { lastMissedFireAt }
   };
 }
 function decodeScheduleNextFireAt(decoded, scheduleId) {
@@ -214,10 +245,23 @@ function decodeScheduleQueuedRuns(decoded, scheduleId) {
   }
   return queuedRuns;
 }
+function decodeScheduleMissedFireCount(decoded, scheduleId) {
+  const missedFireCount = decoded.missedFireCount;
+  if (missedFireCount === void 0)
+    return 0;
+  if (typeof missedFireCount !== "number" || !Number.isSafeInteger(missedFireCount) || missedFireCount < 0) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid missedFireCount");
+    return null;
+  }
+  return missedFireCount;
+}
 export function decodeScheduleRuntimeFields(decoded, scheduleId) {
   const backfill = decodeScheduleBackfill(decoded, scheduleId);
   if (backfill === null)
     return null;
+  const jitterMs = decodeScheduleJitterMs(decoded, scheduleId);
+  if (jitterMs === null)
+    return null;
   const timestamps = decodeScheduleTimestamps(decoded, scheduleId);
   if (timestamps === null)
     return null;
@@ -230,11 +274,16 @@ export function decodeScheduleRuntimeFields(decoded, scheduleId) {
   const queuedRuns = decodeScheduleQueuedRuns(decoded, scheduleId);
   if (queuedRuns === null)
     return null;
+  const missedFireCount = decodeScheduleMissedFireCount(decoded, scheduleId);
+  if (missedFireCount === null)
+    return null;
   return {
     backfill,
+    ...jitterMs !== void 0 && { jitterMs },
     ...timestamps,
     nextFireAt: nextFireAt.value,
     ...currentWorkflow.value !== void 0 && { currentWorkflowId: currentWorkflow.value },
+    missedFireCount,
     queuedRuns
   };
 }

package/dist/core/engine/validation.js

@@ -11,6 +11,29 @@ const WORKFLOW_TIMELINE_STATUSES = new Set([
   "cancelled",
   "timed-out"
 ]);
+function defineCompleteWorkflowStateFieldNames(fieldNames) {
+  return fieldNames;
+}
+const WORKFLOW_STATE_FIELD_NAMES = new Set(defineCompleteWorkflowStateFieldNames([
+  "id",
+  "type",
+  "status",
+  "tags",
+  "input",
+  "result",
+  "error",
+  "errorStack",
+  "failureCategory",
+  "terminationReason",
+  "versionTuple",
+  "executionStateOwnerId",
+  "createdAt",
+  "startedAt",
+  "updatedAt",
+  "terminalCleanupToken",
+  "executionDeadline",
+  "forkedFrom"
+]));
 export function isSanitizedSearchAttributeValue(value) {
   if (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
     return !0;
@@ -56,12 +79,10 @@ export function isValidDecodedTags(value) {
   return value === void 0 || isWorkflowTagArray(value);
 }
 export function decodeWorkflowState(bytes) {
-  const decoded = decode(bytes);
-  if (isRecord(decoded))
-    liftFlatVersionTuple(decoded);
+  const decoded = decode(bytes), decodedRecord = isRecord(decoded) ? decoded : void 0;
+  if (decodedRecord !== void 0)
+    liftFlatVersionTuple(decodedRecord);
   const state = decoded;
-  if ("tenant" in state)
-    delete state.tenant;
   if (!isValidDecodedTags(state.tags)) {
     console.warn(`[weft] Decoded workflow state for "${String(state.id)}" has invalid tags; dropping the malformed tag list from the decoded state.`);
     delete state.tags;
@@ -80,6 +101,12 @@ export function decodeWorkflowState(bytes) {
       console.warn(`[weft] Decoded workflow state for "${String(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;
     }
+  return decodedRecord === void 0 ? state : stripUnknownWorkflowStateFields(state, decodedRecord);
+}
+function stripUnknownWorkflowStateFields(state, stateFields) {
+  for (const fieldName of Object.keys(stateFields))
+    if (!WORKFLOW_STATE_FIELD_NAMES.has(fieldName))
+      delete stateFields[fieldName];
   return state;
 }
 function liftFlatVersionTuple(record) {

package/dist/core/engine/waiting-update-response.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Park until a waiting `ctx.waitForUpdate` handler responds (via the resolver it
+ * registered in `updateWaiters`) or the update times out. Resolves with the
+ * handler's response value; rejects with {@link UpdateTimeoutError} when the
+ * timeout elapses first. The `respond` callback is single-shot — a late second
+ * response is ignored.
+ */
+export declare function waitForUpdateResponse(updateId: string, payload: unknown, timeout: number, updateWaiter: (request: unknown) => void): Promise<unknown>;

package/dist/core/engine/waiting-update-response.js

@@ -0,0 +1,22 @@
+import { UpdateTimeoutError } from "../updates.js";
+export async function waitForUpdateResponse(updateId, payload, timeout, updateWaiter) {
+  const { promise: respondPromise, resolve: resolveRespond } = Promise.withResolvers();
+  let responded = !1;
+  updateWaiter({ payload, respond: (value) => {
+    if (responded)
+      return;
+    responded = !0;
+    resolveRespond(value);
+  } });
+  let timeoutId;
+  try {
+    return await Promise.race([
+      respondPromise,
+      new Promise((_resolve, reject) => {
+        timeoutId = setTimeout(() => reject(new UpdateTimeoutError(updateId, timeout)), timeout);
+      })
+    ]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/dist/core/engine/workflow-concurrency.d.ts

@@ -0,0 +1,10 @@
+import type { BatchOperation, ConditionalBatchCondition } from '../../storage/interface.ts';
+import type { WorkflowConcurrencyOptions } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+export type WorkflowConcurrencyStartOperations = {
+    stateKey: string;
+    operations: BatchOperation[];
+    conditions: ConditionalBatchCondition[];
+};
+export declare function buildWorkflowConcurrencyStartOperations(internals: EngineInternals, workflowType: string, workflowId: string, input: unknown, concurrency: WorkflowConcurrencyOptions): Promise<WorkflowConcurrencyStartOperations>;
+export declare function releaseWorkflowConcurrencySlot(internals: EngineInternals, workflowId: string): Promise<void>;

package/dist/core/engine/workflow-concurrency.js

@@ -0,0 +1,136 @@
+import { KEYS } from "../../storage/interface.js";
+import { AtomicState, atomicStateVersionKey, readAtomicStateSnapshot } from "../atomic-state.js";
+import { decode, encode } from "../codec.js";
+import {
+  initialLockRecord,
+  reduceRelease
+} from "../concurrency.js";
+import { WorkflowConcurrencyLimitExceededError } from "./errors.js";
+const WORKFLOW_CONCURRENCY_HOLDER_VERSION = 1, NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE = Number.MAX_SAFE_INTEGER;
+function encodeVersionCondition(dataKey, version) {
+  return {
+    key: atomicStateVersionKey(dataKey),
+    expectedValue: version === 0 ? null : encode(version)
+  };
+}
+function normalizeLockRecord(record) {
+  if (record === void 0)
+    return initialLockRecord();
+  return {
+    holders: Array.isArray(record.holders) ? record.holders : [],
+    waiters: Array.isArray(record.waiters) ? record.waiters : []
+  };
+}
+function liveWorkflowConcurrencyHolders(holders, now) {
+  return holders.filter((holder) => holder.leaseExpiresAt > now);
+}
+function acquireWorkflowConcurrencySlot(current, options) {
+  const record = normalizeLockRecord(current), holders = liveWorkflowConcurrencyHolders(record.holders, options.now);
+  if (holders.some((holder) => holder.holderId === options.workflowId))
+    return {
+      acquired: !0,
+      record: {
+        holders: holders.map((holder) => holder.holderId === options.workflowId ? {
+          holderId: options.workflowId,
+          leaseExpiresAt: NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE
+        } : holder),
+        waiters: []
+      }
+    };
+  if (holders.length >= options.limit)
+    return { acquired: !1, record: { holders, waiters: [] } };
+  return {
+    acquired: !0,
+    record: {
+      holders: [
+        ...holders,
+        {
+          holderId: options.workflowId,
+          leaseExpiresAt: NON_EXPIRING_WORKFLOW_CONCURRENCY_LEASE
+        }
+      ],
+      waiters: []
+    }
+  };
+}
+function resolveWorkflowConcurrencyPartitionKey(workflowType, input, concurrency) {
+  if (concurrency.key === void 0)
+    return workflowType;
+  let partitionKey;
+  try {
+    partitionKey = concurrency.key(input);
+  } catch (error) {
+    throw Error(`workflow("${workflowType}").concurrency.key threw while resolving the partition key: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (typeof partitionKey !== "string")
+    throw TypeError(`workflow("${workflowType}").concurrency.key must return a string partition key`);
+  return partitionKey;
+}
+function encodeHolderRecord(workflowType, partitionKey) {
+  return {
+    version: WORKFLOW_CONCURRENCY_HOLDER_VERSION,
+    workflowType,
+    partitionKey
+  };
+}
+function decodeHolderRecord(bytes) {
+  const decoded = decode(bytes);
+  if (typeof decoded !== "object" || decoded === null)
+    return null;
+  const record = decoded;
+  if (record.version !== WORKFLOW_CONCURRENCY_HOLDER_VERSION || typeof record.workflowType !== "string" || typeof record.partitionKey !== "string")
+    return null;
+  return {
+    version: WORKFLOW_CONCURRENCY_HOLDER_VERSION,
+    workflowType: record.workflowType,
+    partitionKey: record.partitionKey
+  };
+}
+export async function buildWorkflowConcurrencyStartOperations(internals, workflowType, workflowId, input, concurrency) {
+  const partitionKey = resolveWorkflowConcurrencyPartitionKey(workflowType, input, concurrency), stateKey = KEYS.workflowConcurrency(workflowType, partitionKey), snapshot = await readAtomicStateSnapshot(internals.storage, stateKey, {
+    initial: initialLockRecord()
+  }), acquired = acquireWorkflowConcurrencySlot(snapshot.value, {
+    workflowId,
+    now: internals.options.getNow(),
+    limit: concurrency.max
+  });
+  if (!acquired.acquired)
+    throw new WorkflowConcurrencyLimitExceededError({
+      workflowType,
+      limit: concurrency.max,
+      partitionKey
+    });
+  return {
+    stateKey,
+    conditions: [encodeVersionCondition(stateKey, snapshot.version)],
+    operations: [
+      { type: "put", key: stateKey, value: encode(acquired.record) },
+      { type: "put", key: atomicStateVersionKey(stateKey), value: encode(snapshot.version + 1) },
+      {
+        type: "put",
+        key: KEYS.workflowConcurrencyHolder(workflowId),
+        value: encode(encodeHolderRecord(workflowType, partitionKey))
+      },
+      {
+        type: "put",
+        key: KEYS.terminalCleanupNeeded(workflowId),
+        value: new Uint8Array(0)
+      }
+    ]
+  };
+}
+export async function releaseWorkflowConcurrencySlot(internals, workflowId) {
+  const holderKey = KEYS.workflowConcurrencyHolder(workflowId), markerBytes = await internals.storage.get(holderKey);
+  if (markerBytes === null)
+    return;
+  const marker = decodeHolderRecord(markerBytes);
+  if (marker === null) {
+    await internals.storage.delete(holderKey);
+    return;
+  }
+  const stateKey = KEYS.workflowConcurrency(marker.workflowType, marker.partitionKey);
+  await new AtomicState(internals.storage, stateKey, {
+    initial: initialLockRecord()
+  }).update((current) => reduceRelease(current, { holderId: workflowId, now: internals.options.getNow() }));
+  await internals.storage.delete(holderKey);
+}

package/dist/core/engine/workflow-feed.d.ts

@@ -26,11 +26,10 @@ export declare const STREAM_CHUNK_KIND = "stream:chunk";
 export declare const COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
 /**
  * A committed workflow-feed record surfaced to subscribers of
- * `subscribeWorkflowFeedCommits()`. Fires after `storage.batch()`
- * (events) or `storage.put()` (tokens) resolves, so replay and live
- * delivery share the same committed sequence authority. The same
- * shape covers both selectors — consumers filter on `selector`
- * before interpreting `payload`.
+ * `subscribeWorkflowFeedCommits()`. Fires after the storage commit resolves, so
+ * replay and live delivery share the same committed sequence authority. The
+ * same shape covers both selectors — consumers filter on `selector` before
+ * interpreting `payload`.
  *
  *   - `events` selector: `kind` is the durable log entry type
  *     (e.g. `'workflow:checkpoint'`). `sequence` / `timestamp` come

package/dist/core/engine/workflow-feed.js

@@ -1,7 +1,7 @@
 import { EventLog } from "../event-log.js";
 import { readEventLogWatermark } from "./event-log-compaction.js";
 import { workflowFeedListenerKey } from "./state-utilities.js";
-import { loadStoredStreamChunks } from "./stream-chunk-loading.js";
+import { loadStoredStreamChunks, loadStoredStreamTailSequence } from "./stream-chunk-loading.js";
 export const TOKENS_STREAM_KEY = "tokens", STREAM_CHUNK_KIND = "stream:chunk", COMPACTION_BOUNDARY_KIND = "workflow:compaction-boundary";
 export async function* replayWorkflowFeed(internals, workflowId, selector, afterSequence) {
   if (selector === "events") {
@@ -17,6 +17,9 @@ export async function snapshotWorkflowFeedTail(internals, workflowId, selector)
       return head.sequence;
     return (await new EventLog(internals.storage, workflowId).loadHead()).sequence;
   }
+  const tail = await loadStoredStreamTailSequence(internals.storage, workflowId, TOKENS_STREAM_KEY);
+  if (tail !== null)
+    return tail;
   const chunks = await loadStoredStreamChunks(internals.storage, workflowId, TOKENS_STREAM_KEY);
   if (chunks.length === 0)
     return -1;