@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/src/authoring/workflow.ts

@@ -17,6 +17,7 @@ import type {
 	WorkflowOutputsFromSchemas,
 	WorkflowProvidedInputsFromSchemas,
 } from "../shared/workflow-authoring-types.js";
+import { DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES } from "../shared/workflow-heartbeat-contract.js";
 import { normalizeWorkflowName } from "../workflows/identity.js";
 
 export type {
@@ -158,6 +159,13 @@ export function workflow<
 	) {
 		throw new TypeError("workflow: inputs must be a schema map");
 	}
+	const heartbeatIntervalMinutes =
+		spec.heartbeatIntervalMinutes === undefined
+			? DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES
+			: spec.heartbeatIntervalMinutes;
+	if (!Number.isFinite(heartbeatIntervalMinutes) || heartbeatIntervalMinutes < 0) {
+		throw new TypeError("workflow: heartbeatIntervalMinutes must be a non-negative finite number");
+	}
 
 	const name = resolveWorkflowName(spec.name);
 	const normalizedName = normalizeWorkflowName(name);
@@ -174,6 +182,7 @@ export function workflow<
 		normalizedName,
 		description: spec.description,
 		...(spec.autoAttach === true ? { autoAttach: true } : {}),
+		heartbeatIntervalMinutes,
 		inputs: frozenInputs,
 		outputs: frozenOutputs,
 		...(inputBindings !== undefined ? { inputBindings } : {}),

package/dist/builtin/workflows/src/authoring.d.ts

