@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/src/durable/dbos-metadata.ts

@@ -1,13 +1,13 @@
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { DbosStepRecord } from "./dbos-backend.js";
-import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
-import type { DurableCheckpointEntry, DurableWorkflowStatus } from "./types.js";
+import { isCurrentDurableFormat, DURABLE_FORMAT_VERSION } from "./format-version.js";
+import type { DurableWorkflowMetadata, DurableWorkflowStatus } from "./types.js";
+import { isAbsorbingDurableStatus } from "./workflow-status-transition.js";
 
 const METADATA_STEP_PREFIX = "__atomic_metadata";
 
-export type DbosMetadataCompatibility =
-  | { readonly kind: "current"; readonly entry: DurableCheckpointEntry }
-  | { readonly kind: "legacy" }
+export type DbosMetadataClassification =
+  | { readonly kind: "current"; readonly metadata: DurableWorkflowMetadata; readonly generation: number }
   | { readonly kind: "unknown" }
   | { readonly kind: "unavailable" };
 
@@ -15,46 +15,90 @@ export function metadataStepName(ts: number): string {
   return `${METADATA_STEP_PREFIX}:${ts}:${crypto.randomUUID()}`;
 }
 
+/** Deterministic first-writer-wins claim id for one observed generation. */
+export function claimMetadataStepName(generation: number): string {
+  return `${METADATA_STEP_PREFIX}:${generation + 1}:claim`;
+}
+
 export function isMetadataStep(stepName: string): boolean {
   return stepName === METADATA_STEP_PREFIX || stepName.startsWith(`${METADATA_STEP_PREFIX}:`);
 }
 
