resonatehq/resonate-skills/resonate-advanced-reasoning-typescript

Resonate Advanced Reasoning

Spec Reference

The normative ground truth for promise lifecycle, handler semantics, and state transitions is the Resonate specification — an executable abstract machine in Lean 4:

• Repository: <https://github.com/resonatehq/resonate-specification>
• Key files: spec/01-objects/state.lean (promise/task state), spec/02-actions/ (P-*.lean for promise handlers, T-*.lean for task handlers, S-*.lean for schedule handlers)

When this skill and the spec diverge, the spec wins.

Overview

Use this skill to translate Resonate specification concepts into Resonate TypeScript SDK usage. Treat the spec as the mental model and the SDK as its concrete expression.

Spec to SDK Translation Map

System Model -> Runtime

• Process -> a single Node.js process running new Resonate(...).
• Logical process -> a group of interchangeable workers (group + target).
• Message passing -> Async RPC over HTTP long poll (or Kafka/SQS transport).
• Addressing -> poll://any@<group> or poll://id@<group> targets.

Execution Model -> SDK Semantics

• Execution -> a durable function invocation.
• Invoke event -> run, rpc, beginRun, or beginRpc.
• Return event -> durable promise resolution stored by the server.
• Durable promise -> the promise ID for each invocation step.
• Resume -> internal callback that replays and continues after a promise resolves.

Programming Model -> SDK APIs

• Durable function -> resonate.register("name", function* ...).
• Local invocation -> ctx.run / ctx.beginRun.
• Remote invocation -> ctx.rpc / ctx.beginRpc with target options.
• External promise -> ctx.promise() and resonate.promises.resolve/reject/cancel.
• Call graph -> inspect with resonate tree <id>.
• Root promise -> the top-level invocation ID passed to run or rpc.

Coordination Semantics (Spec -> SDK)

Eventual resumption

Spec: caller awaits a promise that is not yet resolved.

SDK:

• Caller yields ctx.rpc(...) or ctx.beginRpc(...).
• Resonate Server stores promise and registers resume callback.
• Caller resumes after the promise is resolved.

function* parent(ctx: Context, id: string) {
  const child = yield* ctx.beginRpc(
    "child",
    id,
    ctx.options({ target: "poll://any@workers" })
  );
  const result = yield* child; // eventual resumption
  return result;
}

Immediate resumption

Spec: caller awaits a promise already resolved.

SDK:

• On replay, yield* ctx.run(...) returns stored result immediately.
• No new execution is spawned for the already-completed promise.

function* replayed(ctx: Context, id: string) {
  const cached = yield* ctx.run(step, id); // returns stored value
  return cached;
}

Recovery Semantics (Spec -> SDK)

Spec: interruption-transparent execution.

SDK:

• Each yield* checkpoint writes a durable promise.
• On crash, Resonate replays the function and reuses stored results.
• Side effects must be wrapped in durable calls to avoid duplication.

function* durable(ctx: Context, id: string) {
  const v1 = yield* ctx.run(step1, id);
  const v2 = yield* ctx.run(step2, v1);
  return v2;
}

Determinism Requirements (Spec -> SDK)

Spec: execution should be equivalent with or without interruptions.

SDK:

• Do not call Date.now(), Math.random(), or crypto.randomUUID() directly inside durable generator code — these return different values on replay, breaking equivalence.
• SDK-sanctioned pattern: pass timestamps and random seeds as arguments from the caller into the workflow, then thread them through as ordinary parameters. The value is fixed at invocation time and stable across replays.
• Ensure all return values are serializable.

// ✅ CORRECT — timestamp fixed at call site, stable on replay
await resonate.run("report/2024-01-15", generateReport, {
  asOf: Date.now(),       // captured once in the ephemeral world
  seed: Math.random(),    // ditto
});
function* generateReport(ctx: Context, { asOf, seed }: ReportInput) {
  // asOf and seed are ordinary parameters — same value on every replay
  const data = yield* ctx.run(fetchData, asOf);
  return data;
}

Idempotency and Promise IDs

Spec: durable promises deduplicate re-invocation.

SDK:

• Top-level invocation ID is the idempotency key.
• Reusing the same ID returns cached results.
• Generate new IDs for a fresh execution.

await resonate.run("order/123", processOrder, "123");
await resonate.run("order/123", processOrder, "123"); // returns cached
await resonate.run("order/124", processOrder, "124"); // new execution

Local vs Remote Execution Reasoning

Spec: locality defines whether an invocation stays in-process or crosses processes.

SDK:

• ctx.run stays local.
• ctx.rpc crosses to another process group and resumes when resolved.

function* workflow(ctx: Context, input: string) {
  const local = yield* ctx.run(stepLocal, input);
  const remote = yield* ctx.rpc(
    "stepRemote",
    local,
    ctx.options({ target: "poll://any@workers" })
  );
  return remote;
}

Message Passing and Addressing

Spec: messages may be sent to a process or a group.

SDK:

• Unicast: use a specific poll://id@group target.
• Anycast: use poll://any@group to let the server route.

const result = yield* ctx.rpc(
  "task",
  data,
  ctx.options({ target: "poll://any@workers" })
);

Advanced Reasoning Checklist

• Is each side effect behind a durable step (ctx.run or ctx.rpc)?
• Are all durable return values serializable?
• Are promise IDs stable and meaningful?
• Does the target group match the worker group?
• Are retries bounded with timeouts where appropriate?
• Is concurrency structured (fork then join)?

When to Hand Off

• Use resonate-basic-durable-world-usage-typescript for SDK usage patterns and hands-on TS authoring.
• Use resonate-basic-debugging-typescript for runtime diagnosis.