@bastani/atomic 0.9.8-alpha.1 → 0.9.9-alpha.1

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

@@ -1,10 +1,12 @@
 /** DBOS-backed durable backend adapter, loaded only when configured. */
 
-import type { DurableCheckpoint, DurableCheckpointEntry, DurableWorkflowHandle, DurableWorkflowStatus, ResumableWorkflowEntry } from "./types.js";
+import type { DurableCheckpoint, DurableWorkflowHandle, DurableWorkflowStatus, ResumableWorkflowEntry } from "./types.js";
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { WorkflowSerializableObject as DurableInputs } from "./types.js";
 import { InMemoryDurableBackend, type DurableWorkflowBackend, type WorkflowRegistrationInput } from "./backend.js";
-import { encodeCheckpoint, decodeToCheckpoint } from "./dbos-envelope.js";
+import { encodeCheckpoint, classifyCheckpointPayload } from "./dbos-envelope.js";
+import { classifyLatestMetadata, encodeMetadata, isMetadataStep, metadataStepName } from "./dbos-metadata.js";
+import { DBOS_DELETION_STEP, classifyDbosDeletionTombstone, encodeDbosDeletionTombstone } from "./dbos-tombstone.js";
 
 // ---------------------------------------------------------------------------
 // SDK abstraction
