@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/src/durable/dbos-sdk-handle.ts

@@ -0,0 +1,161 @@
+/**
+ * Real `@dbos-inc/dbos-sdk` handle factory.
+ *
+ * Wraps the DBOS static executor into the {@link DbosSdkHandle} seam used by
+ * {@link DbosDurableBackend}. Kept separate from the backend adapter so both
+ * files stay within the repository file-length gate.
+ */
+
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { DbosSdkHandle, DbosStepRecord, DbosWorkflowInfo } from "./dbos-backend.js";
+
+interface DbosWorkflowHandle {
+  readonly workflowID?: string;
+  getStatus(): Promise<DbosStatus | null>;
+  getResult(): Promise<WorkflowSerializableValue>;
+}
+
+interface DbosStatus {
+  readonly workflowID?: string;
+  readonly workflowId?: string;
+  readonly workflowName?: string;
+  readonly name?: string;
+  readonly status?: string;
+  readonly createdAt?: number;
+  readonly input?: readonly WorkflowSerializableValue[];
+}
+
+/**
+ * Unique executor identity for this Atomic process. Multiple concurrent Atomic
+ * sessions share one DBOS database; a per-process id keeps DBOS-level recovery
+ * and workflow ownership scoped to the process that actually runs the work.
+ */
+const ATOMIC_EXECUTOR_ID = `atomic-${process.pid.toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
+
+export function getAtomicExecutorId(): string {
+  return ATOMIC_EXECUTOR_ID;
+}
+
+export interface DbosLogger {
+  info(value: unknown, metadata?: object): void;
+  debug(value: unknown, metadata?: object): void;
+  warn(value: unknown, metadata?: object): void;
+  error(value: unknown, metadata?: object): void;
+}
+
+export interface DbosConfiguration {
+  readonly name: string;
+  readonly systemDatabaseUrl?: string;
+  readonly runAdminServer: boolean;
+  readonly executorID: string;
+  readonly logger: DbosLogger;
+}
+
+export interface DbosStatic {
+  setConfig(config: DbosConfiguration): void;
+  launch(): Promise<void>;
+  shutdown(): Promise<void>;
+  registerWorkflow<Args extends readonly WorkflowSerializableValue[]>(
+    fn: (...args: Args) => Promise<WorkflowSerializableValue>,
+    config?: { readonly name?: string },
+  ): (...args: Args) => Promise<WorkflowSerializableValue>;
+  startWorkflow<Args extends readonly WorkflowSerializableValue[]>(
+    target: (...args: Args) => Promise<WorkflowSerializableValue>,
+    params?: { readonly workflowID?: string },
+  ): (...args: Args) => Promise<DbosWorkflowHandle>;
+  retrieveWorkflow(workflowId: string): DbosWorkflowHandle;
+  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 createRealDbosHandle(
+  dbos: DbosStatic,
+  mainWorkflow: (name: string, inputs: Record<string, WorkflowSerializableValue>) => Promise<WorkflowSerializableValue>,
+  checkpointWorkflow: (workflowId: string, stepName: string, output: WorkflowSerializableValue) => Promise<WorkflowSerializableValue>,
+): DbosSdkHandle {
+  const checkpointId = (workflowId: string, stepName: string): string => `${workflowId}:checkpoint:${stepName}`;
+  return {
+    launch: () => dbos.launch(),
+    shutdown: () => dbos.shutdown(),
+    async startWorkflow(workflowId, name, inputs) {
+      try {
+        await dbos.startWorkflow(mainWorkflow, { workflowID: workflowId })(name, { ...inputs });
+      } catch (err) {
+        if (!isDbosDuplicateWorkflowError(err)) throw err;
+      }
+    },
+    async retrieveWorkflow(workflowId) {
+      const statuses = await dbos.listWorkflows({ workflowIDs: [workflowId], loadInput: true, limit: 1 });
+      const status = statuses[0];
+      if (status === undefined) return undefined;
+      return statusToInfo(status, workflowId);
+    },
+    async cancelWorkflow(workflowId) { await dbos.cancelWorkflow(workflowId, { cancelChildren: true }); },
+    async resumeWorkflow(workflowId) { await dbos.resumeWorkflow(workflowId); },
+    async listAllWorkflows() {
+      const statuses = await dbos.listWorkflows({ workflowName: "atomicWorkflowHandle", loadInput: true, sortDesc: true });
+      return statuses.map((s) => statusToInfo(s, s.workflowID ?? s.workflowId ?? ""));
+    },
+    async listStepRecords(workflowId) {
+      const prefix = `${workflowId}:checkpoint:`;
+      const statuses = await dbos.listWorkflows({ workflow_id_prefix: prefix, loadOutput: true, sortDesc: false });
+      const records: DbosStepRecord[] = [];
+      for (const s of statuses) {
+        if (s.status !== "SUCCESS") continue;
+        const wid = s.workflowID ?? s.workflowId ?? "";
+        const stepName = wid.slice(prefix.length);
+        if (stepName.length === 0) continue;
+        const handle = dbos.retrieveWorkflow(wid);
+        const output = await handle.getResult();
+        records.push({ stepName, output, completedAt: s.createdAt });
+      }
+      return records;
+    },
+    async recordStepOutput(workflowId, stepName, output) {
+      let handle: DbosWorkflowHandle;
+      try {
+        handle = await dbos.startWorkflow(checkpointWorkflow, { workflowID: checkpointId(workflowId, stepName) })(workflowId, stepName, output);
+      } catch (err) {
+        if (!isDbosDuplicateWorkflowError(err)) throw err;
+        handle = dbos.retrieveWorkflow(checkpointId(workflowId, stepName));
+      }
+      // Await completion so the record is durable and readable before the
+      // caller's flush boundary; duplicates resolve to the first stored output.
+      await handle.getResult();
+    },
+    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);
+    },
+  };
+}
+
+function isDbosDuplicateWorkflowError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return /duplicate|conflict|already/i.test(msg);
+}
+
+function statusToInfo(status: DbosStatus, fallbackId: string): DbosWorkflowInfo {
+  const info: DbosWorkflowInfo = {
+    workflowId: status.workflowID ?? status.workflowId ?? fallbackId,
+    name: status.workflowName ?? status.name ?? "atomicWorkflowHandle",
+    status: status.status ?? "PENDING",
+    createdAt: status.createdAt ?? Date.now(),
+  };
+  if (status.input !== undefined && status.input.length >= 2) {
+    const inputs = status.input[1];
+    if (typeof inputs === "object" && inputs !== null && !Array.isArray(inputs)) {
+      return { ...info, inputs: inputs as import("./types.js").WorkflowSerializableObject };
+    }
+  }
+  return info;
+}

package/dist/builtin/workflows/src/durable/dbos-status-transition.ts

@@ -0,0 +1,62 @@
+import type { DbosMetadataClassification } from "./dbos-metadata.js";
+import type { DurableWorkflowHandle, DurableWorkflowMetadata, DurableWorkflowStatus } from "./types.js";
+import { isAbsorbingDurableStatus } from "./workflow-status-transition.js";
+
+interface DbosStatusTransitionInput {
+  readonly expectedStatuses: readonly DurableWorkflowStatus[];
+  readonly status: DurableWorkflowStatus;
+  readonly flush: () => Promise<void>;
+  readonly read: () => Promise<DbosMetadataClassification>;
+  readonly local: () => DurableWorkflowHandle | undefined;
+  readonly reconcile: (metadata: DurableWorkflowMetadata) => void;
+  /** Atomically claim this generation's transition against concurrent processes. */
+  readonly claim?: (authoritative: DurableWorkflowMetadata, generation: number) => Promise<boolean>;
+  readonly write: () => Promise<void>;
+}
+
+/**
+ * Serialize local writes around authoritative generations and verify the
+ * persisted result. DBOS metadata classification makes terminal generations
+ * absorbing, so a stale nonterminal append cannot reopen a completed run.
+ * The optional claim step makes the read→write window safe across processes:
+ * every racer that observed the same generation competes for one durable
+ * first-writer-wins record before it may write.
+ */
+export async function transitionDbosWorkflowStatus(input: DbosStatusTransitionInput): Promise<boolean> {
+  await input.flush();
+  const authoritative = await input.read();
+  const local = input.local();
+  if (local === undefined || authoritative.kind !== "current"
+    || !input.expectedStatuses.includes(authoritative.metadata.status)) {
+    if (authoritative.kind === "current") input.reconcile(authoritative.metadata);
+    return false;
+  }
+
+  if (input.claim !== undefined && !(await input.claim(authoritative.metadata, authoritative.generation))) {
+    const current = await input.read();
+    if (current.kind === "current") input.reconcile(current.metadata);
+    return false;
+  }
+
+  try {
+    await input.write();
+  } catch (error) {
+    const persisted = await input.read();
+    if (persisted.kind === "current" && persisted.metadata.status === input.status) {
+      input.reconcile(persisted.metadata);
+      return true;
+    }
+    if (persisted.kind === "current"
+      && isAbsorbingDurableStatus(persisted.metadata.status, persisted.metadata.resumable)) {
+      input.reconcile(persisted.metadata);
+      return false;
+    }
+    throw error;
+  }
+  const persisted = await input.read();
+  if (persisted.kind !== "current" || persisted.metadata.status !== input.status) {
+    if (persisted.kind === "current") input.reconcile(persisted.metadata);
+    return false;
+  }
+  return true;
+}

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

@@ -1,6 +1,6 @@
 import type { WorkflowSerializableValue } from "../shared/types.js";
 import type { DbosStepRecord } from "./dbos-backend.js";
-import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
+import { isCurrentDurableFormat, DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 export const DBOS_DELETION_STEP = "__atomic_deleted";
 
@@ -23,5 +23,5 @@ export function classifyDbosDeletionTombstone(
   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";
+  return isCurrentDurableFormat(raw["version"]) ? "current" : "unknown";
 }

package/dist/builtin/workflows/src/durable/durable-hash.ts

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { WorkflowSerializableObject } from "./types.js";
+
+/** Compute a collision-resistant digest over canonical JSON. */
+export function durableHash(
+  value: WorkflowSerializableValue | WorkflowSerializableObject,
+): string {
+  const canonical = canonicalJsonString(value);
+  const digest = createHash("sha256").update(canonical).digest("hex");
+  return `h${digest.slice(0, 32)}`;
+}
+
+function canonicalJsonString(value: WorkflowSerializableValue): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJsonString).join(",")}]`;
+  const object = value as WorkflowSerializableObject;
+  const keys = Object.keys(object).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJsonString(object[key]!)}`).join(",")}}`;
+}

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

