Resonate External System of Record Pattern — Java

Prerelease note. resonate-sdk-java is published on Maven Central — pin io.resonatehq:resonate-sdk-java:0.1.1. The API mirrors the Python SDK and may change before a stable 1.0. Requires Java 21+ (virtual threads, a feature generally available in Java 21). There is no Java system-of-record example repo yet, so every code block here uses only documented SDK surface, compile-verified against 0.1.1 and cross-checked against develop/java.mdx (docs PR #230) and the SDK source.

Overview

For the language-agnostic framing and the "Write Last, Read First" mental model, see resonate-external-system-of-record-pattern-typescript. This skill translates that model to idiomatic Java: ctx.run-based checkpointing, type-keyed dependency injection for the external client, and idempotency keys derived from the durable execution's stable ID.

The core contract is simple: one system owns the truth. Resonate coordinates the workflow and guarantees at-least-once execution; the external system enforces consistency through its own primitives — idempotency keys, upserts, conditional writes, ledger deduplication.

When to use

• A Resonate workflow must create, update, or read from a database, payment processor, ledger, or any external store that has its own durability.
• You need multi-step operations (reserve → charge → record) to be safe to retry without double-writes.
• You cannot use distributed transactions across Resonate's promise store and the external system.

Do not use this pattern when all writes live inside a single ACID transaction scope — use the transaction directly.

The replay principle — wrap every SoR call in ctx.run