@@ -28,6 +30,8 @@ export interface DbosSdkHandle {
   readonly listStepRecords: (workflowId: string) => Promise<readonly DbosStepRecord[]>;
   /** Record a checkpoint step output (envelope) to DBOS. */
   readonly recordStepOutput: (workflowId: string, stepName: string, output: WorkflowSerializableValue) => Promise<void>;
+  /** Permanently delete a root workflow and all prefix checkpoint records. */
+  readonly deleteWorkflowData: (workflowId: string) => Promise<void>;
 }
 
 export interface DbosWorkflowInfo {
@@ -81,6 +85,7 @@ interface DbosStatic {
   resumeWorkflow(workflowId: string): Promise<DbosWorkflowHandle>;
   cancelWorkflow(workflowId: string, options?: { readonly cancelChildren?: boolean }): Promise<void>;
   listWorkflows(input: Record<string, WorkflowSerializableValue>): Promise<readonly DbosStatus[]>;
+  deleteWorkflows(workflowIds: string[], deleteChildren?: boolean): Promise<void>;
 }
 
 export function isDbosConfigured(): boolean {
@@ -158,6 +163,17 @@ function createRealDbosHandle(
     async recordStepOutput(workflowId, stepName, output) {
       await dbos.startWorkflow(checkpointWorkflow, { workflowID: checkpointId(workflowId, stepName) })(workflowId, stepName, output);
     },
+    async deleteWorkflowData(workflowId) {
+      const prefix = `${workflowId}:checkpoint:`;
+      const checkpointIds: string[] = [];
+      const pageSize = 1_000;
+      for (let offset = 0;; offset += pageSize) {
+        const page = await dbos.listWorkflows({ workflow_id_prefix: prefix, limit: pageSize, offset });
+        checkpointIds.push(...page.map((status) => status.workflowID ?? status.workflowId ?? "").filter((id) => id.length > 0));
+        if (page.length < pageSize) break;
+      }
+      await dbos.deleteWorkflows([...new Set([workflowId, ...checkpointIds])], true);
+    },
   };
 }
 
@@ -202,6 +218,9 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
   private readonly mem = new InMemoryDurableBackend();
   private readonly sdk: DbosSdkHandle;
   private readonly hydrated = new Set<string>();
+  private readonly incompatible = new Set<string>();
+  private readonly compatible = new Set<string>();
+  private readonly locallyRegistered = new Set<string>();
   private writeQueue: Promise<void> = Promise.resolve();
   private writeErrors: Error[] = [];
 
@@ -210,6 +229,9 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
   }
 
   registerWorkflow(handle: WorkflowRegistrationInput): void {
+    this.incompatible.delete(handle.workflowId);
+    this.compatible.add(handle.workflowId);
+    this.locallyRegistered.add(handle.workflowId);
     this.mem.registerWorkflow(handle);
     this.enqueueWrite(async () => {
       await this.sdk.startWorkflow(handle.workflowId, handle.name, handle.inputs);
@@ -218,12 +240,15 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
   }
 
   recordCheckpoint(checkpoint: DurableCheckpoint): void {
+    if (!this.isWorkflowLoadable(checkpoint.workflowId)) return;
     this.mem.recordCheckpoint(checkpoint);
     this.enqueueWrite(() => this.persistCheckpoint(checkpoint));
   }
 
   async recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void> {
+    if (!this.isWorkflowLoadable(checkpoint.workflowId)) return;
     await this.enqueueWrite(async () => {
+      if (!this.isWorkflowLoadable(checkpoint.workflowId)) return;
       await this.persistCheckpointRecord(checkpoint);
       this.mem.recordCheckpoint(checkpoint);
       await this.writeMetadata(checkpoint.workflowId);
@@ -247,17 +272,48 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
   getWorkflow(workflowId: string): DurableWorkflowHandle | undefined { return this.mem.getWorkflow(workflowId); }
 
   setWorkflowStatus(workflowId: string, status: DurableWorkflowStatus, pendingPrompts?: number, resumable?: boolean): void {
+    if (!this.isWorkflowLoadable(workflowId)) return;
     this.mem.setWorkflowStatus(workflowId, status, pendingPrompts, resumable);
     this.enqueueWrite(async () => {
+      if (!this.isWorkflowLoadable(workflowId)) return;
       if (status === "cancelled") await this.sdk.cancelWorkflow(workflowId);
       else if (status === "running") await this.sdk.resumeWorkflow(workflowId);
       await this.writeMetadata(workflowId);
     });
   }
 
-  listResumableWorkflows(): readonly ResumableWorkflowEntry[] { return this.mem.listResumableWorkflows(); }
-  toCacheEntry(workflowId: string) { return this.mem.toCacheEntry(workflowId); }
-  reset(): void { this.mem.reset(); this.hydrated.clear(); this.writeQueue = Promise.resolve(); this.writeErrors = []; }
+  listResumableWorkflows(): readonly ResumableWorkflowEntry[] {
+    return this.mem.listResumableWorkflows().filter((entry) => !this.incompatible.has(entry.workflowId));
+  }
+  listCompletedWorkflows(): readonly ResumableWorkflowEntry[] {
+    return this.mem.listCompletedWorkflows().filter((entry) => !this.incompatible.has(entry.workflowId));
+  }
+  toCacheEntry(workflowId: string) { return this.incompatible.has(workflowId) ? undefined : this.mem.toCacheEntry(workflowId); }
+  async deleteWorkflow(workflowId: string): Promise<void> {
+    this.incompatible.add(workflowId);
+    this.compatible.delete(workflowId);
+    this.locallyRegistered.delete(workflowId);
+    this.hydrated.delete(workflowId);
+    await this.mem.deleteWorkflow(workflowId);
+    await this.enqueueWrite(async () => {
+      await this.sdk.deleteWorkflowData(workflowId);
+      await this.sdk.recordStepOutput(workflowId, DBOS_DELETION_STEP, encodeDbosDeletionTombstone(workflowId));
+    });
+  }
+  isWorkflowLoadable(workflowId: string): boolean {
+    return !this.incompatible.has(workflowId)
+      && (this.locallyRegistered.has(workflowId) || this.compatible.has(workflowId));
+  }
+  reset(): void {
+    this.mem.reset();
+    this.hydrated.clear();
+    this.incompatible.clear();
+    this.compatible.clear();
+    this.locallyRegistered.clear();
+    this.writeQueue = Promise.resolve();
+    this.writeErrors = [];
+  }
+
   async flush(): Promise<void> {
     await this.writeQueue;
     if (this.writeErrors.length === 0) return;
@@ -266,63 +322,76 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
     throw first;
   }
 
-  /**
-   * Hydrate a single workflow's handle and checkpoints from DBOS into the
-   * in-memory mirror. Idempotent: skips workflows already hydrated with
-   * checkpoints. Safe to call before synchronous replay reads.
-   */
   async hydrateWorkflow(workflowId: string): Promise<void> {
-    if (this.hydrated.has(workflowId) && this.mem.getWorkflow(workflowId) !== undefined) return;
+    if (this.locallyRegistered.has(workflowId)) return;
     const info = await this.sdk.retrieveWorkflow(workflowId);
-    if (info !== undefined && this.mem.getWorkflow(workflowId) === undefined) {
-      this.mem.registerWorkflow({
-        workflowId: info.workflowId,
-        name: info.name,
-        inputs: info.inputs ?? {},
-        createdAt: info.createdAt,
-        status: dbosStatusToDurable(info.status),
-      });
+    if (info !== undefined) {
+      await this.hydrateInfo(info);
+      return;
     }
-    const stepRecords = await this.sdk.listStepRecords(workflowId);
-    this.applyMetadata(workflowId, stepRecords);
-    for (const rec of stepRecords) {
-      if (isMetadataStep(rec.stepName)) continue;
-      const cp = decodeToCheckpoint(workflowId, rec.stepName, rec.output);
-      if (cp !== undefined) this.mem.recordCheckpoint(cp);
-    }
-    this.hydrated.add(workflowId);
+    const records = await this.sdk.listStepRecords(workflowId);
+    const deletion = classifyDbosDeletionTombstone(records, workflowId);
+    if (deletion !== "absent") await this.suppressWorkflow(workflowId);
   }
 
-  /**
-   * Hydrate all resumable workflows from DBOS into the in-memory mirror.
-   * Called by the resume/list path before enumerating resumable entries so
-   * a fresh process discovers workflows persisted by a prior session.
-   */
   async hydrateResumableWorkflows(): Promise<void> {
     const all = await this.sdk.listAllWorkflows();
     for (const info of all) {
-      if (this.mem.getWorkflow(info.workflowId) === undefined) {
-        this.mem.registerWorkflow({
-          workflowId: info.workflowId,
-          name: info.name,
-          inputs: info.inputs ?? {},
-          createdAt: info.createdAt,
-          status: dbosStatusToDurable(info.status),
-        });
+      if (this.locallyRegistered.has(info.workflowId)) continue;
+      await this.hydrateInfo(info);
+    }
+  }
+
+  private async hydrateInfo(info: DbosWorkflowInfo): Promise<void> {
+    const records = await this.sdk.listStepRecords(info.workflowId);
+    const metadata = classifyLatestMetadata(records, info.workflowId);
+    if (metadata.kind === "legacy") {
+      await this.cleanupLegacyWorkflow(info.workflowId);
+      return;
+    }
+    if (metadata.kind !== "current") {
+      await this.suppressWorkflow(info.workflowId);
+      return;
+    }
+    const checkpoints: DurableCheckpoint[] = [];
+    for (const record of records) {
+      if (isMetadataStep(record.stepName) || record.stepName === DBOS_DELETION_STEP) continue;
+      const classified = classifyCheckpointPayload(info.workflowId, record.stepName, record.output);
+      if (classified.kind === "legacy") {
+        await this.cleanupLegacyWorkflow(info.workflowId);
+        return;
       }
-      if (!this.hydrated.has(info.workflowId)) {
-        const stepRecords = await this.sdk.listStepRecords(info.workflowId);
-        this.applyMetadata(info.workflowId, stepRecords);
-        for (const rec of stepRecords) {
-          if (isMetadataStep(rec.stepName)) continue;
-          const cp = decodeToCheckpoint(info.workflowId, rec.stepName, rec.output);
-          if (cp !== undefined) this.mem.recordCheckpoint(cp);
-        }
-        this.hydrated.add(info.workflowId);
+      if (classified.kind === "unknown") {
+        await this.suppressWorkflow(info.workflowId);
+        return;
       }
+      checkpoints.push(classified.checkpoint);
+    }
+    await this.mem.deleteWorkflow(info.workflowId);
+    this.incompatible.delete(info.workflowId);
+    this.compatible.add(info.workflowId);
+    this.applyMetadata(info.workflowId, metadata.entry);
+    checkpoints.forEach((checkpoint) => this.mem.recordCheckpoint(checkpoint));
+    this.hydrated.add(info.workflowId);
+  }
+
+  private async cleanupLegacyWorkflow(workflowId: string): Promise<void> {
+    try {
+      await this.deleteWorkflow(workflowId);
+    } catch {
+      // deleteWorkflow marks the in-memory mirror incompatible before durable
+      // cleanup. Its write queue records/logs the error, while hydration must
+      // still return a filtered catalog and allow later discovery to retry.
     }
   }
 
+  private async suppressWorkflow(workflowId: string): Promise<void> {
+    this.incompatible.add(workflowId);
+    this.compatible.delete(workflowId);
+    this.hydrated.delete(workflowId);
+    await this.mem.deleteWorkflow(workflowId);
+  }
+
   private enqueueWrite(fn: () => Promise<void>): Promise<void> {
     const next = this.writeQueue.then(fn, fn);
     this.writeQueue = next.catch((err) => {
@@ -339,14 +408,7 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
     await this.sdk.recordStepOutput(workflowId, metadataStepName(entry.ts), encodeMetadata(entry));
   }
 
-  private applyMetadata(workflowId: string, records: readonly DbosStepRecord[]): void {
-    const entries = records
-      .filter((r) => isMetadataStep(r.stepName))
-      .map((r) => decodeMetadata(r.output))
-      .filter((entry): entry is DurableCheckpointEntry => entry !== undefined)
-      .sort((a, b) => a.ts - b.ts);
-    const entry = entries.at(-1);
-    if (entry === undefined) return;
+  private applyMetadata(workflowId: string, entry: import("./types.js").DurableCheckpointEntry): void {
     this.mem.registerWorkflow({
       workflowId,
       name: entry.name,
@@ -367,116 +429,4 @@ export class DbosDurableBackend implements DurableWorkflowBackend {
   }
 }
 
-const METADATA_STEP_PREFIX = "__atomic_metadata";
-const METADATA_VERSION = 1;
-
-function metadataStepName(ts: number): string {
-  return `${METADATA_STEP_PREFIX}:${ts}:${crypto.randomUUID()}`;
-}
-
-function isMetadataStep(stepName: string): boolean {
-  return stepName === METADATA_STEP_PREFIX || stepName.startsWith(`${METADATA_STEP_PREFIX}:`);
-}
-
-interface DbosMetadataEnvelope {
-  readonly __atomicDurableMetadata: true;
-  readonly version: 1;
-  readonly entry: WorkflowSerializableValue;
-}
-
-function encodeMetadata(entry: DurableCheckpointEntry): WorkflowSerializableValue {
-  return {
-    __atomicDurableMetadata: true,
-    version: METADATA_VERSION,
-    entry: {
-      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,
-    },
-  };
-}
-
-function decodeMetadata(value: WorkflowSerializableValue): DurableCheckpointEntry | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  const raw = value as Partial<DbosMetadataEnvelope>;
-  if (raw.__atomicDurableMetadata !== true || raw.version !== METADATA_VERSION) return undefined;
-  const entry = raw.entry;
-  if (entry === undefined) return undefined;
-  return parseDurableCheckpointEntry(entry);
-}
-
-function parseDurableCheckpointEntry(value: WorkflowSerializableValue): DurableCheckpointEntry | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-  const entry = value as Partial<DurableCheckpointEntry>;
-  if (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 {
-    type: "workflow.durable.checkpoint",
-    workflowId: entry.workflowId,
-    name: entry.name,
-    inputs: entry.inputs,
-    status: entry.status,
-    completedCheckpoints: entry.completedCheckpoints,
-    pendingPrompts: entry.pendingPrompts,
-    ts: entry.ts,
-    ...(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 } : {}),
-  };
-}
-
-function isDurableWorkflowStatus(value: string): value is DurableWorkflowStatus {
-  return value === "running"
-    || value === "paused"
-    || value === "completed"
-    || value === "failed"
-    || value === "cancelled"
-    || value === "blocked";
-}
-
-function dbosStatusToDurable(status: string): DurableWorkflowStatus {
-  switch (status) {
-    case "SUCCESS": return "completed";
-    case "ERROR": return "failed";
-    case "CANCELLED": return "cancelled";
-    case "PENDING":
-    case "ENQUEUED":
-    case "DELAYED":
-      return "running";
-    default: return "running";
-  }
-}
+// Metadata encoding/classification lives in dbos-metadata.ts to keep this adapter focused.

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

@@ -23,9 +23,10 @@ import type {
   DurableUiCheckpoint,
   UiPromptKind,
 } from "./types.js";
+import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 /** Envelope schema version. */
-export const DBOS_ENVELOPE_VERSION = 1;
+export const DBOS_ENVELOPE_VERSION = DURABLE_FORMAT_VERSION;
 
 /** Marker key present on every envelope payload. */
 const ENVELOPE_MARKER = "__dbos_checkpoint__";
@@ -105,9 +106,35 @@ export function encodeCheckpoint(cp: DurableCheckpoint): DbosCheckpointEnvelope
  * Type guard: is this value a checkpoint envelope?
  */
 export function isCheckpointEnvelope(value: WorkflowSerializableValue | undefined): value is DbosCheckpointEnvelope {
+  if (!hasCheckpointEnvelopeMarker(value)) return false;
+  return value.v === DBOS_ENVELOPE_VERSION;
+}
+
+function hasCheckpointEnvelopeMarker(value: WorkflowSerializableValue | undefined): value is Record<string, WorkflowSerializableValue> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-  const obj = value as Record<string, unknown>;
-  return obj[ENVELOPE_MARKER] === ENVELOPE_MARKER;
+  return (value as Record<string, WorkflowSerializableValue>)[ENVELOPE_MARKER] === ENVELOPE_MARKER;
+}
+export type DbosCheckpointCompatibility =
+  | { readonly kind: "current"; readonly checkpoint: DurableCheckpoint }
+  | { readonly kind: "legacy" }
+  | { readonly kind: "unknown" };
+
+/** Classify and decode one DBOS checkpoint payload without reinterpreting marked formats. */
+export function classifyCheckpointPayload(
+  workflowId: string,
+  stepName: string,
+  value: WorkflowSerializableValue,
+): DbosCheckpointCompatibility {
+  if (!hasCheckpointEnvelopeMarker(value)) return { kind: "current", checkpoint: decodeLegacy(workflowId, stepName, value) };
+  const compatibility = classifyDurableFormatVersion(value.v);
+  if (compatibility !== "current") return { kind: compatibility };
+  const hasOutput = value["hasOutput"];
+  const containsOutput = value["output"] !== undefined;
+  if (value["checkpointId"] !== stepName || typeof hasOutput !== "boolean" || hasOutput !== containsOutput) {
+    return { kind: "unknown" };
+  }
+  const checkpoint = decodeEnvelope(workflowId, value as DbosCheckpointEnvelope);
+  return checkpoint === undefined ? { kind: "unknown" } : { kind: "current", checkpoint };
 }
 
 /**
@@ -124,15 +151,18 @@ export function decodeToCheckpoint(
   stepName: string,
   value: WorkflowSerializableValue,
 ): DurableCheckpoint | undefined {
-  if (isCheckpointEnvelope(value)) return decodeEnvelope(workflowId, value);
-  if (value === undefined) return undefined;
-  return decodeLegacy(workflowId, stepName, value);
+  const classified = classifyCheckpointPayload(workflowId, stepName, value);
+  return classified.kind === "current" ? classified.checkpoint : undefined;
 }
 
 function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): DurableCheckpoint | undefined {
+  if (typeof env.checkpointId !== "string" || env.checkpointId.length === 0
+    || typeof env.completedAt !== "number" || !Number.isFinite(env.completedAt)
+    || (env.name !== undefined && typeof env.name !== "string")
+    || (env.hasOutput !== undefined && typeof env.hasOutput !== "boolean")) return undefined;
   const common = { workflowId, checkpointId: env.checkpointId, completedAt: env.completedAt };
   if (env.kind === "tool") {
-    if (env.argsHash === undefined || env.output === undefined) return undefined;
+    if (typeof env.argsHash !== "string" || env.output === undefined) return undefined;
     return {
       kind: "tool",
       ...common,
@@ -142,7 +172,8 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
     } as DurableToolCheckpoint;
   }
   if (env.kind === "ui") {
-    if (env.promptHash === undefined || env.promptKind === undefined || env.output === undefined) return undefined;
+    if (typeof env.promptHash !== "string" || !isUiPromptKind(env.promptKind) || env.output === undefined
+      || (env.message !== undefined && typeof env.message !== "string")) return undefined;
     return {
       kind: "ui",
       ...common,
@@ -152,6 +183,18 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
       response: env.output,
     } as DurableUiCheckpoint;
   }
+  if (env.kind !== "stage"
+    || (env.replayKey !== undefined && typeof env.replayKey !== "string")
+    || (env.sessionId !== undefined && typeof env.sessionId !== "string")
+    || (env.sessionFile !== undefined && typeof env.sessionFile !== "string")
+    || !isOptionalFiniteNumber(env.startedAt)
+    || !isOptionalFiniteNumber(env.endedAt)
+    || !isOptionalFiniteNumber(env.durationMs)
+    || (env.result !== undefined && typeof env.result !== "string")
+    || (env.model !== undefined && typeof env.model !== "string")
+    || (env.fastMode !== undefined && typeof env.fastMode !== "boolean")
+    || (env.attemptedModels !== undefined && !isStringArray(env.attemptedModels))
+    || (env.modelAttempts !== undefined && !isModelAttempts(env.modelAttempts))) return undefined;
   return {
     kind: "stage",
     ...common,
@@ -172,6 +215,39 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
 }
 
 
+function isModelAttempts(value: WorkflowSerializableValue | undefined): boolean {
+  return Array.isArray(value) && value.every((attempt) => {
+    if (typeof attempt !== "object" || attempt === null || Array.isArray(attempt)) return false;
+    const record = attempt as Record<string, WorkflowSerializableValue>;
+    return typeof record["model"] === "string"
+      && typeof record["success"] === "boolean"
+      && (record["reasoningLevel"] === undefined || isReasoningLevel(record["reasoningLevel"]))
+      && (record["error"] === undefined || typeof record["error"] === "string")
+      && (record["usage"] === undefined || isModelUsage(record["usage"]));
+  });
+}
+
+function isReasoningLevel(value: WorkflowSerializableValue): boolean {
+  return value === "off" || value === "minimal" || value === "low" || value === "medium"
+    || value === "high" || value === "xhigh" || value === "max";
+}
+
+function isModelUsage(value: WorkflowSerializableValue): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const usage = value as Record<string, WorkflowSerializableValue>;
+  return ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"]
+    .every((key) => usage[key] === undefined || (typeof usage[key] === "number" && Number.isFinite(usage[key])));
+}
+
+function isUiPromptKind(value: WorkflowSerializableValue | undefined): value is UiPromptKind {
+  return value === "input" || value === "confirm" || value === "select"
+    || value === "editor" || value === "custom";
+}
+
+function isOptionalFiniteNumber(value: WorkflowSerializableValue | undefined): boolean {
+  return value === undefined || (typeof value === "number" && Number.isFinite(value));
+}
+
 function isStringArray(value: WorkflowSerializableValue | undefined): value is readonly string[] {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }

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

@@ -0,0 +1,98 @@
+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";
+
+const METADATA_STEP_PREFIX = "__atomic_metadata";
+
+export type DbosMetadataCompatibility =
+  | { readonly kind: "current"; readonly entry: DurableCheckpointEntry }
+  | { readonly kind: "legacy" }
+  | { readonly kind: "unknown" }
+  | { readonly kind: "unavailable" };
+
+export function metadataStepName(ts: number): string {
+  return `${METADATA_STEP_PREFIX}:${ts}:${crypto.randomUUID()}`;
+}
+
+export function isMetadataStep(stepName: string): boolean {
+  return stepName === METADATA_STEP_PREFIX || stepName.startsWith(`${METADATA_STEP_PREFIX}:`);
+}
+
+export function encodeMetadata(entry: DurableCheckpointEntry): 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,
+    },
+  };
+}
+
+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 };
+}
+
+function metadataTimestamp(record: DbosStepRecord): number {
+  const segment = record.stepName.split(":")[1];
+  const fromName = segment === undefined ? Number.NaN : Number(segment);
+  return Number.isFinite(fromName) ? fromName : (record.completedAt ?? 0);
+}
+
+function parseDurableCheckpointEntry(
+  value: WorkflowSerializableValue | undefined,
+  workflowId: string,
+): DurableCheckpointEntry | 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;
+}
+
+function isDurableWorkflowStatus(value: string): value is DurableWorkflowStatus {
+  return value === "running" || value === "paused" || value === "completed"
+    || value === "failed" || value === "cancelled" || value === "blocked";
+}

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

@@ -0,0 +1,27 @@
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DbosStepRecord } from "./dbos-backend.js";
+import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
+
+export const DBOS_DELETION_STEP = "__atomic_deleted";
+
+export type DbosDeletionCompatibility = "current" | "unknown" | "absent";
+
+export function encodeDbosDeletionTombstone(workflowId: string): WorkflowSerializableValue {
+  return {
+    __atomicDurableDeleted: true,
+    version: DURABLE_FORMAT_VERSION,
+    workflowId,
+  };
+}
+
+export function classifyDbosDeletionTombstone(
+  records: readonly DbosStepRecord[],
+  workflowId: string,
+): DbosDeletionCompatibility {
+  const record = records.find((candidate) => candidate.stepName === DBOS_DELETION_STEP);
+  if (record === undefined) return "absent";
+  if (typeof record.output !== "object" || record.output === null || Array.isArray(record.output)) return "unknown";
+  const raw = record.output as Record<string, WorkflowSerializableValue>;
+  if (raw["__atomicDurableDeleted"] !== true || raw["workflowId"] !== workflowId) return "unknown";
+  return classifyDurableFormatVersion(raw["version"]) === "current" ? "current" : "unknown";
+}

package/dist/builtin/workflows/src/durable/factory.ts

@@ -87,7 +87,7 @@ export function createDefaultFileBackend(): DurableWorkflowBackend {
 export function createWorkflowFileBackend(workflowId: string): DurableWorkflowBackend {
   const dir = defaultDurableStateDir();
   if (dir === undefined) return createInMemoryBackend();
-  return new FileDurableBackend(durableStateFileFor(dir, workflowId));
+  return new FileDurableBackend(durableStateFileFor(dir, workflowId), workflowId);
 }
 
 function isDurabilityOptedOut(): boolean {