-export function encodeMetadata(entry: DurableCheckpointEntry): WorkflowSerializableValue {
+/** Parse one metadata step record, returning current-format metadata only. */
+export function parseCurrentMetadataRecord(
+  record: DbosStepRecord,
+  workflowId: string,
+): DurableWorkflowMetadata | undefined {
+  const classified = classifyMetadataRecord(record, workflowId);
+  return classified.kind === "current" ? classified.metadata : undefined;
+}
+
+export function encodeMetadata(metadata: DurableWorkflowMetadata): WorkflowSerializableValue {
   return {
     __atomicDurableMetadata: true,
     version: DURABLE_FORMAT_VERSION,
-    entry: {
-      formatVersion: entry.formatVersion,
-      type: entry.type,
-      workflowId: entry.workflowId,
-      name: entry.name,
-      inputs: entry.inputs,
-      status: entry.status,
-      completedCheckpoints: entry.completedCheckpoints,
-      pendingPrompts: entry.pendingPrompts,
-      ...(entry.label !== undefined ? { label: entry.label } : {}),
-      ...(entry.rootWorkflowId !== undefined ? { rootWorkflowId: entry.rootWorkflowId } : {}),
-      ...(entry.resumable !== undefined ? { resumable: entry.resumable } : {}),
-      ...(entry.invocationCwd !== undefined ? { invocationCwd: entry.invocationCwd } : {}),
-      ...(entry.workflowCwd !== undefined ? { workflowCwd: entry.workflowCwd } : {}),
-      ...(entry.repositoryRoot !== undefined ? { repositoryRoot: entry.repositoryRoot } : {}),
-      ...(entry.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: entry.gitWorktreeRoot } : {}),
-      ts: entry.ts,
+    metadata: {
+      workflowId: metadata.workflowId,
+      name: metadata.name,
+      inputs: metadata.inputs,
+      status: metadata.status,
+      createdAt: metadata.createdAt,
+      completedCheckpoints: metadata.completedCheckpoints,
+      pendingPrompts: metadata.pendingPrompts,
+      promptReservationEpoch: metadata.promptReservationEpoch,
+      ...(metadata.ownerExecutorId !== undefined ? { ownerExecutorId: metadata.ownerExecutorId } : {}),
+      ...(metadata.transitionClaimId !== undefined ? { transitionClaimId: metadata.transitionClaimId } : {}),
+      ...(metadata.sessionFile !== undefined ? { sessionFile: metadata.sessionFile } : {}),
+      ...(metadata.label !== undefined ? { label: metadata.label } : {}),
+      ...(metadata.rootWorkflowId !== undefined ? { rootWorkflowId: metadata.rootWorkflowId } : {}),
+      ...(metadata.resumable !== undefined ? { resumable: metadata.resumable } : {}),
+      ...(metadata.invocationCwd !== undefined ? { invocationCwd: metadata.invocationCwd } : {}),
+      ...(metadata.workflowCwd !== undefined ? { workflowCwd: metadata.workflowCwd } : {}),
+      ...(metadata.repositoryRoot !== undefined ? { repositoryRoot: metadata.repositoryRoot } : {}),
+      ...(metadata.gitWorktreeRoot !== undefined ? { gitWorktreeRoot: metadata.gitWorktreeRoot } : {}),
+      updatedAt: metadata.updatedAt,
     },
   };
 }
 
-export function classifyLatestMetadata(records: readonly DbosStepRecord[], workflowId: string): DbosMetadataCompatibility {
-  const metadata = records.filter((record) => isMetadataStep(record.stepName));
-  if (metadata.length === 0) return { kind: "unavailable" };
-  const latest = metadata.reduce((selected, record) => metadataTimestamp(record) >= metadataTimestamp(selected) ? record : selected);
-  if (typeof latest.output !== "object" || latest.output === null || Array.isArray(latest.output)) return { kind: "unknown" };
-  const raw = latest.output as Record<string, WorkflowSerializableValue>;
-  if (raw["__atomicDurableMetadata"] !== true) return { kind: "unknown" };
-  const compatibility = classifyDurableFormatVersion(raw["version"]);
-  if (compatibility !== "current") return { kind: compatibility };
-  const entry = parseDurableCheckpointEntry(raw["entry"], workflowId);
-  return entry === undefined ? { kind: "unknown" } : { kind: "current", entry };
+export function classifyLatestMetadata(
+  records: readonly DbosStepRecord[],
+  workflowId: string,
+): DbosMetadataClassification {
+  const metadataRecords = records.filter((record) => isMetadataStep(record.stepName));
+  if (metadataRecords.length === 0) return { kind: "unavailable" };
+  const latest = metadataRecords.reduce((selected, record) =>
+    metadataTimestamp(record) >= metadataTimestamp(selected) ? record : selected);
+  const latestClassification = classifyMetadataRecord(latest, workflowId);
+  if (latestClassification.kind !== "current") return latestClassification;
+  const terminals = metadataRecords
+    .map((record) => ({ record, classified: classifyMetadataRecord(record, workflowId) }))
+    .filter((candidate): candidate is {
+      record: DbosStepRecord;
+      classified: { kind: "current"; metadata: DurableWorkflowMetadata };
+    } => candidate.classified.kind === "current"
+      && isAbsorbingDurableStatus(candidate.classified.metadata.status, candidate.classified.metadata.resumable));
+  if (terminals.length === 0) {
+    return { ...latestClassification, generation: metadataTimestamp(latest) };
+  }
+  const terminal = terminals.reduce((selected, candidate) =>
+    metadataTimestamp(candidate.record) >= metadataTimestamp(selected.record) ? candidate : selected);
+  return { ...terminal.classified, generation: metadataTimestamp(terminal.record) };
+}
+
+function classifyMetadataRecord(
+  record: DbosStepRecord,
+  workflowId: string,
+): { readonly kind: "current"; readonly metadata: DurableWorkflowMetadata } | { readonly kind: "unknown" } {
+  if (typeof record.output !== "object" || record.output === null || Array.isArray(record.output)) {
+    return { kind: "unknown" };
+  }
+  const raw = record.output as Record<string, WorkflowSerializableValue>;
+  if (raw["__atomicDurableMetadata"] !== true || !isCurrentDurableFormat(raw["version"])) {
+    return { kind: "unknown" };
+  }
+  const metadata = parseDurableWorkflowMetadata(raw["metadata"], workflowId);
+  return metadata === undefined ? { kind: "unknown" } : { kind: "current", metadata };
 }
 
 function metadataTimestamp(record: DbosStepRecord): number {
@@ -63,33 +107,36 @@ function metadataTimestamp(record: DbosStepRecord): number {
   return Number.isFinite(fromName) ? fromName : (record.completedAt ?? 0);
 }
 
-function parseDurableCheckpointEntry(
+function parseDurableWorkflowMetadata(
   value: WorkflowSerializableValue | undefined,
   workflowId: string,
-): DurableCheckpointEntry | undefined {
+): DurableWorkflowMetadata | undefined {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  const entry = value as Partial<DurableCheckpointEntry>;
-  if (entry.workflowId !== workflowId
-    || entry.formatVersion !== DURABLE_FORMAT_VERSION
-    || entry.type !== "workflow.durable.checkpoint"
-    || typeof entry.workflowId !== "string"
-    || typeof entry.name !== "string"
-    || typeof entry.inputs !== "object"
-    || entry.inputs === null
-    || Array.isArray(entry.inputs)
-    || typeof entry.status !== "string"
-    || !isDurableWorkflowStatus(entry.status)
-    || typeof entry.completedCheckpoints !== "number"
-    || typeof entry.pendingPrompts !== "number"
-    || typeof entry.ts !== "number"
-    || (entry.label !== undefined && typeof entry.label !== "string")
-    || (entry.rootWorkflowId !== undefined && typeof entry.rootWorkflowId !== "string")
-    || (entry.resumable !== undefined && typeof entry.resumable !== "boolean")
-    || (entry.invocationCwd !== undefined && typeof entry.invocationCwd !== "string")
-    || (entry.workflowCwd !== undefined && typeof entry.workflowCwd !== "string")
-    || (entry.repositoryRoot !== undefined && typeof entry.repositoryRoot !== "string")
-    || (entry.gitWorktreeRoot !== undefined && typeof entry.gitWorktreeRoot !== "string")) return undefined;
-  return entry as DurableCheckpointEntry;
+  const metadata = value as Partial<DurableWorkflowMetadata>;
+  if (metadata.workflowId !== workflowId
+    || typeof metadata.workflowId !== "string"
+    || typeof metadata.name !== "string"
+    || typeof metadata.inputs !== "object"
+    || metadata.inputs === null
+    || Array.isArray(metadata.inputs)
+    || typeof metadata.status !== "string"
+    || !isDurableWorkflowStatus(metadata.status)
+    || typeof metadata.completedCheckpoints !== "number"
+    || typeof metadata.createdAt !== "number"
+    || typeof metadata.pendingPrompts !== "number"
+    || typeof metadata.promptReservationEpoch !== "string"
+    || typeof metadata.updatedAt !== "number"
+    || (metadata.ownerExecutorId !== undefined && typeof metadata.ownerExecutorId !== "string")
+    || (metadata.transitionClaimId !== undefined && typeof metadata.transitionClaimId !== "string")
+    || (metadata.sessionFile !== undefined && typeof metadata.sessionFile !== "string")
+    || (metadata.label !== undefined && typeof metadata.label !== "string")
+    || (metadata.rootWorkflowId !== undefined && typeof metadata.rootWorkflowId !== "string")
+    || (metadata.resumable !== undefined && typeof metadata.resumable !== "boolean")
+    || (metadata.invocationCwd !== undefined && typeof metadata.invocationCwd !== "string")
+    || (metadata.workflowCwd !== undefined && typeof metadata.workflowCwd !== "string")
+    || (metadata.repositoryRoot !== undefined && typeof metadata.repositoryRoot !== "string")
+    || (metadata.gitWorktreeRoot !== undefined && typeof metadata.gitWorktreeRoot !== "string")) return undefined;
+  return metadata as DurableWorkflowMetadata;
 }
 
 function isDurableWorkflowStatus(value: string): value is DurableWorkflowStatus {

package/dist/builtin/workflows/src/durable/dbos-prompt-reservations.ts

@@ -0,0 +1,320 @@
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DbosStepRecord } from "./dbos-backend.js";
+import { DURABLE_FORMAT_VERSION } from "./format-version.js";
+import { promptReservationToken, type PromptReservationToken } from "./prompt-reservation-state.js";
+import type { DurableWorkflowMetadata } from "./types.js";
+
+const RESERVATION_PREFIX = "__atomic_prompt_reservation";
+
+export interface DbosActivePromptReservation {
+  readonly generation: number;
+  readonly tokenId: string;
+}
+
+export interface DbosPromptReservationState {
+  readonly active: Map<string, DbosActivePromptReservation>;
+  readonly maxGeneration: Map<string, number>;
+  readonly releasedGeneration: Map<string, number>;
+  readonly availableTokens: Set<string>;
+  readonly consumedTokens: Set<string>;
+  readonly baseline: number;
+  readonly epoch: string;
+  hasEvents: boolean;
+}
+
+export function emptyDbosPromptReservationState(baseline = 0, epoch: string = crypto.randomUUID()): DbosPromptReservationState {
+  const normalized = Math.max(0, Math.trunc(baseline));
+  const availableTokens = new Set<string>();
+  for (let index = 0; index < normalized; index++) availableTokens.add(`baseline:${epoch}:${index}`);
+  return {
+    active: new Map(),
+    maxGeneration: new Map(),
+    releasedGeneration: new Map(),
+    availableTokens,
+    consumedTokens: new Set(),
+    baseline: normalized,
+    epoch,
+    hasEvents: false,
+  };
+}
+
+export function promptReservationStepName(
+  reservationId: string,
+  generation: number,
+  operation: "reserve" | "release",
+  epoch: string,
+): string {
+  return `${RESERVATION_PREFIX}:${operation}:${reservationId}:${generation}:${epoch}`;
+}
+
+export function encodePromptReservationEvent(input: {
+  readonly reservationId: string;
+  readonly generation: number;
+  readonly operation: "reserve" | "release";
+  readonly tokenId: string;
+  readonly epoch: string;
+}): WorkflowSerializableValue {
+  return {
+    __atomicPromptReservation: true,
+    version: DURABLE_FORMAT_VERSION,
+    reservationId: input.reservationId,
+    generation: input.generation,
+    operation: input.operation,
+    tokenId: input.tokenId,
+    epoch: input.epoch,
+  };
+}
+
+export function isDbosPromptStateStep(stepName: string): boolean {
+  return stepName.startsWith(`${RESERVATION_PREFIX}:`);
+}
+
+interface ParsedReservation {
+  readonly reservationId: string;
+  readonly generation: number;
+  readonly operation: "reserve" | "release";
+  readonly tokenId: string;
+  readonly epoch: string;
+}
+
+interface ReservationGeneration {
+  tokenId: string;
+  reserved: boolean;
+  released: boolean;
+}
+
+export function classifyDbosPromptReservationState(
+  records: readonly DbosStepRecord[],
+  baseline = 0,
+  epoch: string = crypto.randomUUID(),
+): DbosPromptReservationState {
+  const state = emptyDbosPromptReservationState(baseline, epoch);
+  const generations = new Map<string, Map<number, ReservationGeneration>>();
+  for (const record of records) {
+    if (!isDbosPromptStateStep(record.stepName)) continue;
+    const event = parseReservation(record.output);
+    if (event === undefined || event.epoch !== epoch) continue;
+    state.hasEvents = true;
+    let byGeneration = generations.get(event.reservationId);
+    if (byGeneration === undefined) {
+      byGeneration = new Map();
+      generations.set(event.reservationId, byGeneration);
+    }
+    const entry = byGeneration.get(event.generation) ?? {
+      tokenId: event.tokenId,
+      reserved: false,
+      released: false,
+    };
+    if (entry.tokenId !== event.tokenId) continue;
+    if (event.operation === "reserve") entry.reserved = true;
+    else entry.released = true;
+    byGeneration.set(event.generation, entry);
+  }
+
+  for (const [reservationId, byGeneration] of generations) {
+    const maxGeneration = Math.max(...byGeneration.keys());
+    state.maxGeneration.set(reservationId, maxGeneration);
+    for (const [generation, entry] of [...byGeneration].sort(([a], [b]) => a - b)) {
+      if (entry.released) {
+        state.releasedGeneration.set(reservationId, Math.max(state.releasedGeneration.get(reservationId) ?? 0, generation));
+        consumeToken(state, entry.tokenId);
+      }
+      if (generation === maxGeneration && entry.reserved && !entry.released
+        && !state.consumedTokens.has(entry.tokenId)) {
+        state.active.set(reservationId, { generation, tokenId: entry.tokenId });
+        state.availableTokens.add(entry.tokenId);
+      }
+    }
+  }
+  return state;
+}
+
+export function promptReservationAdjustment(state: DbosPromptReservationState): number {
+  return state.availableTokens.size - state.baseline;
+}
+
+function parseReservation(output: WorkflowSerializableValue): ParsedReservation | undefined {
+  if (!isRecord(output) || output["__atomicPromptReservation"] !== true
+    || output["version"] !== DURABLE_FORMAT_VERSION
+    || typeof output["reservationId"] !== "string"
+    || typeof output["generation"] !== "number"
+    || !Number.isInteger(output["generation"]) || output["generation"] < 1
+    || (output["operation"] !== "reserve" && output["operation"] !== "release")
+    || typeof output["tokenId"] !== "string" || typeof output["epoch"] !== "string") return undefined;
+  return {
+    reservationId: output["reservationId"], generation: output["generation"],
+    operation: output["operation"], tokenId: output["tokenId"], epoch: output["epoch"],
+  };
+}
+
+function isRecord(value: WorkflowSerializableValue): value is Record<string, WorkflowSerializableValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+interface DbosPromptReservationHost {
+  readonly pendingPrompts: (workflowId: string) => number;
+  readonly adjustPendingPrompts: (workflowId: string, delta: number) => void;
+  readonly persist: (workflowId: string, stepName: string, output: WorkflowSerializableValue) => void;
+}
+
+export class DbosPromptReservationTracker {
+  private readonly baselines = new Map<string, number>();
+  private readonly states = new Map<string, DbosPromptReservationState>();
+
+  constructor(private readonly host: DbosPromptReservationHost) {}
+
+  registerWorkflow(workflowId: string, pending: number | undefined, existingPending: number): number {
+    if (pending === undefined) return this.register(workflowId, existingPending);
+    return this.states.has(workflowId) ? this.setBaseline(workflowId, pending) : this.register(workflowId, pending);
+  }
+
+  register(workflowId: string, pending: number): number {
+    const existing = this.states.get(workflowId);
+    if (existing !== undefined) return pendingPrompts(existing);
+    const normalized = Math.max(0, Math.trunc(pending));
+    this.baselines.set(workflowId, normalized);
+    this.states.set(workflowId, emptyDbosPromptReservationState(normalized));
+    return normalized;
+  }
+
+  setBaseline(workflowId: string, pending: number): number {
+    const normalized = Math.max(0, Math.trunc(pending));
+    this.baselines.set(workflowId, normalized);
+    this.states.set(workflowId, emptyDbosPromptReservationState(normalized));
+    return normalized;
+  }
+
+  delete(workflowId: string): void { this.baselines.delete(workflowId); this.states.delete(workflowId); }
+  clear(): void { this.baselines.clear(); this.states.clear(); }
+
+  metadata(
+    workflowId: string,
+    value: Omit<DurableWorkflowMetadata, "promptReservationEpoch">,
+  ): DurableWorkflowMetadata {
+    const state = this.state(workflowId);
+    return {
+      ...value,
+      pendingPrompts: this.baselines.get(workflowId) ?? value.pendingPrompts,
+      promptReservationEpoch: state.epoch,
+    };
+  }
+
+  hydrate(workflowId: string, baseline: number, records: readonly DbosStepRecord[], epoch?: string): number {
+    if (epoch === undefined) return 0;
+    const state = classifyDbosPromptReservationState(records, baseline, epoch);
+    this.baselines.set(workflowId, baseline);
+    this.states.set(workflowId, state);
+    return pendingPrompts(state);
+  }
+
+  adjust(workflowId: string, delta: number): void {
+    const state = this.state(workflowId);
+    const count = Math.max(0, Math.trunc(Math.abs(delta)));
+    for (let index = 0; index < count; index++) {
+      if (delta > 0) this.reserveScalar(workflowId, state);
+      else if (delta < 0) {
+        const tokenId = state.availableTokens.values().next().value as string | undefined;
+        if (tokenId === undefined) break;
+        const owner = [...state.active].find(([, reservation]) => reservation.tokenId === tokenId);
+        if (owner !== undefined) this.releaseGeneration(workflowId, state, owner[0], owner[1]);
+        else this.releaseUnownedToken(workflowId, state, tokenId);
+      }
+    }
+    this.syncPending(workflowId, state);
+  }
+
+  token(workflowId: string, reservationId: string): PromptReservationToken | undefined {
+    const reservation = this.state(workflowId).active.get(reservationId);
+    return reservation === undefined ? undefined : tokenFor(reservationId, reservation);
+  }
+
+  reserve(workflowId: string, reservationId: string): PromptReservationToken {
+    const state = this.state(workflowId);
+    const current = state.active.get(reservationId);
+    if (current !== undefined) return tokenFor(reservationId, current);
+    const generation = (state.maxGeneration.get(reservationId) ?? 0) + 1;
+    const reservation = { generation, tokenId: `prompt:${state.epoch}:${encodeURIComponent(reservationId)}:${generation}` };
+    applyReserve(state, reservationId, reservation);
+    this.syncPending(workflowId, state);
+    this.persistReservation(workflowId, state, reservationId, reservation, "reserve");
+    return tokenFor(reservationId, reservation);
+  }
+
+  release(workflowId: string, reservationId: string, token: PromptReservationToken): void {
+    const state = this.state(workflowId);
+    const reservation = state.active.get(reservationId);
+    if (reservation === undefined || token.reservationId !== reservationId
+      || token.generation !== reservation.generation || token.tokenId !== reservation.tokenId) return;
+    this.releaseGeneration(workflowId, state, reservationId, reservation);
+    this.syncPending(workflowId, state);
+  }
+
+  private reserveScalar(workflowId: string, state: DbosPromptReservationState): void {
+    const id = crypto.randomUUID();
+    const reservation = { generation: 1, tokenId: `scalar:${state.epoch}:${id}` };
+    applyReserve(state, `__scalar:${id}`, reservation);
+    this.persistReservation(workflowId, state, `__scalar:${id}`, reservation, "reserve");
+  }
+
+  private releaseUnownedToken(workflowId: string, state: DbosPromptReservationState, tokenId: string): void {
+    const reservationId = `__token_release:${crypto.randomUUID()}`;
+    const reservation = { generation: 1, tokenId };
+    state.maxGeneration.set(reservationId, 1);
+    state.releasedGeneration.set(reservationId, 1);
+    consumeToken(state, tokenId);
+    state.hasEvents = true;
+    this.persistReservation(workflowId, state, reservationId, reservation, "release");
+  }
+
+  private releaseGeneration(workflowId: string, state: DbosPromptReservationState, reservationId: string, reservation: DbosActivePromptReservation): void {
+    applyRelease(state, reservationId, reservation);
+    this.persistReservation(workflowId, state, reservationId, reservation, "release");
+  }
+
+  private state(workflowId: string): DbosPromptReservationState {
+    let state = this.states.get(workflowId);
+    if (state === undefined) {
+      state = emptyDbosPromptReservationState(this.baselines.get(workflowId) ?? 0);
+      this.states.set(workflowId, state);
+    }
+    return state;
+  }
+
+  private syncPending(workflowId: string, state: DbosPromptReservationState): void {
+    const delta = pendingPrompts(state) - this.host.pendingPrompts(workflowId);
+    if (delta !== 0) this.host.adjustPendingPrompts(workflowId, delta);
+  }
+
+  private persistReservation(workflowId: string, state: DbosPromptReservationState, reservationId: string, reservation: DbosActivePromptReservation, operation: "reserve" | "release"): void {
+    this.host.persist(
+      workflowId,
+      promptReservationStepName(reservationId, reservation.generation, operation, state.epoch),
+      encodePromptReservationEvent({ reservationId, operation, ...reservation, epoch: state.epoch }),
+    );
+  }
+}
+
+function tokenFor(reservationId: string, reservation: DbosActivePromptReservation): PromptReservationToken {
+  return promptReservationToken({ reservationId, generation: reservation.generation, tokenId: reservation.tokenId });
+}
+
+function pendingPrompts(state: DbosPromptReservationState): number { return state.availableTokens.size; }
+
+function applyReserve(state: DbosPromptReservationState, reservationId: string, reservation: DbosActivePromptReservation): void {
+  state.maxGeneration.set(reservationId, reservation.generation);
+  state.active.set(reservationId, reservation);
+  if (!state.consumedTokens.has(reservation.tokenId)) state.availableTokens.add(reservation.tokenId);
+  state.hasEvents = true;
+}
+
+function applyRelease(state: DbosPromptReservationState, reservationId: string, reservation: DbosActivePromptReservation): void {
+  state.active.delete(reservationId);
+  state.releasedGeneration.set(reservationId, Math.max(state.releasedGeneration.get(reservationId) ?? 0, reservation.generation));
+  consumeToken(state, reservation.tokenId);
+  state.hasEvents = true;
+}
+
+function consumeToken(state: DbosPromptReservationState, tokenId: string): void {
+  state.availableTokens.delete(tokenId);
+  state.consumedTokens.add(tokenId);
+}