@bastani/atomic 0.9.26-alpha.4 → 0.9.26-alpha.5

package/dist/builtin/workflows/src/extension/index.bundle.mjs

@@ -76,6 +76,92 @@ function raceAbort(operation, signal) {
   });
 }
 
+// dist/builtin/workflows/src/durable/dbos-database-diagnostics.ts
+function redactedDatabaseEndpoint(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return "unparseable PostgreSQL endpoint";
+  }
+}
+function redactedDatabaseMessage(message, url) {
+  let safe = message.replace(/postgres(?:ql)?:\/\/[^\s"'<>]+/gi, (value2) => redactedDatabaseEndpoint(value2));
+  let configuredSecrets = [];
+  if (url !== undefined) {
+    try {
+      const parsed = new URL(url);
+      configuredSecrets = [parsed.username, parsed.password, ...parsed.searchParams.values()].flatMap((secret) => {
+        try {
+          return [secret, decodeURIComponent(secret)];
+        } catch {
+          return [secret];
+        }
+      }).filter((secret) => secret.length > 0);
+    } catch {
+      return "PostgreSQL diagnostic could not be safely redacted; check the configured endpoint.";
+    }
+  }
+  safe = safe.replace(/\b(password|passwd|token|secret|sslpassword|user(?:name)?)\s*(?:([=:])\s*|((?:is|was)\s+)|\s+)(?:"([^"]*)"|'([^']*)'|([^\s,;]+))/gi, (match, key, separator, filler, doubleQuoted, singleQuoted, bare) => {
+    const value2 = doubleQuoted ?? singleQuoted ?? bare ?? "";
+    const isUserContext = /^user(?:name)?$/i.test(key);
+    if (separator === undefined && !isUserContext && !configuredSecrets.includes(value2))
+      return match;
+    const rendered = doubleQuoted !== undefined ? '"[redacted]"' : singleQuoted !== undefined ? "'[redacted]'" : "[redacted]";
+    return `${key}${separator ?? " "}${filler ?? ""}${rendered}`;
+  });
+  for (const secret of new Set(configuredSecrets)) {
+    if (secret.length < 4)
+      continue;
+    const escaped = secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const expression = new RegExp(`(?<![\\p{L}\\p{N}_\\[])${escaped}(?![\\p{L}\\p{N}_\\]])`, "gu");
+    safe = safe.replace(expression, "[redacted]");
+  }
+  return safe;
+}
+function databaseDependencyMessage(message, diagnostics) {
+  const safe = redactedDatabaseMessage(message, diagnostics?.url);
+  if (diagnostics === undefined)
+    return safe;
+  const failure = diagnostics.failure === undefined ? "" : ` Last probe/recovery failure: ${redactedDatabaseMessage(diagnostics.failure, diagnostics.url)}`;
+  return `${safe} Provider: ${diagnostics.provider}; endpoint: ${redactedDatabaseEndpoint(diagnostics.url)}.${failure}`;
+}
+
+// dist/builtin/workflows/src/durable/dbos-process-owner.ts
+function emptyOwner2() {
+  return {
+    version: 1,
+    state: "uninitialized",
+    configured: undefined,
+    active: undefined,
+    launchPromise: undefined,
+    shutdownPromise: undefined,
+    failure: undefined,
+    wrappers: undefined,
+    leases: new Set
+  };
+}
+function ownerBag2() {
+  return globalThis;
+}
+function getDbosProcessOwner() {
+  const bag = ownerBag2();
+  const existing = bag[DBOS_PROCESS_OWNER_KEY];
+  if (existing !== undefined && existing.version === 1)
+    return existing;
+  const created = emptyOwner2();
+  bag[DBOS_PROCESS_OWNER_KEY] = created;
+  return created;
+}
+var DBOS_PROCESS_OWNER_KEY;
+var init_dbos_process_owner = __esm(() => {
+  DBOS_PROCESS_OWNER_KEY = Symbol.for("atomic-workflows/dbos-process-owner@1");
+});
+
 // dist/builtin/workflows/src/durable/dbos-admission.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 function isDbosDependencyError(error) {