@@ -4,6 +4,7 @@ export type { AgentSessionAdapter, CompleteAdapter, CompleteStageOpts, GitWorktr
 import type * as AuthoringContract from "./shared/authoring-contract.js";
 import type { AuthoredWorkflowSpec as SharedAuthoredWorkflowSpec, WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas } from "./shared/workflow-authoring-types.js";
 export type { WorkflowInputsFromSchemas, WorkflowOutputsFromSchemas, WorkflowProvidedInputsFromSchemas, } from "./shared/workflow-authoring-types.js";
+export type { WorkflowHeartbeatEvent, WorkflowHeartbeatEventDetails, WorkflowHeartbeatIdentity, } from "./shared/workflow-heartbeat-contract.js";
 import type { GitWorktreeSetupOptions, GitWorktreeSetupResult, ResolvedInputs, RunResult, RunStatus, StageSnapshot, WorkflowDefinition as WorkflowContractDefinition, WorkflowExecutionPolicy, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableObject } from "./shared/authoring-contract.js";
 declare const workflowDefinitionBrand: unique symbol;
 type WorkflowDefinitionBrand = {
@@ -55,6 +56,8 @@ export declare function workflow<const TInputs extends WorkflowInputSchemaMap =
 export declare function keepContext(text: string): string;
 export declare const KEEP_CONTEXT_OPEN_TAG: string;
 export declare const KEEP_CONTEXT_CLOSE_TAG: string;
+export declare const DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES: 15;
+export declare const WORKFLOW_HEARTBEAT_CUSTOM_TYPE: "workflows:workflow-heartbeat";
 export declare function createRegistry<TDefinitions extends readonly AnyWorkflowDefinition[] = readonly AnyWorkflowDefinition[]>(initial?: TDefinitions): WorkflowRegistry;
 export declare function normalizeWorkflowName(name: string): string;
 export declare function workflowNamesEqual(a: string, b: string): boolean;

package/dist/builtin/workflows/src/durable/completed-catalog.ts

@@ -1,6 +1,7 @@
 import { flattenTruncatedString } from "../shared/flat-string.js";
 import { isReopenableSessionTranscript } from "../shared/session-transcript.js";
 import type { RunSnapshot, StageSnapshot, ToolNodeSnapshot } from "../shared/store-types.js";
+import { boundedToolPayload, boundedToolPayloadRecord, boundedToolText } from "../shared/tool-payload-bounds.js";
 import type { WorkflowInputValues, WorkflowSerializableValue } from "../shared/types.js";
 import type { DurableWorkflowBackend } from "./backend.js";
 import {
@@ -23,6 +24,17 @@ import {
 import { isDurableWorkflowResumable } from "./resume-eligibility.js";
 import { resolveDurableEntry } from "./resume-runtime.js";
 import { priorRunElapsedMs, RUN_TIMING_CHECKPOINT_NAME } from "./run-timing.js";
+import { WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME } from "./workflow-heartbeat-anchor.js";
+
+/**
+ * Reserved run-level tool checkpoints that carry no graph node. They round-trip
+ * through the durable envelope like any tool checkpoint, so reconstruction has
+ * to skip them or they surface as phantom cached tool nodes.
+ */
+function isReservedRunCheckpointHash(argsHash: string): boolean {
+	return argsHash === RUN_TIMING_CHECKPOINT_NAME || argsHash === WORKFLOW_HEARTBEAT_ANCHOR_CHECKPOINT_NAME;
+}
+
 import {
 	directChildTopologyError,
 	groupByDurableStageKey,
@@ -218,7 +230,7 @@ function checkpointDrafts(checkpoints: readonly DurableCheckpoint[]): Reconstruc
 			stageByReplayKey.set(checkpoint.replayKey, mergeStageDraft(existing, checkpoint, sequence));
 			return;
 		}
-		if (checkpoint.kind !== "tool" || checkpoint.argsHash === RUN_TIMING_CHECKPOINT_NAME) return;
+		if (checkpoint.kind !== "tool" || isReservedRunCheckpointHash(checkpoint.argsHash)) return;
 		if (!firstToolSequenceByHash.has(checkpoint.argsHash)) {
 			firstToolSequenceByHash.set(checkpoint.argsHash, sequence);
 		}
@@ -255,6 +267,11 @@ function completedToolNodes(
 				kind: "tool" as const,
 				id: topology?.nodeId ?? checkpoint.checkpointId,
 				name: checkpoint.name,
+				// Restored nodes are recorded into the live store, which session and
+				// status surfaces clone and re-serialize, so these inspection copies
+				// are bounded. `checkpoint.output` itself stays exact for replay.
+				...(checkpoint.args !== undefined ? { args: boundedToolPayloadRecord(checkpoint.args) } : {}),
+				...(checkpoint.source !== undefined ? { source: boundedToolText(checkpoint.source) } : {}),
 				argsHash: checkpoint.argsHash,
 				ordinal: topology?.ordinal ?? index + 1,
 				parentIds: Object.freeze(
@@ -266,6 +283,10 @@ function completedToolNodes(
 				executionOrder: topology?.order ?? firstSequenceByHash.get(checkpoint.argsHash)!,
 				...(topology?.startedAt !== undefined ? { startedAt: topology.startedAt } : {}),
 				endedAt: topology?.endedAt ?? checkpoint.completedAt,
+				...(topology?.startedAt !== undefined
+					? { durationMs: Math.max(0, (topology?.endedAt ?? checkpoint.completedAt) - topology.startedAt) }
+					: {}),
+				...(checkpoint.throwingFailureError === undefined ? { result: boundedToolPayload(checkpoint.output) } : {}),
 				...(failed
 					? { error: failureError ?? "Invalid durable ctx.tool failure outcome" }
 					: { resultSummary: summarizeCompletedToolResult(checkpoint.output) }),
@@ -390,7 +411,7 @@ function runSnapshotsFromCheckpoints(
 		const supportedNonGraphState = checkpoints.every(
 			(checkpoint) =>
 				checkpoint.kind === "ui" ||
-				(checkpoint.kind === "tool" && checkpoint.argsHash === RUN_TIMING_CHECKPOINT_NAME),
+				(checkpoint.kind === "tool" && isReservedRunCheckpointHash(checkpoint.argsHash)),
 		);
 		if (policy.failClosed && supportedNonGraphState) {
 			return [emptyGraphRun(rootRunId, rootRunName, fallbackCompletedAt)];

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

@@ -81,6 +81,7 @@ export interface DbosStepRecord {
 	readonly completedAt?: number;
 }
 
+import { getDbosProcessOwner } from "./dbos-process-owner.js";
 import { createRealDbosHandle, type DbosLogger, type DbosStatic, getAtomicExecutorId } from "./dbos-sdk-handle.js";
 // ---------------------------------------------------------------------------
 // Real SDK handle factory (lazy import, no top-level dependency)
@@ -118,23 +119,35 @@ export async function configureDbosDurableBackend(config?: {
 	readonly systemDatabaseUrl?: string;
 }): Promise<ConfiguredDbosDurability> {
 	const sdk = await importDbosSdk();
-	const url = effectiveSystemDatabaseUrl(config?.systemDatabaseUrl);
-	sdk.setConfig({
-		name: "atomic-workflows",
-		...(url === undefined ? {} : { systemDatabaseUrl: url }),
-		runAdminServer: false,
-		// Unique per process: concurrent Atomic sessions share one database, and
-		// DBOS-level pending-workflow recovery must stay scoped to the owner.
-		executorID: getAtomicExecutorId(),
-		logger: SILENT_DBOS_LOGGER,
-	});
-	const mainWorkflow = sdk.registerWorkflow(async (_name: string, inputs: DurableInputs) => inputs, {
-		name: "atomicWorkflowHandle",
-	});
-	const checkpointWorkflow = sdk.registerWorkflow(
-		async (_workflowId: string, _stepName: string, output: WorkflowSerializableValue) => output,
-		{ name: "atomicWorkflowCheckpoint" },
-	);
+	const owner = getDbosProcessOwner();
+	const existing = owner.wrappers;
+	// The SDK forbids setConfig after launch. Recover original wrappers first.
+	if (existing === undefined) {
+		const url = effectiveSystemDatabaseUrl(config?.systemDatabaseUrl);
+		sdk.setConfig({
+			name: "atomic-workflows",
+			...(url === undefined ? {} : { systemDatabaseUrl: url }),
+			runAdminServer: false,
+			// Unique per process: concurrent Atomic sessions share one database, and
+			// DBOS-level pending-workflow recovery must stay scoped to the owner.
+			executorID: getAtomicExecutorId(),
+			logger: SILENT_DBOS_LOGGER,
+		});
+	}
+	const mainWorkflow =
+		existing?.mainWorkflow ??
+		sdk.registerWorkflow(async (_name: string, inputs: DurableInputs) => inputs, {
+			name: "atomicWorkflowHandle",
+		});
+	const checkpointWorkflow =
+		existing?.checkpointWorkflow ??
+		sdk.registerWorkflow(
+			async (_workflowId: string, _stepName: string, output: WorkflowSerializableValue) => output,
+			{ name: "atomicWorkflowCheckpoint" },
+		);
+	if (existing === undefined) {
+		owner.wrappers = { mainWorkflow, checkpointWorkflow };
+	}
 	return {
 		backend: new DbosDurableBackend(createRealDbosHandle(sdk, mainWorkflow, checkpointWorkflow)),
 		launch: () => sdk.launch(),

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

@@ -47,6 +47,8 @@ export interface DbosCheckpointEnvelope extends WorkflowSerializableObject {
 	readonly kind: DurableCheckpointKind;
 	readonly checkpointId: string;
 	readonly name?: string;
+	readonly args?: WorkflowSerializableValue;
+	readonly source?: string;
 	readonly argsHash?: string;
 	readonly promptKind?: UiPromptKind;
 	readonly outcomeKind?: "return_success" | "return_failure";
@@ -99,6 +101,8 @@ export function encodeCheckpoint(checkpoint: DurableCheckpoint): DbosCheckpointE
 		return {
 			...base,
 			name: t.name,
+			...(t.args !== undefined ? { args: t.args } : {}),
+			...(t.source !== undefined ? { source: t.source } : {}),
 			argsHash: t.argsHash,
 			...(t.outcomeKind !== undefined ? { outcomeKind: t.outcomeKind } : {}),
 			...(t.throwingFailureError !== undefined ? { throwingFailureError: t.throwingFailureError } : {}),
@@ -218,6 +222,10 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
 		return undefined;
 	const common = { workflowId, checkpointId: env.checkpointId, completedAt: env.completedAt };
 	if (env.kind === "tool") {
+		// An inspection-only field must never invalidate durable state: one
+		// rejected checkpoint suppresses the whole workflow and re-runs completed
+		// side effects. `args` and `source` are therefore ignored when they are
+		// not the expected shape, while the replayable fields stay strict.
 		if (
 			typeof env.argsHash !== "string" ||
 			env.output === undefined ||
@@ -227,6 +235,10 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
 			(env.throwingFailureError !== undefined && typeof env.throwingFailureError !== "string")
 		)
 			return undefined;
+		const inspectionArgs =
+			typeof env.args === "object" && env.args !== null && !Array.isArray(env.args)
+				? (env.args as Readonly<Record<string, WorkflowSerializableValue>>)
+				: undefined;
 		const outcome = env.outcomeKind === undefined ? undefined : workflowToolOutcomeFromValue(env.output);
 		if (
 			(env.outcomeKind === "return_success" && outcome?.ok !== true) ||
@@ -239,6 +251,8 @@ function decodeEnvelope(workflowId: string, env: DbosCheckpointEnvelope): Durabl
 			kind: "tool",
 			...common,
 			name: env.name ?? "tool",
+			...(inspectionArgs !== undefined ? { args: inspectionArgs } : {}),
+			...(typeof env.source === "string" ? { source: env.source } : {}),
 			argsHash: env.argsHash,
 			output: env.output,
 			...(env.outcomeKind !== undefined ? { outcomeKind: env.outcomeKind } : {}),

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

@@ -4,6 +4,8 @@ import {
 	resolveDbosSystemDatabaseUrl,
 	shouldProvisionLocalDbos,
 } from "./dbos-local-postgres.js";
+import { getDbosProcessOwner, resetDbosProcessOwner } from "./dbos-process-owner.js";
+import { classifyDbosDurabilityFailure, readDbosFailureDetail } from "./dbos-registration-diagnostics.js";
 
 export type DbosLifecycleState =
 	| "uninitialized"
@@ -52,49 +54,51 @@ const defaultConfigurator: DbosConfigurator = async () => {
 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,
-	);
+function owner(): ReturnType<typeof getDbosProcessOwner> {
+	return getDbosProcessOwner();
+}
+
+async function durabilityFailure(action: string, error: unknown): Promise<DbosDurabilityError> {
+	const detail = readDbosFailureDetail(error);
+	const kind = await classifyDbosDurabilityFailure(error);
+	const guidance =
+		kind === "duplicate_registration"
+			? "A duplicate DBOS operation registration caused this failure; changing the database URL will not resolve it."
+			: "Set DBOS_SYSTEM_DATABASE_URL to an existing Postgres when local provisioning is unavailable.";
+	const cause = error instanceof Error ? { cause: error } : undefined;
+	return new DbosDurabilityError(`DBOS workflow durability ${action} failed: ${detail}. ${guidance}`, cause);
 }
 
 export async function configureDbosOnce(): Promise<ConfiguredDbosDurability> {
-	if (failure !== undefined) throw failure;
-	configured ??= configureDurability()
+	const slot = owner();
+	if (slot.failure !== undefined) throw slot.failure;
+	slot.configured ??= configureDurability()
 		.then((value) => {
-			active = value;
-			state = "configured";
+			slot.active = value;
+			slot.state = "configured";
 			return value;
 		})
-		.catch((error: unknown) => {
-			failure = durabilityFailure("configuration", error);
-			state = "failed";
-			throw failure;
+		.catch(async (error: unknown) => {
+			slot.failure = await durabilityFailure("configuration", error);
+			slot.state = "failed";
+			throw slot.failure;
 		});
-	return await configured;
+	return await slot.configured;
 }
 
 export async function launchDbosOnce(): Promise<void> {
-	if (failure !== undefined) throw failure;
+	const slot = owner();
+	if (slot.failure !== undefined) throw slot.failure;
 	// The executor is process-scoped and stops exactly once, at process exit.
 	// Post-shutdown launches must fail loudly instead of returning a backend
 	// whose SDK launched marker has been cleared.
-	if (state === "shutting_down" || state === "shut_down") throw new DbosShutdownError();
+	if (slot.state === "shutting_down" || slot.state === "shut_down") throw new DbosShutdownError();
 	const durability = await configureDbosOnce();
-	launchPromise ??= (async () => {
-		state = "launching";
+	slot.launchPromise ??= (async () => {
+		slot.state = "launching";
 		try {
 			await durability.launch();
-			state = "ready";
+			slot.state = "ready";
 		} catch (error) {
 			if (shouldProvisionLocalDbos(error)) {
 				try {
@@ -103,54 +107,57 @@ export async function launchDbosOnce(): Promise<void> {
 					await durability.shutdown();
 					await provisionLocalDbos();
 					await durability.launch();
-					state = "ready";
+					slot.state = "ready";
 					return;
 				} catch (provisionError) {
-					failure = durabilityFailure("local Postgres startup", provisionError);
+					slot.failure = await durabilityFailure("local Postgres startup", provisionError);
 				}
 			} else {
-				failure = durabilityFailure("launch", error);
+				slot.failure = await durabilityFailure("launch", error);
 			}
-			state = "failed";
-			throw failure;
+			slot.state = "failed";
+			throw slot.failure;
 		}
 	})();
-	await launchPromise;
+	await slot.launchPromise;
 }
 
 export async function getReadyDbosBackend(): Promise<DbosDurableBackend> {
 	await launchDbosOnce();
-	if (state !== "ready" || active === undefined) throw failure ?? new DbosNotReadyError();
-	return active.backend;
+	const slot = owner();
+	if (slot.state !== "ready" || slot.active === undefined) throw slot.failure ?? new DbosNotReadyError();
+	return slot.active.backend;
 }
 
 export function getReadyDbosBackendSync(): DbosDurableBackend | undefined {
-	return state === "ready" ? active?.backend : undefined;
+	const slot = owner();
+	return slot.state === "ready" ? slot.active?.backend : undefined;
 }
 
 export async function shutdownDbos(): Promise<void> {
-	if (shutdownPromise !== undefined) return await shutdownPromise;
-	const configuredPromise = configured;
+	const slot = owner();
+	if (slot.shutdownPromise !== undefined) return await slot.shutdownPromise;
+	const configuredPromise = slot.configured;
 	if (configuredPromise === undefined) return;
-	shutdownPromise = (async () => {
+	slot.shutdownPromise = (async () => {
 		// A backend that never reached "ready" has nothing to flush or stop.
 		// `configured`/`launchPromise` memoize rejections, so re-awaiting them
 		// unguarded would rethrow the original provisioning failure out of every
 		// session dispose — crashing otherwise-successful runs at process exit.
 		const durability = await configuredPromise.catch(() => undefined);
 		if (durability === undefined) return;
-		if (launchPromise !== undefined) await launchPromise.catch(() => undefined);
-		if (state !== "ready") return;
-		state = "shutting_down";
+		if (slot.launchPromise !== undefined) await slot.launchPromise.catch(() => undefined);
+		if (slot.state !== "ready") return;
+		slot.state = "shutting_down";
 		await durability.backend.flush();
 		await durability.shutdown();
-		state = "shut_down";
-	})().catch((error: unknown) => {
-		failure = durabilityFailure("shutdown", error);
-		state = "failed";
-		throw failure;
+		slot.state = "shut_down";
+	})().catch(async (error: unknown) => {
+		slot.failure = await durabilityFailure("shutdown", error);
+		slot.state = "failed";
+		throw slot.failure;
 	});
-	await shutdownPromise;
+	await slot.shutdownPromise;
 }
 
 /**
@@ -159,12 +166,13 @@ export async function shutdownDbos(): Promise<void> {
  * `/fork`, `/reload`) where the DBOS executor must stay launched.
  */
 export async function flushDbos(): Promise<void> {
-	if (state !== "ready" || active === undefined) return;
-	await active.backend.flush();
+	const slot = owner();
+	if (slot.state !== "ready" || slot.active === undefined) return;
+	await slot.active.backend.flush();
 }
 
 export function dbosLifecycleState(): DbosLifecycleState {
-	return state;
+	return owner().state;
 }
 
 /** Reset the process singleton with an explicit configurator for unit tests. */
@@ -172,12 +180,7 @@ export function resetDbosLifecycleForTests(
 	configurator: DbosConfigurator = defaultConfigurator,
 	provisioner: LocalDbosProvisioner = provisionResolvedLocalDbos,
 ): void {
-	state = "uninitialized";
-	configured = undefined;
-	active = undefined;
-	launchPromise = undefined;
-	shutdownPromise = undefined;
-	failure = undefined;
+	resetDbosProcessOwner();
 	configureDurability = configurator;
 	provisionLocalDbos = provisioner;
 }

package/dist/builtin/workflows/src/durable/dbos-process-owner.ts

@@ -0,0 +1,87 @@
+/**
+ * Process-global owner for DBOS lifecycle state and registered wrappers.
+ *
+ * `@dbos-inc/dbos-sdk` keeps a process-global operation registry that #1958
+ * leaves alive across session replacement. The workflows bundle is re-evaluated
+ * on `/reload` and the other process-preserving boundaries, so module-local
+ * variables restart at `uninitialized` and `configureDbosDurableBackend` would
+ * register `atomicWorkflowHandle` / `atomicWorkflowCheckpoint` a second time.
+ * The second registration throws and the replacement session degrades to
+ * `InMemoryDurableBackend` (#2022).
+ *
+ * Session scope is the wrong lifetime: the SDK registry is process-global, so
+ * a session-scoped owner would re-register per session and reproduce the bug.
+ * This slot lives on `globalThis` under `Symbol.for` so every load generation
+ * of the bundle — and a second copy of the module reached through a different
+ * specifier — shares one owner.
+ *
+ * The `@1` suffix is the shape version. Bump it when these fields change so a
+ * new generation declines an incompatible predecessor instead of reading it.
+ */
+
+import type { WorkflowSerializableValue } from "../shared/types.js";
+import type { ConfiguredDbosDurability } from "./dbos-backend.js";
+import type { DbosDurabilityError, DbosLifecycleState } from "./dbos-lifecycle.js";
+
+export const DBOS_PROCESS_OWNER_KEY = Symbol.for("atomic-workflows/dbos-process-owner@1");
+
+export interface DbosRegisteredWrappers {
+	readonly mainWorkflow: (
+		name: string,
+		inputs: Record<string, WorkflowSerializableValue>,
+	) => Promise<WorkflowSerializableValue>;
+	readonly checkpointWorkflow: (
+		workflowId: string,
+		stepName: string,
+		output: WorkflowSerializableValue,
+	) => Promise<WorkflowSerializableValue>;
+}
+
+export interface DbosProcessOwner {
+	readonly version: 1;
+	state: DbosLifecycleState;
+	configured: Promise<ConfiguredDbosDurability> | undefined;
+	active: ConfiguredDbosDurability | undefined;
+	launchPromise: Promise<void> | undefined;
+	shutdownPromise: Promise<void> | undefined;
+	failure: DbosDurabilityError | undefined;
+	wrappers: DbosRegisteredWrappers | undefined;
+}
+
+function emptyOwner(): DbosProcessOwner {
+	return {
+		version: 1,
+		state: "uninitialized",
+		configured: undefined,
+		active: undefined,
+		launchPromise: undefined,
+		shutdownPromise: undefined,
+		failure: undefined,
+		wrappers: undefined,
+	};
+}
+
+function ownerBag(): Record<symbol, DbosProcessOwner | undefined> {
+	return globalThis as typeof globalThis & Record<symbol, DbosProcessOwner | undefined>;
+}
+
+export function getDbosProcessOwner(): DbosProcessOwner {
+	const bag = ownerBag();
+	const existing = bag[DBOS_PROCESS_OWNER_KEY];
+	if (existing !== undefined && existing.version === 1) return existing;
+	const created = emptyOwner();
+	bag[DBOS_PROCESS_OWNER_KEY] = created;
+	return created;
+}
+
+/** Reset every field on the process-global slot. Used by durability tests. */
+export function resetDbosProcessOwner(): void {
+	const owner = getDbosProcessOwner();
+	owner.state = "uninitialized";
+	owner.configured = undefined;
+	owner.active = undefined;
+	owner.launchPromise = undefined;
+	owner.shutdownPromise = undefined;
+	owner.failure = undefined;
+	owner.wrappers = undefined;
+}

package/dist/builtin/workflows/src/durable/dbos-registration-diagnostics.ts

@@ -0,0 +1,113 @@
+/**
+ * Classify DBOS durability failures so a duplicate operation registration
+ * is not described as a Postgres provisioning problem (#2022 / #2462).
+ *
+ * Uses the SDK `Error` namespace (`DBOSConflictingRegistrationError` and
+ * `getDBOSErrorCode`). The SDK is loaded lazily so this module never
+ * statically imports `@dbos-inc/dbos-sdk`. `instanceof` is not used: two
+ * resolved copies of the SDK would make it fail.
+ */
+
+export type DbosDurabilityFailureKind = "duplicate_registration" | "other";
+
+interface DbosSdkErrorModule {
+	readonly DBOSConflictingRegistrationError?: new (msg: string) => object;
+	readonly getDBOSErrorCode?: (error: Error) => number | undefined;
+}
+
+let cachedErrorModule: DbosSdkErrorModule | undefined;
+let errorModuleLoad: Promise<DbosSdkErrorModule | undefined> | undefined;
+
+async function loadDbosErrorModule(): Promise<DbosSdkErrorModule | undefined> {
+	if (cachedErrorModule !== undefined) return cachedErrorModule;
+	errorModuleLoad ??= (async () => {
+		const spec = "@dbos-inc/dbos-sdk";
+		try {
+			const mod = (await import(spec)) as { readonly Error?: DbosSdkErrorModule };
+			cachedErrorModule = mod.Error;
+			return cachedErrorModule;
+		} catch {
+			return undefined;
+		}
+	})();
+	return await errorModuleLoad;
+}
+
+function conflictingRegistrationCode(errors: DbosSdkErrorModule | undefined): number | undefined {
+	const ctor = errors?.DBOSConflictingRegistrationError;
+	if (ctor === undefined) return undefined;
+	try {
+		const code = Reflect.get(new ctor(""), "dbosErrorCode");
+		return typeof code === "number" ? code : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function isDuplicateRegistration(value: object, errors: DbosSdkErrorModule | undefined): boolean {
+	const expected = conflictingRegistrationCode(errors);
+	const code = readOwn(value, "dbosErrorCode");
+	if (typeof code === "number" && typeof expected === "number" && code === expected) return true;
+	if (errors?.getDBOSErrorCode !== undefined && value instanceof Error) {
+		try {
+			if (errors.getDBOSErrorCode(value) === expected) return true;
+		} catch {
+			/* keep walking */
+		}
+	}
+	const name = readOwn(value, "name");
+	const className = errors?.DBOSConflictingRegistrationError?.name;
+	return typeof name === "string" && typeof className === "string" && name === className;
+}
+
+function classifyWith(error: unknown, errors: DbosSdkErrorModule | undefined): DbosDurabilityFailureKind {
+	try {
+		const seen = new Set<object>();
+		let current: unknown = error;
+		while (current !== undefined && current !== null) {
+			if (typeof current !== "object") return "other";
+			if (seen.has(current)) return "other";
+			seen.add(current);
+			if (isDuplicateRegistration(current, errors)) return "duplicate_registration";
+			current = readOwn(current, "cause");
+		}
+	} catch {
+		return "other";
+	}
+	return "other";
+}
+
+/**
+ * Async classification used at the durability boundary so the first failure
+ * can load the SDK error classes before deciding. Subsequent sync callers
+ * reuse the cached module.
+ */
+export async function classifyDbosDurabilityFailure(error: unknown): Promise<DbosDurabilityFailureKind> {
+	const errors = await loadDbosErrorModule();
+	return classifyWith(error, errors);
+}
+
+/**
+ * Read an error's display detail without letting a throwing `message` getter
+ * escape the durability wrapper. `String(error)` is the last-resort fallback
+ * and is itself guarded: some `toString` implementations also throw.
+ */
+export function readDbosFailureDetail(error: unknown): string {
+	if (typeof error === "object" && error !== null) {
+		const message = readOwn(error, "message");
+		if (typeof message === "string" && message !== "") return message;
+	}
+	try {
+		return String(error);
+	} catch {
+		return "unknown error";
+	}
+}
+
+function readOwn(value: object, key: string): unknown {
+	try {
+		return Reflect.get(value, key);
+	} catch {
+		return undefined;
+	}
+}

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

@@ -8,6 +8,7 @@ import {
 	getReadyDbosBackend,
 	getReadyDbosBackendSync,
 } from "./dbos-lifecycle.js";
+import { classifyDbosDurabilityFailure, readDbosFailureDetail } from "./dbos-registration-diagnostics.js";
 
 let injectedBackend: DurableWorkflowBackend | undefined;
 let initializedBackend: DurableWorkflowBackend | undefined;
@@ -65,12 +66,9 @@ export async function initializeDurableBackend(): Promise<DurableWorkflowBackend
 		initializing = undefined;
 	}
 	initializing ??= getReadyDbosBackend()
-		.catch((error: unknown) => {
-			// Post-shutdown initialization is a process-exit race, not a
-			// provisioning failure: fail loudly instead of silently degrading to a
-			// non-durable backend.
+		.catch(async (error: unknown) => {
 			if (error instanceof DbosShutdownError) throw error;
-			return degradeToNonDurableBackend(error);
+			return await degradeToNonDurableBackend(error);
 		})
 		.then((backend) => {
 			initializedBackend = backend;
@@ -79,12 +77,17 @@ export async function initializeDurableBackend(): Promise<DurableWorkflowBackend
 	return await initializing;
 }
 
-function degradeToNonDurableBackend(error: unknown): DurableWorkflowBackend {
-	const detail = error instanceof Error ? error.message : String(error);
+async function degradeToNonDurableBackend(error: unknown): Promise<DurableWorkflowBackend> {
+	const detail = readDbosFailureDetail(error);
+	const kind = await classifyDbosDurabilityFailure(error);
+	const restore =
+		kind === "duplicate_registration"
+			? `Restore durability by resolving the duplicate DBOS operation registration: ${detail}`
+			: `Restore durability by fixing Postgres provisioning: ${detail}`;
 	console.error(
 		"atomic-workflows: durable backend unavailable — continuing NON-DURABLY with an in-memory backend. " +
 			"Workflow runs will execute, but their state will not survive this process and `/workflow resume` " +
-			`after exit will not work. Restore durability by fixing Postgres provisioning: ${detail}`,
+			`after exit will not work. ${restore}`,
 	);
 	return new InMemoryDurableBackend();
 }