@@ -1,96 +1,36 @@
-/**
- * Durable backend factory.
- *
- * Resolves which backend to use based on configuration:
- * - Explicit override (for testing)
- * - DBOS/Postgres when `DBOS_SYSTEM_DATABASE_URL` is set and durability is not opted out
- * - File-backed fallback (default; zero infrastructure)
- *
- * cross-ref: issue #1498
- */
+/** DBOS-only durable backend factory and internal test injection seam. */
 
-import type { DurableWorkflowBackend } from "./backend.js";
-import { InMemoryDurableBackend } from "./backend.js";
-import { FileDurableBackend, WorkflowFileDurableBackend, defaultDurableStateDir, durableStateFileFor } from "./file-backend.js";
-import { createDbosDurableBackend } from "./dbos-backend.js";
+import { InMemoryDurableBackend, type DurableWorkflowBackend } from "./backend.js";
+import {
+  DbosNotReadyError,
+  getReadyDbosBackend,
+  getReadyDbosBackendSync,
+} from "./dbos-lifecycle.js";
 
-let globalBackend: DurableWorkflowBackend | undefined;
-let dbosInit: Promise<DurableWorkflowBackend | undefined> | undefined;
+let injectedBackend: DurableWorkflowBackend | undefined;
+let initializedBackend: DurableWorkflowBackend | undefined;
 
