Resonate Migrate From Dbos

Migrate from DBOS to Resonate

A pattern-by-pattern playbook for porting a DBOS application to Resonate. Identify which DBOS construct each piece of the source uses, apply the matching transform, and reach for the linked per-SDK skill for idiomatic target code.

Ground rules

• Never invent DBOS code. Quote it from the user's source or a named dbos-inc/dbos-demo-apps / dbos-transact-* file. If you can't find it, say so.
• DBOS has SDKs for TypeScript, Python, Go, and Java — but no Rust SDK. Don't emit DBOS Rust. When migrating to Resonate Rust, map from the DBOS Python or TypeScript idiom.
• Resonate has no @DBOS.workflow/@DBOS.step split. A step is just a function made durable by ctx.run. Don't invent decorators or a step type.
• A DBOS workflow must be deterministic — side effects live in steps. The same discipline carries to Resonate: do side-effecting work inside ctx.run so it is checkpointed, not re-executed on replay.
• State coverage honestly. A missing example ≠ impossible; it means no worked reference exists yet.
• Verify APIs against the pinned version before emitting — both the DBOS and Resonate SDK surfaces drift between versions.

Pinned SDK versions (latest released at time of writing)

Core mappings (apply everywhere)

Pattern: Workflow + step

• DETECT: @DBOS.workflow() + @DBOS.step() (py), DBOS.registerWorkflow + DBOS.runStep / @DBOS.workflow()/@DBOS.step() static-method decorators (ts), dbos.RegisterWorkflow + dbos.RunAsStep (go).
• TRANSFORM: Register one function. Turn each step into a plain function called via ctx.run. Drop the decorator split and the systemDatabaseUrl config.
• DBOS SOURCE: dbos-demo-apps/{python/dbos-app-starter,typescript/dbos-node-starter,golang/dbos-go-starter}.
• RESONATE TARGET: example-hello-world-{ts,py,rs,go}.
• RELATED SKILL: resonate-basic-durable-world-usage-{typescript,python,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ✅ (DBOS has no Rust source — map from py/ts).

Pattern: Child workflows (composition + recursion)

• DETECT: DBOS.start_workflow(fn, ...) (py), DBOS.startWorkflow(fn)(...) (ts), dbos.RunWorkflow(ctx, fn, args) called inside a workflow (go).
• TRANSFORM: Replace the child-workflow call with a call to a registered function by name (ctx.rpc("name", args) / ctx.run(fn, args)). A function can recurse on itself — Resonate composes functions indefinitely. Optionally pin child ids with .options(id=…).
• DBOS SOURCE: dbos-demo-apps/{python,golang}/widget-store (start_workflow/RunWorkflow of the dispatch workflow). DBOS does not ship a recursive example.
• RESONATE TARGET: example-recursive-factorial-{ts,py,rs,go}.
• RELATED SKILL: resonate-recursive-fan-out-pattern-{typescript,python,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ✅.

Pattern: Fan-out / fan-in (durable queues → parallel + join)

• DETECT: DBOS.register_queue(...) + a loop of DBOS.enqueue_workflow(queue, fn, x) then handle.get_result() (py), DBOS.startWorkflow(fn, { queueName })(x) then h.getResult() (ts), dbos.NewWorkflowQueue + dbos.RunWorkflow(..., dbos.WithQueue(q.Name)) then handle.GetResult() (go).
• TRANSFORM: Start each unit non-blocking — ctx.beginRun (ts) / ctx.rfi (py) / ctx.run(...).spawn() (rs) / ctx.RPC (go); each returns a future immediately. Then await each future. Start ALL before awaiting ANY, or the work serializes.
• NOTE: DBOS queues also provide concurrency limits, rate limits, priority, and debouncing. Resonate's fan-out primitive is parallelism + join, not a managed queue — if the source relies on per-queue flow control, plan how to reproduce it (e.g. a worker group plus application-level limiting) and say so.
• DBOS SOURCE: DBOS docs Python queue tutorial + TypeScript programming guide (the process_tasks enqueue-N-then-get_result fan-out), dbos-transact-golang README (10-task fan-out). (dbos-demo-apps/python/queue-patterns shows fair-queue / rate-limit / debounce, not a plain fan-out.)
• RESONATE TARGET: example-fan-out-fan-in-{ts,py,rs,go}.
• RELATED SKILL: resonate-recursive-fan-out-pattern-{typescript,python,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ✅.

Pattern: Durable sleep

• DETECT: DBOS.sleep(seconds) (py), DBOS.sleep(ms) (ts), dbos.Sleep(ctx, duration) (go).
• TRANSFORM: Replace with ctx.sleep(duration). Mind the units — they match DBOS almost exactly:
  • TypeScript: milliseconds (ctx.sleep(ms)). DBOS DBOS.sleep is also ms.
  • Python: seconds as float (ctx.sleep(secs)). DBOS DBOS.sleep is also seconds.
  • Go: time.Duration (ctx.Sleep(d) then f.Await(nil)). DBOS dbos.Sleep(ctx, d) is also time.Duration.
  • Rust: std::time::Duration (ctx.sleep(Duration::from_secs(n)).await?).
• DBOS SOURCE: dbos-demo-apps/{python,golang}/widget-store (DBOS.sleep(1) / dbos.Sleep(ctx, time.Second)), dbos-demo-apps/typescript/widget-store/src/shop.ts (DBOS.sleep(1000)).
• RESONATE TARGET: example-durable-sleep-{ts,py,rs,go}.
• RELATED SKILL: resonate-durable-sleep-scheduled-work-{typescript,rust,go} (no Python variant yet — for Python durable-sleep, delegate to resonate-basic-durable-world-usage-python).
• COVERAGE: ts ✅ py ✅ rs ✅ go ✅.

Pattern: Scheduled (cron) workflows

• DETECT: @DBOS.scheduled(cron) decorator over @DBOS.workflow() with a (scheduled, actual) datetime signature (py/ts), DBOS.create_schedule(...) / apply_schedules(...) (py/ts), dbos.WithSchedule(cron) registration option (go).
• TRANSFORM: Register a schedule against the Resonate Server: resonate.schedule(id, cron, fn, ...args) (ts/rust) or resonate.schedules.create(id=…, cron=…, promise_id=…, …) (py). The server fires the promise on the cron; the worker runs the registered function.
• MIND THE CRON FIELDS: DBOS uses a 6-field cron with a leading seconds component (* * * * * * = every second). Resonate takes a standard 5-field cron (* * * * * = every minute). Drop the leading seconds field when migrating, or a * * * * * * copied verbatim silently fires far more often than intended.
• DBOS SOURCE: dbos-transact-py/tests/test_scheduler_decorator.py, dbos-transact-ts/tests/scheduler_decorator.test.ts, dbos-transact-golang README.
• RESONATE TARGET: example-schedule-{ts,py,rs}.
• RELATED SKILL: resonate-durable-sleep-scheduled-work-{typescript,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ⚠️ (no example-schedule-go yet; Go's 0.1.0 Schedules().Create covers the direct cron-fired-promise half, but there is no top-level resonate.Schedule(id, cron, fn, args) convenience wrapper yet — map by analogy, or set the resonate:target dispatch tag by hand, per resonate-durable-sleep-scheduled-work-go).

Pattern: Communication → durable promises (human-in-the-loop)

• DETECT: DBOS.recv(topic, timeout) + DBOS.send(destId, msg, topic) and/or DBOS.set_event(key, value) + DBOS.get_event(wfId, key) (py/ts/go; Go uses generic forms dbos.Recv[T] / dbos.Send / dbos.SetEvent / dbos.GetEvent[T]).
• TRANSFORM: Replace the recv/set_event pair with a single latent durable promise (p = ctx.promise(); await p). Surface p.id to whoever will resolve it. Replace the external DBOS.send(...) with resonate.promises.resolve(id, value). The promise's resolved value is the status — you don't need a separate get_event channel.
• RESOLVE API — verify against pinned version:
  • ts (0.11.4): the data field is base64-encoded JSON — const data = Buffer.from(JSON.stringify(v), "utf8").toString("base64"); resonate.promises.resolve(id, { data }) (the codec base64-decodes data, so a raw JSON.stringify(v) round-trips to garbage)
  • py (0.7.4): await resonate.promises.resolve(id, value) — positional id and a Value, not resolve(id=…, ikey=…); there is no ikey kwarg on Promises.resolve in this release. Confirm the exact call shape against example-human-in-the-loop-py before emitting.
  • rs (0.6.0): resonate.promises.resolve(&id, Value::from_serializable(v)?) (the example repo may use json!(v) — verify it compiles against your released crate version; use the Value form if not)
  • go (0.1.0): r.Promises().Resolve(ctx, id, v) — the direct Promises() sub-client handles the codec encoding for you. The CLI (resonate promises resolve <id> --value '{"headers":{},"data":"…"}') and the lower-level sender/promise-settle path remain available.
• DBOS SOURCE: dbos-demo-apps/{python,typescript,golang}/widget-store, dbos-demo-apps/python/agent-inbox (richer HITL with recv + set_event).
• RESONATE TARGET: example-human-in-the-loop-{ts,py,rs,go}.
• RELATED SKILL: resonate-human-in-the-loop-pattern-{typescript,python,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ✅ (0.1.0 has a direct Promises().Resolve; the CLI and low-level Sender().PromiseSettle remain as alternates).

Pattern: Saga / compensation

• DETECT: a DBOS workflow that, on a failed/declined step, calls an explicit undo step (e.g. undo_reserve_inventory() / undoSubtractInventory() / undoReserveInventory) in the failure branch. DBOS has no saga DSL.
• TRANSFORM: Run each step with ctx.run. On failure, run the undo inline in the catch/error branch, guarded by which steps actually completed. Make compensations idempotent. Same shape as DBOS — no compensation stack, no helper.
• DBOS SOURCE: dbos-demo-apps/{python,typescript,golang}/widget-store (checkout workflow), dbos-demo-apps/python/reliable-refunds-langchain.
• RESONATE TARGET: example-saga-booking-ts, example-money-transfer-{py,rs}.
• RELATED SKILL: resonate-saga-pattern-{typescript,python,rust,go}.
• COVERAGE: ts ✅ py ✅ rs ✅ go ⚠️ (no Go example yet — map by analogy).

What does not map cleanly (do not fabricate)

• Exactly-once Kafka consumers (@DBOS.kafka_consumer) are a DBOS built-in with no direct Resonate example. The closest Resonate shape is a worker that creates a promise keyed by the message's idempotency key, but there is no worked sample — say so.
• Durable queue flow control (concurrency/rate-limit/priority/debounce) is a DBOS queue feature. Resonate fan-out is parallelism + join only; reproduce limits at the application or worker-group level and flag the gap.
• Built-in observability dashboard + workflow-management APIs (list_workflows, cancel, resume, fork) are DBOS features without a 1:1 Resonate analog.

Coverage gaps (Resonate examples that don't exist yet)

• Scheduled work: no example-schedule-go.
• Saga: no Go example (example-money-transfer-go / example-saga-booking-go).
• DBOS has no Rust SDK, so all Rust migrations map from the DBOS Python/TypeScript idiom.

Source of truth

• Resonate examples: https://github.com/resonatehq-examples
• DBOS demos + SDKs: https://github.com/dbos-inc (dbos-demo-apps, dbos-transact-{py,ts,golang})
• DBOS docs: https://docs.dbos.dev
• Side-by-side guide: https://docs.resonatehq.io/evaluate/coming-from/dbos
• Concepts first: see the durable-execution and resonate-philosophy skills.