Durable Promises And Awakeables

A handler creates an awakeable and must hand its id to a third-party callback so the third party can resolve it later. The handler stores the id only in a local variable and awaits.

Create the awakeable with ctx.awakeable(), then durably hand its id to the external system inside a journaled step (the call that registers the callback) BEFORE awaiting it — so a crash between creation and handoff does not orphan a promise nobody can resolve. The id is the rendezvous token; treat …

An external approval system can approve or deny. The integrator resolves the awakeable with a payload on approval but, on denial, simply never resolves it.

Resolve the awakeable with a payload on success and REJECT it with an error on denial (ctx-side, the awaiting handler then throws). Never leave an awakeable unresolved on the failure path — the awaiting invocation would hang until timeout. Model both outcomes explicitly so the handler can branch on…

An awakeable is resolved with an arbitrary JSON shape on one side and deserialized into a strict type on the awaiting side, which differs.

Treat the awakeable payload as a typed contract shared between resolver and awaiter (a versioned schema). Validate on receipt and fail with a TerminalError on schema mismatch rather than silently coercing. Keep the payload small and reference large data by storage key.