-const DURABLE_OPT_OUT_ENV = "ATOMIC_WORKFLOW_DURABLE";
-
-/**
- * Get the singleton durable backend. Creates one lazily on first call.
- * - If a backend was explicitly set via {@link setDurableBackend}, returns it.
- * - If `DBOS_SYSTEM_DATABASE_URL` is configured and durability was not opted
- *   out, the extension runtime upgrades to a DBOS-backed backend on launch.
- * - Otherwise returns the zero-infrastructure per-workflow file backend rooted
- *   under `~/.atomic/workflow-durable`, so cross-session resume is available by
- *   default without an opt-in environment variable. Set
- *   `ATOMIC_WORKFLOW_DURABLE=0` (or `false`/`off`/`memory`) to fail closed to
- *   process-local in-memory durability for sensitive environments.
- */
+/** Return the injected test backend or the process-wide ready DBOS backend. */
 export function getDurableBackend(): DurableWorkflowBackend {
-  if (globalBackend) return globalBackend;
-  if (isDurabilityOptedOut()) {
-    globalBackend = createInMemoryBackend();
-    return globalBackend;
-  }
-  // Always enable cross-session durability by default. DBOS initialization is
-  // async because the SDK is optional; the file backend is the durable baseline
-  // and remains the safe fallback if DBOS is unavailable.
-  globalBackend = createDefaultFileBackend();
-  return globalBackend;
+  const backend = injectedBackend ?? initializedBackend ?? getReadyDbosBackendSync();
+  if (backend === undefined) throw new DbosNotReadyError();
+  return backend;
 }
 