@@ -94,6 +180,8 @@ async function boundedAdmission(operation, signal, timeoutMs = DBOS_ADMISSION_TI
     return await raceAbort(operation(controller.signal), controller.signal);
   } catch (error) {
     controller.abort(error);
+    if (isDbosDependencyError(error) && error.admissionDetail !== undefined)
+      throw new DbosDependencyError(error.admissionDetail, null);
     throw error;
   } finally {
     clearTimeout(timer);
@@ -102,10 +190,13 @@ async function boundedAdmission(operation, signal, timeoutMs = DBOS_ADMISSION_TI
 }
 var DBOS_ADMISSION_TIMEOUT_MS = 1e4, DbosDependencyError, key2, bag, dbosAdmissionContext;
 var init_dbos_admission = __esm(() => {
+  init_dbos_process_owner();
   DbosDependencyError = class DbosDependencyError extends Error {
     code = "ATOMIC_DBOS_DEPENDENCY";
-    constructor(message = "Workflow database unavailable during admission. Restore PostgreSQL before retrying.") {
-      super(message);
+    admissionDetail;
+    constructor(message = "Workflow database unavailable during admission. Restore PostgreSQL before retrying.", diagnostics = getDbosProcessOwner().databaseDiagnostics?.(), admissionDetail) {
+      super(databaseDependencyMessage(message, diagnostics ?? undefined));
+      this.admissionDetail = admissionDetail === undefined ? undefined : redactedDatabaseMessage(admissionDetail);
       this.name = "DbosDependencyError";
     }
   };
@@ -30276,11 +30367,11 @@ function fenceDbosAdmissionPool(pool) {
   const connect = pool.connect.bind(pool);
   async function acquire(signal) {
     if (signal.aborted)
-      throw new DbosDependencyError;
+      throw sdkDependencyError();
     const pending = connect().then((client) => {
       if (signal.aborted) {
         client.release(true);
-        throw new DbosDependencyError;
+        throw sdkDependencyError();
       }
       return fencedClient(client, signal);
     });
@@ -30324,7 +30415,7 @@ function fencedClient(client, signal) {
       const callback = typeof last === "function" ? values.pop() : undefined;
       const pending = (async () => {
         if (signal.aborted || released)
-          throw new DbosDependencyError;
+          throw sdkDependencyError();
         try {
           return await raceAbort(new Promise((resolve, reject) => {
             Reflect.apply(target, client, [
@@ -30356,9 +30447,15 @@ function fencedClient(client, signal) {
     }
   });
 }
+function sdkDependencyError(message) {
+  const reported = message === undefined ? new DbosDependencyError : new DbosDependencyError(message, null);
+  return new DbosDependencyError(undefined, null, reported.message);
+}
 function databaseError(error, signal) {
   if (signal.aborted)
-    return new DbosDependencyError;
+    return sdkDependencyError();
+  if (isDbosDependencyError(error))
+    return sdkDependencyError(error.admissionDetail ?? error.message);
   const pending = [error];
   const seen = new Set;
   while (pending.length > 0) {
@@ -30375,7 +30472,7 @@ function databaseError(error, signal) {
     const code = "code" in value2 && typeof value2.code === "string" ? value2.code : undefined;
     const message = value2 instanceof Error ? value2.message : "";
     if (code !== undefined && (/^(?:08|53|57)[0-9A-Z]{3}$|^40003$/.test(code) || connectionErrnos.has(code)) || code === undefined && connectionMessages.has(message)) {
-      return new DbosDependencyError;
+      return sdkDependencyError();
     }
   }
   return error;
@@ -30398,7 +30495,9 @@ var init_dbos_admission_pool = __esm(() => {
     "Connection terminated unexpectedly",
     "Connection terminated due to connection timeout",
     "Client has encountered a connection error and is not queryable",
-    "timeout exceeded when trying to connect"
+    "timeout exceeded when trying to connect",
+    "Client was closed and is not queryable",
+    "Postgres connection pool changed while acquiring a connection"
   ]);
 });
 
@@ -30686,6 +30785,11 @@ function defaultDatabaseUrl(name) {
 function configureAdmissionDatabase(sdk, config, launchLock = withDbosLaunchLock) {
   const systemDatabaseUrl = config.systemDatabaseUrl ?? defaultDatabaseUrl(config.name);
   const health = resolvedPostgresHealth(systemDatabaseUrl);
+  getDbosProcessOwner().databaseDiagnostics = () => ({
+    provider: health === undefined ? config.systemDatabaseUrl === undefined ? "docker" : "configured" : "managed",
+    url: health?.endpoint ?? systemDatabaseUrl,
+    failure: health?.lastFailure?.message
+  });
   const createPool = () => {
     let unsubscribe;
     const managed = createRecoverablePostgresPool(systemDatabaseUrl, {
@@ -30723,6 +30827,7 @@ var import_datasource2;
 var init_dbos_admission_config = __esm(() => {
   init_dbos_admission_pool();
   init_dbos_launch_lock();
+  init_dbos_process_owner();
   init_dbos_recoverable_pool();
   import_datasource2 = __toESM(require_datasource(), 1);
 });
@@ -85896,33 +86001,8 @@ function classifyDbosDeletionTombstone(records, workflowId) {
   return isCurrentDurableFormat(raw.version) ? "current" : "unknown";
 }
 
-// dist/builtin/workflows/src/durable/dbos-process-owner.ts
-var DBOS_PROCESS_OWNER_KEY = Symbol.for("atomic-workflows/dbos-process-owner@1");
-function emptyOwner2() {
-  return {
-    version: 1,
-    state: "uninitialized",
-    configured: undefined,
-    active: undefined,
-    launchPromise: undefined,
-    shutdownPromise: undefined,
-    failure: undefined,
-    wrappers: undefined,
-    leases: new Set
-  };
-}
-function ownerBag2() {
-  return globalThis;
-}
-function getDbosProcessOwner() {
-  const bag = ownerBag2();
-  const existing = bag[DBOS_PROCESS_OWNER_KEY];
-  if (existing !== undefined && existing.version === 1)
-    return existing;
-  const created = emptyOwner2();
-  bag[DBOS_PROCESS_OWNER_KEY] = created;
-  return created;
-}
+// dist/builtin/workflows/src/durable/dbos-backend.ts
+init_dbos_process_owner();
 
 // dist/builtin/workflows/src/durable/dbos-sdk-handle.ts
 var ATOMIC_EXECUTOR_ID = `atomic-${process.pid.toString(36)}-${crypto.randomUUID().slice(0, 8)}`;
@@ -86043,6 +86123,7 @@ function statusToInfo(status, fallbackId) {
 }
 
 // dist/builtin/workflows/src/durable/dbos-system-database-url.ts
+init_dbos_process_owner();
 function nonEmptyTrimmed(value2) {
   const trimmed = value2?.trim();
   return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
@@ -86057,9 +86138,7 @@ class DbosSystemDatabaseConflictError extends Error {
 function redactDatabaseUrl(url) {
   try {
     const parsed = new URL(url);
-    if (parsed.password !== "")
-      parsed.password = "***";
-    return parsed.toString();
+    return parsed.host;
   } catch {
     return "the requested database";
   }
@@ -87776,6 +87855,7 @@ class PostgresHealth {
   attempts = 0;
   nextRecoveryAt = 0;
   failure;
+  healthySinceFailure = false;
   revision = 0;
   listeners = new Set;
   constructor(operations) {
@@ -87784,6 +87864,18 @@ class PostgresHealth {
   get lastFailure() {
     return this.failure;
   }
+  get endpoint() {
+    return this.operations.url?.();
+  }
+  retainFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const safe = redactedDatabaseMessage(message, this.endpoint);
+    this.failure = new Error(safe);
+    this.healthySinceFailure = false;
+  }
+  dependencyFailure(message) {
+    return new DbosDependencyError(message, this.endpoint === undefined ? undefined : { provider: "managed", url: this.endpoint, failure: this.failure?.message });
+  }
   subscribe(listener) {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -87806,12 +87898,15 @@ class PostgresHealth {
         await this.operations.validate?.(client);
       }
     } catch (error) {
-      this.failure = error instanceof Error ? error : new Error(String(error));
+      this.retainFailure(error);
       if (!isQueryReadTimeout(error)) {
         this.invalidate();
-        throw error;
+        if (this.endpoint === undefined)
+          throw error;
+        const failure = this.dependencyFailure("Managed PostgreSQL connection validation refused. Preserve its data and ownership records.");
+        throw error instanceof DbosDependencyError ? failure : new Error(failure.message);
       }
-      throw new DbosDependencyError("Managed PostgreSQL did not answer a connection identity check in time.");
+      throw this.dependencyFailure("Managed PostgreSQL did not answer a connection identity check in time.");
     }
   }
   check() {
@@ -87852,7 +87947,7 @@ class PostgresHealth {
       } catch (retryError) {
         if (!isMonitoringConnectionFailure(retryError))
           throw retryError;
-        this.failure = retryError;
+        this.retainFailure(retryError);
         return;
       }
     }
@@ -87867,6 +87962,7 @@ class PostgresHealth {
     this.available = identity;
     this.attempts = 0;
     this.nextRecoveryAt = 0;
+    this.healthySinceFailure = true;
     return identity.url;
   }
   async refresh() {
@@ -87876,19 +87972,21 @@ class PostgresHealth {
         return ready;
     } catch (error) {
       if (isQueryReadTimeout(error)) {
-        this.failure = new DbosDependencyError("Managed PostgreSQL did not answer a health check in time.");
-        throw this.failure;
+        this.retainFailure(new Error("Managed PostgreSQL did not answer a health check in time."));
+        throw this.dependencyFailure("Managed PostgreSQL did not answer a health check in time.");
       }
-      this.failure = error instanceof Error ? error : new Error(String(error));
+      this.retainFailure(error);
       if (!(error instanceof Error && ("code" in error) && error.code === "53300"))
         this.invalidate();
-      throw error;
+      throw this.endpoint === undefined ? error : this.dependencyFailure("Managed PostgreSQL recovery refused after a health probe failure. Preserve its data and ownership records.");
+    }
+    if (this.attempts === 0 && (this.failure === undefined || this.healthySinceFailure)) {
+      this.retainFailure(new Error("Managed PostgreSQL failed its live health check."));
+      this.healthySinceFailure = false;
     }
-    if (this.attempts === 0)
-      this.failure = new DbosDependencyError("Managed PostgreSQL failed its live health check.");
     this.invalidate();
     if ((this.operations.now ?? Date.now)() < this.nextRecoveryAt)
-      throw new DbosDependencyError("Managed Postgres recovery is cooling down after bounded attempts.");
+      throw this.dependencyFailure("Managed Postgres recovery is cooling down after bounded attempts.");
     while (!this.stopped && this.attempts < RECOVERY_ATTEMPTS) {
       const attempt = this.attempts++;
       if (attempt > 0)
@@ -87901,12 +87999,12 @@ class PostgresHealth {
         if (ready !== undefined)
           return ready;
       } catch (error) {
-        this.failure = error instanceof Error ? error : new Error(String(error));
+        this.retainFailure(error);
       }
     }
     this.attempts = 0;
     this.nextRecoveryAt = (this.operations.now ?? Date.now)() + HEALTH_INTERVAL_MS;
-    throw new DbosDependencyError("Managed Postgres is unavailable after bounded recovery. Preserve its data and ownership records.");
+    throw this.dependencyFailure("Managed Postgres is unavailable after bounded recovery. Preserve its data and ownership records.");
   }
 }
 
@@ -88562,6 +88660,8 @@ async function ensureCluster(options = {}) {
           const server = current.server;
           if (!server)
             throw new Error("Managed Postgres published identity is missing.");
+          if (managedPostmaster(current) === undefined)
+            return;
           if (!managedPostgresRuntimeHealthy(current, server.port)) {
             verifyManagedPostmasterProcess(current, server);
             return;
@@ -88578,6 +88678,7 @@ async function ensureCluster(options = {}) {
         };
         health = new PostgresHealth({
           probe: () => inspect(),
+          url: embeddedDbosSystemDatabaseUrl,
           validate: async (client) => {
             const identity = await inspect(async () => {
               const query = { text: POSTGRES_IDENTITY_SQL, query_timeout: POSTGRES_HEALTH_QUERY_TIMEOUT_MS };
@@ -89665,6 +89766,9 @@ async function requireDockerSuccess(action, args) {
   throw new Error(`Could not ${action}: ${commandFailureDetail(result)}`);
 }
 
+// dist/builtin/workflows/src/durable/dbos-lifecycle.ts
+init_dbos_process_owner();
+
 // dist/builtin/workflows/src/durable/dbos-registration-diagnostics.ts
 var cachedErrorModule;
 var errorModuleLoad;
@@ -94385,6 +94489,9 @@ function registerWorkflowLifecycleHandlers(pi, deps) {
   });
 }
 
+// dist/builtin/workflows/src/extension/extension-runtime-state.ts
+init_dbos_process_owner();
+
 // dist/builtin/workflows/src/durable/workflow-heartbeat-anchor.ts
 var WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME = "workflow-heartbeat-anchor";
 function asPersistedAnchorOutput(output) {
@@ -102532,6 +102639,7 @@ function hasInvocationData(checkpoints, replayKey) {
 
 // dist/builtin/workflows/src/engine/run.ts
 init_dbos_admission();
+init_dbos_process_owner();
 
 // dist/builtin/workflows/src/runs/foreground/executor-direct-helpers.ts
 import { isAbsolute as isAbsolute12, join as join28, resolve as resolve12 } from "node:path";
@@ -114202,7 +114310,7 @@ async function run(def, inputs, opts = {}) {
         if (control === latestControl && !ownController.signal.aborted && isDbosDependencyError(error)) {
           activeStore.recordRunExecutionState(runId, {
             phase: "blocked_dependency",
-            dependencyError: `Workflow database unavailable during ${status === "paused" ? "pause" : "resume"}; persistence not confirmed.`
+            dependencyError: `Workflow database unavailable during ${status === "paused" ? "pause" : "resume"}; persistence not confirmed. ${error.message}`
           });
           if (status === "paused")
             return;
@@ -114249,7 +114357,7 @@ async function run(def, inputs, opts = {}) {
       if (!admission.admitting)
         return pausePersistence;
       backgroundAdmissionControl(durableBackend, runId, pausePersistence, (error, resumable) => {
-        admissionControlError = unknownErrorMessage(error);
+        admissionControlError = databaseDependencyMessage(unknownErrorMessage(error), getDbosProcessOwner().databaseDiagnostics?.());
         runSnapshot.error = admissionControlError;
         activeStore.recordRunPaused(runId, undefined, { resumable });
         return runSnapshot.error;
@@ -114266,7 +114374,7 @@ async function run(def, inputs, opts = {}) {
         } catch (error) {
           if (admission.failed) {
             scheduler.releaseRun();
-            throw error;
+            throw new Error(admissionControlError ?? databaseDependencyMessage(unknownErrorMessage(error), getDbosProcessOwner().databaseDiagnostics?.()));
           }
         }
         if (generation !== pauseGeneration)
@@ -114339,12 +114447,21 @@ async function run(def, inputs, opts = {}) {
     }).catch((error) => {
       const isTopologyError = typeof error === "object" && error !== null && "name" in error && error.name === "DurableNestedTopologyError";
       if (!isDbosDependencyError(error) && !isTopologyError) {
-        durableAdmissionFailure = { error };
-        classifiedFailures.set(error, classifyWorkflowFailure({
+        const admissionDetail = unknownErrorMessage(error);
+        const diagnostics = getDbosProcessOwner().databaseDiagnostics?.();
+        const safeMessage = databaseDependencyMessage(admissionDetail, diagnostics);
+        activeStore.recordRunExecutionState(runId, {
+          phase: "blocked_dependency",
+          dependencyError: safeMessage
+        });
+        const safeError = new Error(safeMessage);
+        durableAdmissionFailure = { error: safeError };
+        classifiedFailures.set(safeError, classifyWorkflowFailure({
           code: "ATOMIC_DURABLE_ADMISSION_REJECTED",
-          message: unknownErrorMessage(error),
-          cause: error
+          message: safeMessage,
+          cause: safeError
         }));
+        throw safeError;
       }
       throw error;
     }), ownController.signal);
@@ -115654,7 +115771,11 @@ function createExtensionRuntime(opts = {}) {
   const resolvePossibleStageEntry = opts.resolvePossibleStageEntry;
   const beforeRestoreCompleted = opts.beforeRestoreCompleted;
   const ensureDbosReady = async () => {
-    return await initializeDurableBackend(durabilityWarningSink);
+    if (opts.prepareDatabase !== undefined)
+      await opts.prepareDatabase();
+    const backend = await initializeDurableBackend(durabilityWarningSink);
+    opts.databaseReady?.();
+    return backend;
   };
   function runOptions(policy) {
     const defaultSessionDir = resolveDefaultStageSessionDir?.();
@@ -115925,6 +116046,95 @@ function createStatusWriter(store, config, opts = {}) {
   };
 }
 
+// dist/builtin/workflows/src/extension/workflow-database-settings.ts
+import { readFileSync as readFileSync7 } from "node:fs";
+import { readFile as readFile6 } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join33, resolve as resolve15 } from "node:path";
+import { getAgentDir as getAgentDir3, getAgentDirs as getAgentDirs3, getProjectConfigDirs, SettingsManager } from "@bastani/atomic";
+var DATABASE_SETTING_KEYS = new Set(["systemDatabaseUrl", "systemDatabaseUrlFile"]);
+function databaseSettings(settings) {
+  const workflows = settings.workflows;
+  if (workflows === undefined || workflows === null || Array.isArray(workflows))
+    return;
+  if (typeof workflows !== "object")
+    throw new TypeError("workflows must be an array of paths or an object");
+  return workflows.durability;
+}
+function readSettingsFile(directory) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync7(join33(directory, "settings.json"), "utf8").replace(/^\uFEFF/, ""));
+  } catch {
+    return;
+  }
+  return parsed !== null && typeof parsed === "object" ? parsed : undefined;
+}
+function settingsDirectoryDeclaringDatabase(directories) {
+  let declaring;
+  for (const directory of directories) {
+    const settings = readSettingsFile(directory);
+    if (settings !== undefined && databaseSettings(settings) !== undefined)
+      declaring ??= directory;
+  }
+  return declaring ?? directories[0];
+}
+async function resolveWorkflowDatabaseSettings(global2, project, directories) {
+  const projectDatabase = databaseSettings(project);
+  const database = projectDatabase !== undefined ? projectDatabase : databaseSettings(global2);
+  if (database === undefined)
+    return;
+  if (database === null || typeof database !== "object" || Array.isArray(database)) {
+    throw new TypeError("workflows.durability must be an object");
+  }
+  if (Object.keys(database).some((key) => !DATABASE_SETTING_KEYS.has(key))) {
+    throw new TypeError("workflows.durability supports only systemDatabaseUrl or systemDatabaseUrlFile");
+  }
+  const { systemDatabaseUrl: url, systemDatabaseUrlFile: file } = database;
+  if (url !== undefined && file !== undefined) {
+    throw new TypeError("Set only one of workflows.durability.systemDatabaseUrl and systemDatabaseUrlFile");
+  }
+  let value2 = url;
+  if (file !== undefined) {
+    if (typeof file !== "string" || file.trim() === "") {
+      throw new TypeError("workflows.durability.systemDatabaseUrlFile must be a non-empty path");
+    }
+    const path = file.startsWith("~/") || file.startsWith("~\\") ? join33(homedir3(), file.slice(2)) : resolve15(projectDatabase === undefined ? directories.global : directories.project, file);
+    try {
+      value2 = await readFile6(path, "utf8");
+    } catch {
+      throw new Error("Cannot read workflows.durability.systemDatabaseUrlFile; check its path and permissions");
+    }
+  }
+  if (value2 === undefined)
+    return;
+  if (typeof value2 !== "string" || value2.trim() === "") {
+    throw new TypeError("Workflow database selection must contain a non-empty Postgres URL");
+  }
+  try {
+    const parsed = new URL(value2.trim());
+    if (!["postgres:", "postgresql:"].includes(parsed.protocol) || parsed.hostname === "")
+      throw new Error;
+  } catch {
+    throw new TypeError("Workflow database selection must contain a valid Postgres URL");
+  }
+  return value2.trim();
+}
+async function prepareWorkflowDatabaseSettings(cwd, projectTrusted) {
+  if (process.env.DBOS_SYSTEM_DATABASE_URL?.trim())
+    return;
+  const manager = SettingsManager.create(cwd, getAgentDir3(), { projectTrusted });
+  if (manager.drainErrors().length > 0)
+    throw new Error("Cannot read workflow database settings; repair settings.json");
+  const projectDirectories = getProjectConfigDirs(cwd);
+  const url = await resolveWorkflowDatabaseSettings(manager.getGlobalSettings(), manager.getProjectSettings(), {
+    global: settingsDirectoryDeclaringDatabase(getAgentDirs3()),
+    project: projectTrusted ? settingsDirectoryDeclaringDatabase(projectDirectories) : projectDirectories[0]
+  });
+  if (url !== undefined)
+    requestDbosSystemDatabaseUrl(url);
+}
+
 // dist/builtin/workflows/src/extension/workflow-heartbeat-notice.ts
 var WORKFLOW_HEARTBEAT_TITLE = "WORKFLOW HEARTBEAT";
 var WORKFLOW_HEARTBEAT_GLYPH = "♥";
@@ -117076,6 +117286,45 @@ function createWorkflowExtensionRuntimeState(pi, adapters, options = {}) {
   const resolveDefaultStageSessionDir = () => hostStageSessionDir.current;
   const discoveryRef = { current: null };
   const resolvePossibleStageEntry = (normalizedName) => discoveryRef.current?.sources.find((source) => source.id === normalizedName)?.filePath ?? resolveBuiltinDefinitionSource(normalizedName);
+  let databasePreparation;
+  const prepareDatabase = () => {
+    const cwd = resolveCwd();
+    const trusted = pi.getResourceLoaderInheritanceSnapshot?.()?.projectTrusted ?? false;
+    const key = JSON.stringify([cwd, trusted]);
+    if (databasePreparation?.key === key)
+      return databasePreparation.promise;
+    const promise = prepareWorkflowDatabaseSettings(cwd, trusted).catch((error) => {
+      if (databasePreparation?.promise === promise)
+        databasePreparation = undefined;
+      throw error;
+    });
+    databasePreparation = { key, promise };
+    return promise;
+  };
+  const databaseReady = (ctx) => {
+    const owner = getDbosProcessOwner();
+    const describeDatabase = owner.databaseDiagnostics;
+    if (owner.state !== "ready" || describeDatabase === undefined)
+      return;
+    if (owner.announcedDatabaseDiagnostics === describeDatabase)
+      return;
+    const diagnostics = describeDatabase();
+    const dockerFallback = diagnostics.provider === "docker";
+    let host = "unknown host";
+    try {
+      host = new URL(diagnostics.url).host;
+    } catch {}
+    const message = `Workflow database: ${dockerFallback ? "Docker fallback" : diagnostics.provider} (${host})`;
+    if (ctx?.hasUI && ctx.ui?.notify) {
+      try {
+        ctx.ui.notify(message, "info");
+        owner.announcedDatabaseDiagnostics = describeDatabase;
+      } catch {}
+    } else if (dockerFallback) {
+      owner.announcedDatabaseDiagnostics = describeDatabase;
+      console.error(message);
+    }
+  };
   const startupDiscovery = discoverStartupWorkflowsSync();
   const runtimeRef = {
     current: createExtensionRuntime({
@@ -117089,7 +117338,9 @@ function createWorkflowExtensionRuntimeState(pi, adapters, options = {}) {
       config: runtimeConfigRef.current,
       resolvePossibleStageEntry,
       resolveDefaultStageSessionDir,
-      beforeRestoreCompleted
+      beforeRestoreCompleted,
+      prepareDatabase,
+      databaseReady
     })
   };
   const configLoadRef = { current: null };
@@ -117154,7 +117405,9 @@ function createWorkflowExtensionRuntimeState(pi, adapters, options = {}) {
       ...models === undefined ? {} : { models },
       ...durabilityWarningSink === undefined ? {} : { durabilityWarningSink },
       resolveDefaultStageSessionDir,
-      beforeRestoreCompleted
+      beforeRestoreCompleted,
+      prepareDatabase,
+      databaseReady: () => databaseReady(ctx)
     });
   }
   let lazyDiscoveryPromise = null;
@@ -117193,7 +117446,9 @@ function createWorkflowExtensionRuntimeState(pi, adapters, options = {}) {
       config: runtimeConfigRef.current,
       resolvePossibleStageEntry,
       resolveDefaultStageSessionDir,
-      beforeRestoreCompleted
+      beforeRestoreCompleted,
+      prepareDatabase,
+      databaseReady
     });
   }
   function isWorkflowDiscoveryCurrent(generation) {