@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/src/durable/dbos-embedded-postgres.ts

@@ -0,0 +1,207 @@
+/**
+ * Embedded Postgres for DBOS workflow durability.
+ *
+ * When no `DBOS_SYSTEM_DATABASE_URL` is configured, Atomic runs DBOS against
+ * its own Postgres instance built from npm-distributed binaries
+ * (`@embedded-postgres/<platform>-<arch>`, installed as an optional dependency
+ * of `embedded-postgres`). No Docker daemon or system Postgres is required.
+ *
+ * The cluster lives under `~/.atomic/postgres/v<major>` on a dedicated port and
+ * is started with `pg_ctl`, which daemonizes the server into its own session:
+ * it survives Atomic exiting and is shared by every concurrent Atomic session.
+ * Atomic never stops it.
+ */
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { commandFailureDetail, delay, runLocalCommand, tcpReachable } from "./local-command.js";
+
+const EMBEDDED_HOST = "127.0.0.1";
+const EMBEDDED_PORT = 5439;
+const EMBEDDED_USER = "postgres";
+const EMBEDDED_PASSWORD = "atomic";
+const EMBEDDED_PG_MAJOR = 18;
+const READY_ATTEMPTS = 120;
+const READY_DELAY_MS = 250;
+const SETUP_LOCK_STALE_MS = 120_000;
+
+export const EMBEDDED_DBOS_SYSTEM_DATABASE_URL =
+  `postgresql://${EMBEDDED_USER}:${EMBEDDED_PASSWORD}@${EMBEDDED_HOST}:${EMBEDDED_PORT}/atomic_workflows_dbos_sys?connect_timeout=10&sslmode=disable`;
+
+interface EmbeddedPostgresBinaries {
+  readonly pg_ctl: string;
+  readonly initdb: string;
+}
+
+let ensured: Promise<void> | undefined;
+
+/** Start or attach to the shared embedded DBOS Postgres exactly once per process. */
+export function ensureEmbeddedDbosPostgres(): Promise<void> {
+  ensured ??= ensure().catch((error: unknown) => {
+    ensured = undefined;
+    throw error;
+  });
+  return ensured;
+}
+
+async function ensure(): Promise<void> {
+  if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT)) return;
+  const binaries = await loadEmbeddedPostgresBinaries();
+  hydrateBinaryLibraryLinks(binaries.pg_ctl);
+  const root = join(homedir(), ".atomic", "postgres");
+  const dataDir = join(root, `v${EMBEDDED_PG_MAJOR}`);
+  const logFile = join(root, `v${EMBEDDED_PG_MAJOR}.log`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  await withSetupLock(join(root, `v${EMBEDDED_PG_MAJOR}.setup-lock`), async () => {
+    if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT)) return;
+    if (!existsSync(join(dataDir, "PG_VERSION"))) await initializeCluster(binaries.initdb, dataDir);
+    await startCluster(binaries.pg_ctl, dataDir, logFile);
+  });
+
+  for (let attempt = 0; attempt < READY_ATTEMPTS; attempt += 1) {
+    if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT)) return;
+    await delay(READY_DELAY_MS);
+  }
+  throw new Error(`Embedded Postgres started but never accepted connections on ${EMBEDDED_HOST}:${EMBEDDED_PORT}; see ${logFile}.`);
+}
+
+async function initializeCluster(initdb: string, dataDir: string): Promise<void> {
+  const passwordFile = join(tmpdir(), `atomic-pg-pw-${process.pid}-${crypto.randomUUID().slice(0, 8)}`);
+  writeFileSync(passwordFile, `${EMBEDDED_PASSWORD}\n`, { mode: 0o600 });
+  try {
+    const result = await runLocalCommand(initdb, [
+      "-D", dataDir,
+      "-U", EMBEDDED_USER,
+      "-A", "password",
+      `--pwfile=${passwordFile}`,
+      "-E", "UTF8",
+      "--no-locale",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(`Could not initialize the embedded Postgres cluster: ${commandFailureDetail(result)}`);
+    }
+  } finally {
+    rmSync(passwordFile, { force: true });
+  }
+}
+
+async function startCluster(pgCtl: string, dataDir: string, logFile: string): Promise<void> {
+  const result = await runLocalCommand(pgCtl, [
+    "-D", dataDir,
+    "-l", logFile,
+    "-o", `-p ${EMBEDDED_PORT} -c listen_addresses=${EMBEDDED_HOST}`,
+    "-w", "-t", "60",
+    "start",
+  ]);
+  if (result.exitCode === 0) return;
+  // A concurrent session may have won the start race; readiness polling in the
+  // caller decides. Only fail here when nothing is coming up on the port.
+  if (await tcpReachable(EMBEDDED_HOST, EMBEDDED_PORT, 3_000)) return;
+  throw new Error(
+    `Could not start the embedded Postgres cluster: ${commandFailureDetail(result)}${logTail(logFile)}`,
+  );
+}
+
+/**
+ * The npm platform packages ship `native/lib` symlinks (e.g.
+ * `libicudata.dylib → libicudata.77.1.dylib`) through a `pg-symlinks.json`
+ * manifest plus a postinstall script, because npm tarballs cannot contain
+ * symlinks. Bun and `--ignore-scripts` installs skip postinstall, so hydrate
+ * the links at runtime; fall back to copying when symlinks are unavailable.
+ */
+function hydrateBinaryLibraryLinks(pgCtlPath: string): void {
+  const packageRoot = dirname(dirname(dirname(pgCtlPath)));
+  let manifest: readonly { readonly source: string; readonly target: string }[];
+  try {
+    manifest = JSON.parse(readFileSync(join(packageRoot, "native", "pg-symlinks.json"), "utf8")) as typeof manifest;
+  } catch {
+    return;
+  }
+  for (const { source, target } of manifest) {
+    const absoluteSource = join(packageRoot, source);
+    const absoluteTarget = join(packageRoot, target);
+    if (existsSync(absoluteTarget) || !existsSync(absoluteSource)) continue;
+    try {
+      symlinkSync(relative(dirname(absoluteTarget), absoluteSource), absoluteTarget);
+    } catch {
+      try {
+        copyFileSync(absoluteSource, absoluteTarget);
+      } catch {
+        // Missing optional libraries surface as an initdb/pg_ctl failure with detail.
+      }
+    }
+  }
+}
+
+async function loadEmbeddedPostgresBinaries(): Promise<EmbeddedPostgresBinaries> {
+  const platform = process.platform === "win32" ? "windows" : process.platform;
+  const packageName = `@embedded-postgres/${platform}-${process.arch}`;
+  let binaries: Partial<EmbeddedPostgresBinaries>;
+  try {
+    binaries = await import(packageName) as Partial<EmbeddedPostgresBinaries>;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Embedded Postgres binaries are unavailable for ${process.platform}/${process.arch} (${packageName}): ${detail}`);
+  }
+  if (typeof binaries.pg_ctl !== "string" || typeof binaries.initdb !== "string") {
+    throw new Error(`Embedded Postgres package ${packageName} did not export pg_ctl/initdb paths.`);
+  }
+  for (const binary of [binaries.pg_ctl, binaries.initdb, join(dirname(binaries.pg_ctl), process.platform === "win32" ? "postgres.exe" : "postgres")]) {
+    ensureExecutable(binary);
+  }
+  return { pg_ctl: binaries.pg_ctl, initdb: binaries.initdb };
+}
+
+/** npm can strip executable bits; restore them only when actually missing. */
+function ensureExecutable(filePath: string): void {
+  try {
+    const mode = statSync(filePath).mode;
+    if ((mode & 0o111) !== 0o111) chmodSync(filePath, mode | 0o555);
+  } catch {
+    // A genuinely missing binary surfaces as a spawn failure with detail.
+  }
+}
+
+/** Serialize initdb/start across concurrent Atomic processes on this machine. */
+async function withSetupLock(lockDir: string, fn: () => Promise<void>): Promise<void> {
+  for (let attempt = 0; attempt < READY_ATTEMPTS; attempt += 1) {
+    try {
+      mkdirSync(lockDir);
+      break;
+    } catch {
+      if (lockIsStale(lockDir)) {
+        rmSync(lockDir, { recursive: true, force: true });
+        continue;
+      }
+      await delay(READY_DELAY_MS);
+      if (attempt === READY_ATTEMPTS - 1) throw new Error(`Timed out waiting for another Atomic process to finish Postgres setup (${lockDir}).`);
+    }
+  }
+  try {
+    await fn();
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true });
+  }
+}
+function lockIsStale(lockDir: string): boolean {
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs > SETUP_LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function logTail(logFile: string): string {
+  try {
+    const lines = readFileSync(logFile, "utf8").trimEnd().split("\n");
+    return `\nPostgres log tail:\n${lines.slice(-5).join("\n")}`;
+  } catch {
+    return "";
+  }
+}
+
+export function resetEmbeddedDbosPostgresForTests(): void {
+  ensured = undefined;
+}

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

@@ -8,22 +8,21 @@
  * the synchronous replay reads (`getToolOutput`, `getUiResponse`,
  * `getStageOutput`) cannot reconstruct their lookup keys.
  *
- * The envelope is forward-compatible: old/simple payloads (plain values without
- * the envelope marker) are treated as generic stage outputs during hydration.
- *
- * cross-ref: issue #1498 — DBOS read-side hydration.
+ * Payloads without the current envelope marker and version are rejected.
  */
 
 import type { WorkflowSerializableObject, WorkflowSerializableValue } from "../shared/types.js";
-import type {
-  DurableCheckpoint,
-  DurableCheckpointKind,
-  DurableStageCheckpoint,
-  DurableToolCheckpoint,
-  DurableUiCheckpoint,
-  UiPromptKind,
+import {
+  DURABLE_STAGE_TOPOLOGY_VERSION,
+  type DurableCheckpoint,
+  type DurableCheckpointKind,
+  type DurableStageCheckpoint,
+  type DurableStageTopology,
+  type DurableToolCheckpoint,
+  type DurableUiCheckpoint,
+  type UiPromptKind,
 } from "./types.js";
-import { classifyDurableFormatVersion, DURABLE_FORMAT_VERSION } from "./format-version.js";
+import { isCurrentDurableFormat, DURABLE_FORMAT_VERSION } from "./format-version.js";
 
 /** Envelope schema version. */
 export const DBOS_ENVELOPE_VERSION = DURABLE_FORMAT_VERSION;
@@ -60,12 +59,28 @@ export interface DbosCheckpointEnvelope extends WorkflowSerializableObject {
   readonly fastMode?: boolean;
   readonly attemptedModels?: WorkflowSerializableValue;
   readonly modelAttempts?: WorkflowSerializableValue;
+  readonly topology?: WorkflowSerializableValue;
+}
+
+/**
+ * Stage-kind checkpoints from older session-timing writers may omit
+ * topology. The current format requires it, so default at every write
+ * boundary — persisted records must match the normalized in-memory mirror or
+ * a fresh process would reject them as foreign.
+ */
+export function withCurrentStageTopology(cp: DurableCheckpoint): DurableCheckpoint {
+  if (cp.kind !== "stage" || cp.topology !== undefined) return cp;
+  return {
+    ...cp,
+    topology: { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: cp.checkpointId, parentIds: [] },
+  };
 }
 
 /**
  * Encode a durable checkpoint into a DBOS step-output envelope.
  */
-export function encodeCheckpoint(cp: DurableCheckpoint): DbosCheckpointEnvelope {
+export function encodeCheckpoint(checkpoint: DurableCheckpoint): DbosCheckpointEnvelope {
+  const cp = withCurrentStageTopology(checkpoint);
   const output = checkpointOutputValue(cp);
   const base: DbosCheckpointEnvelope = {
     __dbos_checkpoint__: ENVELOPE_MARKER,
@@ -89,6 +104,7 @@ export function encodeCheckpoint(cp: DurableCheckpoint): DbosCheckpointEnvelope
     ...base,
     name: s.name,
     replayKey: s.replayKey,
+    ...(s.topology !== undefined ? { topology: { version: s.topology.version, stageId: s.topology.stageId, parentIds: [...s.topology.parentIds] } } : {}),
     ...(s.sessionId !== undefined ? { sessionId: s.sessionId } : {}),
     ...(s.sessionFile !== undefined ? { sessionFile: s.sessionFile } : {}),
     ...(s.startedAt !== undefined ? { startedAt: s.startedAt } : {}),
@@ -116,7 +132,6 @@ function hasCheckpointEnvelopeMarker(value: WorkflowSerializableValue | undefine
 }
 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. */
@@ -125,9 +140,7 @@ export function classifyCheckpointPayload(
   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 };
+  if (!hasCheckpointEnvelopeMarker(value) || !isCurrentDurableFormat(value.v)) return { kind: "unknown" };
   const hasOutput = value["hasOutput"];
   const containsOutput = value["output"] !== undefined;
   if (value["checkpointId"] !== stepName || typeof hasOutput !== "boolean" || hasOutput !== containsOutput) {
@@ -137,15 +150,7 @@ export function classifyCheckpointPayload(
   return checkpoint === undefined ? { kind: "unknown" } : { kind: "current", checkpoint };
 }
 
-/**
- * Decode a DBOS step output into a durable checkpoint.
- *
- * - Envelope payloads reconstruct the full checkpoint with original metadata.
- * - Non-envelope payloads (legacy/simple) produce a generic stage checkpoint
- *   so the output is still discoverable during replay.
- *
- * Returns `undefined` if the payload cannot be interpreted.
- */
+/** Decode one current DBOS checkpoint envelope. */
 export function decodeToCheckpoint(
   workflowId: string,
   stepName: string,
@@ -183,7 +188,8 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
       response: env.output,
     } as DurableUiCheckpoint;
   }
-  if (env.kind !== "stage"
+  const topology = stageTopology(env.topology);
+  if (env.kind !== "stage" || topology === undefined
     || (env.replayKey !== undefined && typeof env.replayKey !== "string")
     || (env.sessionId !== undefined && typeof env.sessionId !== "string")
     || (env.sessionFile !== undefined && typeof env.sessionFile !== "string")
@@ -201,6 +207,7 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
     name: env.name ?? "stage",
     replayKey: env.replayKey ?? env.checkpointId,
     ...(env.hasOutput !== false && env.output !== undefined ? { output: env.output } : {}),
+    topology,
     ...(env.sessionId !== undefined ? { sessionId: env.sessionId } : {}),
     ...(env.sessionFile !== undefined ? { sessionFile: env.sessionFile } : {}),
     ...(typeof env.startedAt === "number" ? { startedAt: env.startedAt } : {}),
@@ -215,6 +222,14 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
 }
 
 
+function stageTopology(value: WorkflowSerializableValue | undefined): DurableStageTopology | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const record = value as Record<string, WorkflowSerializableValue>;
+  if (record["version"] !== DURABLE_STAGE_TOPOLOGY_VERSION
+    || typeof record["stageId"] !== "string" || !isStringArray(record["parentIds"])) return undefined;
+  return { version: DURABLE_STAGE_TOPOLOGY_VERSION, stageId: record["stageId"], parentIds: record["parentIds"] };
+}
+
 function isModelAttempts(value: WorkflowSerializableValue | undefined): boolean {
   return Array.isArray(value) && value.every((attempt) => {
     if (typeof attempt !== "object" || attempt === null || Array.isArray(attempt)) return false;
@@ -251,21 +266,6 @@ function isOptionalFiniteNumber(value: WorkflowSerializableValue | undefined): b
 function isStringArray(value: WorkflowSerializableValue | undefined): value is readonly string[] {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
-function decodeLegacy(
-  workflowId: string,
-  stepName: string,
-  output: WorkflowSerializableValue,
-): DurableStageCheckpoint {
-  return {
-    kind: "stage",
-    workflowId,
-    checkpointId: `stage:${stepName}`,
-    name: stepName,
-    replayKey: stepName,
-    output,
-    completedAt: Date.now(),
-  };
-}
 
 function checkpointOutputValue(cp: DurableCheckpoint): WorkflowSerializableValue | undefined {
   if (cp.kind === "tool") return (cp as DurableToolCheckpoint).output;

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

@@ -0,0 +1,155 @@
+import {
+  configureDbosDurableBackend,
+  type ConfiguredDbosDurability,
+  type DbosDurableBackend,
+} from "./dbos-backend.js";
+import {
+  provisionResolvedLocalDbos,
+  resolveDbosSystemDatabaseUrl,
+  shouldProvisionLocalDbos,
+} from "./dbos-local-postgres.js";
+
+export type DbosLifecycleState =
+  | "uninitialized"
+  | "configured"
+  | "launching"
+  | "ready"
+  | "failed"
+  | "shutting_down";
+
+export class DbosDurabilityError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "DbosDurabilityError";
+  }
+}
+
+export class DbosNotReadyError extends DbosDurabilityError {
+  constructor() {
+    super("DBOS workflow durability is not ready. Await initializeDurableBackend() before accessing workflows.");
+    this.name = "DbosNotReadyError";
+  }
+}
+type DbosConfigurator = () => Promise<ConfiguredDbosDurability>;
+type LocalDbosProvisioner = () => Promise<void>;
+
+/**
+ * Default path: resolve the local database first (explicit env URL, embedded
+ * Postgres, or the Docker fallback), then configure DBOS against it.
+ */
+const defaultConfigurator: DbosConfigurator = async () => {
+  const systemDatabaseUrl = await resolveDbosSystemDatabaseUrl();
+  return await configureDbosDurableBackend(
+    systemDatabaseUrl === undefined ? undefined : { systemDatabaseUrl },
+  );
+};
+
+let configureDurability: DbosConfigurator = defaultConfigurator;
+let provisionLocalDbos: LocalDbosProvisioner = provisionResolvedLocalDbos;
+
+let state: DbosLifecycleState = "uninitialized";
+let configured: Promise<ConfiguredDbosDurability> | undefined;
+let active: ConfiguredDbosDurability | undefined;
+let launchPromise: Promise<void> | undefined;
+let shutdownPromise: Promise<void> | undefined;
+let failure: DbosDurabilityError | undefined;
+
+function durabilityFailure(action: string, error: unknown): DbosDurabilityError {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new DbosDurabilityError(
+    `DBOS workflow durability ${action} failed: ${detail}. Set DBOS_SYSTEM_DATABASE_URL to an existing Postgres when local provisioning is unavailable.`,
+    error instanceof Error ? { cause: error } : undefined,
+  );
+}
+
+export async function configureDbosOnce(): Promise<ConfiguredDbosDurability> {
+  if (failure !== undefined) throw failure;
+  configured ??= configureDurability().then((value) => {
+    active = value;
+    state = "configured";
+    return value;
+  }).catch((error: unknown) => {
+    failure = durabilityFailure("configuration", error);
+    state = "failed";
+    throw failure;
+  });
+  return await configured;
+}
+
+export async function launchDbosOnce(): Promise<void> {
+  if (failure !== undefined) throw failure;
+  const durability = await configureDbosOnce();
+  launchPromise ??= (async () => {
+    state = "launching";
+    try {
+      await durability.launch();
+      state = "ready";
+    } catch (error) {
+      if (shouldProvisionLocalDbos(error)) {
+        try {
+          // DBOS creates an executor before testing connectivity. Tear down the
+          // failed executor so retry does not leak a pool or hang shutdown.
+          await durability.shutdown();
+          await provisionLocalDbos();
+          await durability.launch();
+          state = "ready";
+          return;
+        } catch (provisionError) {
+          failure = durabilityFailure("local Postgres startup", provisionError);
+        }
+      } else {
+        failure = durabilityFailure("launch", error);
+      }
+      state = "failed";
+      throw failure;
+    }
+  })();
+  await launchPromise;
+}
+
+export async function getReadyDbosBackend(): Promise<DbosDurableBackend> {
+  await launchDbosOnce();
+  if (state !== "ready" || active === undefined) throw failure ?? new DbosNotReadyError();
+  return active.backend;
+}
+
+export function getReadyDbosBackendSync(): DbosDurableBackend | undefined {
+  return state === "ready" ? active?.backend : undefined;
+}
+
+export async function shutdownDbos(): Promise<void> {
+  if (shutdownPromise !== undefined) return await shutdownPromise;
+  if (configured === undefined) return;
+  shutdownPromise = (async () => {
+    const durability = await configured;
+    if (launchPromise !== undefined) await launchPromise;
+    if (state !== "ready") return;
+    state = "shutting_down";
+    await durability.backend.flush();
+    await durability.shutdown();
+  })().catch((error: unknown) => {
+    failure = durabilityFailure("shutdown", error);
+    state = "failed";
+    throw failure;
+  });
+  await shutdownPromise;
+}
+
+export function dbosLifecycleState(): DbosLifecycleState {
+  return state;
+}
+
+/** Reset the process singleton with an explicit configurator for unit tests. */
+export function resetDbosLifecycleForTests(
+  configurator: DbosConfigurator = defaultConfigurator,
+  provisioner: LocalDbosProvisioner = provisionResolvedLocalDbos,
+): void {
+  state = "uninitialized";
+  configured = undefined;
+  active = undefined;
+  launchPromise = undefined;
+  shutdownPromise = undefined;
+  failure = undefined;
+  configureDurability = configurator;
+  provisionLocalDbos = provisioner;
+}

package/dist/builtin/workflows/src/durable/dbos-local-postgres.ts

@@ -0,0 +1,126 @@
+/**
+ * Local DBOS database resolution.
+ *
+ * Without `DBOS_SYSTEM_DATABASE_URL`, Atomic never guesses at a user-managed
+ * Postgres (a reachable 5432 with foreign credentials is indistinguishable
+ * from a misconfiguration). The order is deterministic:
+ *
+ *   1. `DBOS_SYSTEM_DATABASE_URL` — the user's explicit database.
+ *   2. Atomic's embedded Postgres (npm-distributed binaries, no Docker).
+ *   3. DBOS's reusable `dbos-db` Docker container, only when the embedded
+ *      binaries are unavailable for this platform and Docker exists.
+ */
+
+import {
+  EMBEDDED_DBOS_SYSTEM_DATABASE_URL,
+  ensureEmbeddedDbosPostgres,
+} from "./dbos-embedded-postgres.js";
+import { commandFailureDetail, delay, runLocalCommand, tcpReachable } from "./local-command.js";
+
+const DOCKER_CONTAINER = "dbos-db";
+const DOCKER_IMAGE = "pgvector/pgvector:pg16";
+const DOCKER_READY_ATTEMPTS = 60;
+const DOCKER_READY_DELAY_MS = 500;
+
+type LocalDbosProvider = () => Promise<void>;
+
+let resolution: Promise<string | undefined> | undefined;
+let resolvedProvider: LocalDbosProvider | undefined;
+let embeddedProvider: LocalDbosProvider = ensureEmbeddedDbosPostgres;
+let dockerProvider: LocalDbosProvider = ensureDockerDbosPostgres;
+
+/**
+ * Resolve the system database URL for this process and make its database
+ * reachable. `undefined` defers to the environment/DBOS defaults (explicit
+ * user URL or the Docker container that matches them).
+ */
+export function resolveDbosSystemDatabaseUrl(): Promise<string | undefined> {
+  resolution ??= resolve().catch((error: unknown) => {
+    resolution = undefined;
+    throw error;
+  });
+  return resolution;
+}
+
+/** Re-ensure the previously resolved local database (launch-retry safety net). */
+export async function provisionResolvedLocalDbos(): Promise<void> {
+  await (resolvedProvider ?? embeddedProvider)();
+}
+
+export function shouldProvisionLocalDbos(error: unknown): boolean {
+  if (process.env.DBOS_SYSTEM_DATABASE_URL?.trim()) return false;
+  const message = error instanceof Error ? `${error.message}\n${error.cause ?? ""}` : String(error);
+  return /ECONNREFUSED|server not reachable|connect failed|connection refused|unable to connect to system database/i.test(message);
+}
+
+async function resolve(): Promise<string | undefined> {
+  const explicit = process.env.DBOS_SYSTEM_DATABASE_URL?.trim();
+  if (explicit) return undefined;
+
+  try {
+    await embeddedProvider();
+    resolvedProvider = embeddedProvider;
+    return EMBEDDED_DBOS_SYSTEM_DATABASE_URL;
+  } catch (embeddedError) {
+    try {
+      await dockerProvider();
+      resolvedProvider = dockerProvider;
+      // The container matches DBOS's documented default URL; defer to it.
+      return undefined;
+    } catch (dockerError) {
+      const embeddedDetail = embeddedError instanceof Error ? embeddedError.message : String(embeddedError);
+      const dockerDetail = dockerError instanceof Error ? dockerError.message : String(dockerError);
+      throw new Error(
+        `No usable Postgres for workflow durability. Embedded Postgres: ${embeddedDetail} Docker fallback: ${dockerDetail} `
+        + "Set DBOS_SYSTEM_DATABASE_URL to an existing Postgres to proceed.",
+      );
+    }
+  }
+}
+
+/** Start DBOS's canonical reusable local Postgres container. */
+async function ensureDockerDbosPostgres(): Promise<void> {
+  const docker = await runLocalCommand("docker", ["version", "--format", "{{.Server.Version}}"]).catch(() => undefined);
+  if (docker === undefined || docker.exitCode !== 0) {
+    throw new Error("Docker is unavailable.");
+  }
+
+  const inspection = await runLocalCommand("docker", ["inspect", "--format", "{{.State.Running}}", DOCKER_CONTAINER]);
+  if (inspection.exitCode === 0) {
+    if (inspection.stdout.trim() !== "true") {
+      await requireDockerSuccess("start existing DBOS Postgres", ["start", DOCKER_CONTAINER]);
+    }
+  } else {
+    await requireDockerSuccess("create DBOS Postgres", [
+      "run", "-d",
+      "--name", DOCKER_CONTAINER,
+      "-e", "POSTGRES_PASSWORD=dbos",
+      "-e", "PGDATA=/var/lib/postgresql/data",
+      "-p", "127.0.0.1:5432:5432",
+      "-v", "dbos-db-data:/var/lib/postgresql/data",
+      DOCKER_IMAGE,
+    ]);
+  }
+
+  for (let attempt = 0; attempt < DOCKER_READY_ATTEMPTS; attempt += 1) {
+    if (await tcpReachable("127.0.0.1", 5432)) return;
+    await delay(DOCKER_READY_DELAY_MS);
+  }
+  throw new Error("The DBOS Postgres container started but did not become ready within 30 seconds.");
+}
+
+async function requireDockerSuccess(action: string, args: string[]): Promise<void> {
+  const result = await runLocalCommand("docker", args);
+  if (result.exitCode === 0) return;
+  throw new Error(`Could not ${action}: ${commandFailureDetail(result)}`);
+}
+
+export function resetLocalDbosProvisioningForTests(
+  embedded: LocalDbosProvider = ensureEmbeddedDbosPostgres,
+  docker: LocalDbosProvider = ensureDockerDbosPostgres,
+): void {
+  resolution = undefined;
+  resolvedProvider = undefined;
+  embeddedProvider = embedded;
+  dockerProvider = docker;
+}