-/**
- * Explicitly set the durable backend. Used by tests and by the extension
- * runtime when it initializes DBOS.
- */
+/** Internal injection seam. Production initialization uses DBOS. */
 export function setDurableBackend(backend: DurableWorkflowBackend | undefined): void {
-  globalBackend = backend;
+  injectedBackend = backend;
+  if (backend === undefined) initializedBackend = undefined;
 }
 
-/**
- * Create a fresh in-memory backend (for tests).
- */
-export function createInMemoryBackend(): InMemoryDurableBackend {
+/** Create an isolated current-interface backend for tests only. */
+export function createInMemoryTestBackend(): InMemoryDurableBackend {
   return new InMemoryDurableBackend();
 }
 
-/** Initialize and install the DBOS backend when DBOS_SYSTEM_DATABASE_URL is set. */
-export async function initializeDbosDurableBackendFromEnv(): Promise<DurableWorkflowBackend | undefined> {
-  if (isDurabilityOptedOut()) return undefined;
-  const dbosUrl = process.env.DBOS_SYSTEM_DATABASE_URL;
-  if (dbosUrl === undefined || dbosUrl.length === 0) return undefined;
-  dbosInit ??= createDbosDurableBackend({ systemDatabaseUrl: dbosUrl }).then((backend) => {
-    setDurableBackend(backend);
-    return backend;
-  });
-  return dbosInit;
-}
-
-/**
- * Create the default durable backend. If no user home directory can be resolved,
- * fail closed to the process-local in-memory backend instead of writing to /tmp.
- */
-export function createDefaultFileBackend(): DurableWorkflowBackend {
-  const dir = defaultDurableStateDir();
-  if (dir === undefined) return createInMemoryBackend();
-  return new WorkflowFileDurableBackend(dir);
-}
-
-/**
- * Create a file-backed backend for a specific workflow id.
- * Each workflow gets its own state file for fast load/save.
- */
-export function createWorkflowFileBackend(workflowId: string): DurableWorkflowBackend {
-  const dir = defaultDurableStateDir();
-  if (dir === undefined) return createInMemoryBackend();
-  return new FileDurableBackend(durableStateFileFor(dir, workflowId), workflowId);
-}
-
-function isDurabilityOptedOut(): boolean {
-  const value = process.env[DURABLE_OPT_OUT_ENV]?.toLowerCase();
-  return value === "0" || value === "false" || value === "off" || value === "memory" || value === "in-memory";
+/** Configure, register, launch, and install the mandatory DBOS backend. */
+export async function initializeDurableBackend(): Promise<DurableWorkflowBackend> {
+  if (injectedBackend !== undefined) return injectedBackend;
+  initializedBackend ??= await getReadyDbosBackend();
+  return initializedBackend;
 }

package/dist/builtin/workflows/src/durable/format-version.ts

@@ -1,12 +1,6 @@
-/** Shared schema version for durable workflow state and discovery metadata. */
-export const DURABLE_FORMAT_VERSION = 2 as const;
-export const LEGACY_DURABLE_FORMAT_VERSION = 1 as const;
+/** Single current schema version for DBOS workflow state and metadata. */
+export const DURABLE_FORMAT_VERSION = 3 as const;
 
-export type DurableFormatCompatibility = "current" | "legacy" | "unknown";
-
-/** Classify an explicit durable format version without guessing about malformed data. */
-export function classifyDurableFormatVersion(value: unknown): DurableFormatCompatibility {
-  if (value === DURABLE_FORMAT_VERSION) return "current";
-  if (value === LEGACY_DURABLE_FORMAT_VERSION) return "legacy";
-  return "unknown";
+export function isCurrentDurableFormat(value: unknown): boolean {
+  return value === DURABLE_FORMAT_VERSION;
 }

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

@@ -1,12 +1,8 @@
-/**
- * Durable workflow backend — barrel export.
- *
- * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
- */
+/** DBOS-only durable workflow API. */
 
 export type {
   DurableCheckpoint,
-  DurableCheckpointEntry,
+  DurableWorkflowMetadata,
   DurableStageCheckpoint,
   DurableToolCheckpoint,
   DurableUiCheckpoint,
@@ -17,17 +13,24 @@ export type {
   WorkflowSerializableObject,
 } from "./types.js";
 
-export type { DurableWorkflowBackend } from "./backend.js";
+export type { DurableWorkflowBackend, DurableWorkflowCatalogEntries } from "./backend.js";
 export { InMemoryDurableBackend, durableHash } from "./backend.js";
-export { FileDurableBackend, WorkflowFileDurableBackend, defaultDurableStateDir, durableStateFileFor } from "./file-backend.js";
 export {
-  isDbosConfigured,
   DbosDurableBackend,
-  createDbosDurableBackend,
+  configureDbosDurableBackend,
+  type ConfiguredDbosDurability,
   type DbosSdkHandle,
   type DbosWorkflowInfo,
   type DbosStepRecord,
 } from "./dbos-backend.js";
+export {
+  DbosDurabilityError,
+  DbosNotReadyError,
+  configureDbosOnce,
+  launchDbosOnce,
+  getReadyDbosBackend,
+  shutdownDbos,
+} from "./dbos-lifecycle.js";
 export {
   encodeCheckpoint,
   decodeToCheckpoint,
@@ -38,17 +41,10 @@ export {
 export {
   getDurableBackend,
   setDurableBackend,
-  createInMemoryBackend,
-  createDefaultFileBackend,
-  createWorkflowFileBackend,
-  initializeDbosDurableBackendFromEnv,
+  createInMemoryTestBackend,
+  initializeDurableBackend,
 } from "./factory.js";
-export {
-  scanResumableWorkflows,
-  listResumableFromBackend,
-  persistDurableCacheEntry,
-  formatResumableWorkflowList,
-} from "./resume-catalog.js";
+export { listResumableFromBackend, formatResumableWorkflowList } from "./resume-catalog.js";
 export {
   completedWorkflowSnapshot,
   listCompletedFromBackend,

package/dist/builtin/workflows/src/durable/local-command.ts

@@ -0,0 +1,63 @@
+/** Minimal subprocess and TCP helpers for local DBOS database provisioning. */
+
+import { spawn } from "node:child_process";
+import { connect } from "node:net";
+
+export interface LocalCommandResult {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+const OUTPUT_LIMIT_BYTES = 16_384;
+
+export function runLocalCommand(
+  command: string,
+  args: readonly string[],
+  env?: Readonly<Record<string, string>>,
+): Promise<LocalCommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, [...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+      ...(env !== undefined ? { env: { ...process.env, ...env } } : {}),
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk: string) => { stdout = boundedAppend(stdout, chunk); });
+    child.stderr.on("data", (chunk: string) => { stderr = boundedAppend(stderr, chunk); });
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+  });
+}
+
+export function commandFailureDetail(result: LocalCommandResult): string {
+  return result.stderr.trim() || result.stdout.trim() || `exit ${result.exitCode}`;
+}
+
+export function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** True when a TCP listener accepts a connection on host:port within the timeout. */
+export function tcpReachable(host: string, port: number, timeoutMs = 1_000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = connect({ host, port });
+    const finish = (reachable: boolean) => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(reachable);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+
+function boundedAppend(current: string, chunk: string): string {
+  const next = current + chunk;
+  return next.length <= OUTPUT_LIMIT_BYTES ? next : next.slice(-OUTPUT_LIMIT_BYTES);
+}