@resonatehq/sdk 0.11.4 → 0.11.5

package/dist/src/async/context.d.ts

@@ -17,11 +17,12 @@ export type Return<F> = F extends (...args: any[]) => infer R ? Awaited<R> : nev
 export interface Info {
     readonly id: string;
     readonly parentId: string;
+    /** The lineage origin: everything before the first `:` of every id in this
+     * workflow, set at the top (resonate.run/rpc) and carried through the
+     * resonate:origin tag unchanged forever — including into detached children,
+     * which mint `${originId}:d${hash}` off it. Also the anchor every descendant
+     * id extends, so it doubles as the id-generation root. */
     readonly originId: string;
-    /** The id-generation prefix (resonate:prefix). Set once at the top and
-     * propagated down unchanged — through every child AND across detached
-     * re-roots — so recursive detached ids stay bounded. */
-    readonly prefixId: string;
     readonly branchId: string;
     readonly timeoutAt: number;
     readonly attempt: number;
@@ -149,7 +150,6 @@ export declare class DurablePromise<T> implements Promise<T> {
 interface AsyncContextConfig {
     id: string;
     oId?: string;
-    prId?: string;
     bId?: string;
     pId?: string;
     func: string;
@@ -164,7 +164,6 @@ interface AsyncContextConfig {
 export declare class AsyncContext implements Context {
     readonly id: string;
     readonly originId: string;
-    readonly prefixId: string;
     readonly branchId: string;
     readonly parentId: string;
     readonly func: string;

package/dist/src/async/context.js

@@ -1,4 +1,5 @@
 import exceptions from "../exceptions.js";
+import { joinId } from "../ids.js";
 import { delay, randomUUID } from "../platform.js";
 import { Never } from "../retries.js";
 import * as util from "../util.js";
@@ -37,7 +38,6 @@ export class DurablePromise {
 export class AsyncContext {
     id;
     originId;
-    prefixId;
     branchId;
     parentId;
     func;
@@ -69,7 +69,6 @@ export class AsyncContext {
     constructor(cfg, effects, trace) {
         this.id = cfg.id;
         this.originId = cfg.oId ?? cfg.id;
-        this.prefixId = cfg.prId ?? cfg.id;
         this.branchId = cfg.bId ?? cfg.id;
         this.parentId = cfg.pId ?? cfg.id;
         this.func = cfg.func;
@@ -118,7 +117,6 @@ export class AsyncContext {
         return new AsyncContext({
             id: cfg.id,
             oId: this.originId,
-            prId: this.prefixId,
             bId: this.branchId,
             pId: this.id,
             func: cfg.func,
@@ -262,15 +260,16 @@ export class AsyncContext {
             return this.track("", errOutcome);
         }
         const idChanged = opts.id !== undefined;
-        // Detached ids are minted off the fixed id-generation prefix (NOT the grown
-        // id or the diverging origin), so recursive detached stays bounded at one
-        // segment past the prefix. Mirrors the generator engine (src/context.ts).
-        const id = idChanged ? opts.id : util.detachedId(this.prefixId, this.seqid());
+        // Detached ids are minted off the lineage origin (`${origin}:d${hash}`,
+        // one segment past it), so recursive detached stays bounded instead of
+        // growing a segment per level. Mirrors the generator engine
+        // (src/context.ts).
+        const id = idChanged ? opts.id : util.detachedId(this.originId, this.seqid());
         this.seq++;
         const func = registered ? registered.name : funcOrName;
         const version = registered ? registered.version : opts.version || 1;
         const data = { func, args: argu, retry: opts.retryPolicy?.encode(), version };
-        const createReq = this.detachedCreateReq({ id, data, opts });
+        const createReq = this.detachedCreateReq({ id, data, opts, breaksLineage: idChanged });
         const slot = this.claimCreateSlot();
         // Fire-and-forget: the parent waits only for the durable CREATE to land
         // (so the spawn survives), never for the detached workflow's result, and
@@ -399,12 +398,12 @@ export class AsyncContext {
             data,
             tags: {
                 "resonate:scope": "local",
-                "resonate:branch": this.branchId,
-                "resonate:parent": this.id,
+                // An explicit-id child (breaksLineage) starts a fresh self-anchored
+                // lineage: the server requires an id to extend its declared branch /
+                // parent / origin, which only the id itself satisfies.
+                "resonate:branch": breaksLineage ? id : this.branchId,
+                "resonate:parent": breaksLineage ? id : this.id,
                 "resonate:origin": breaksLineage ? id : this.originId,
-                // Prefix is set at the top and propagates down unchanged forever,
-                // independent of origin (which detached/explicit-id may break).
-                "resonate:prefix": this.prefixId,
                 ...opts.tags,
             },
         });
@@ -418,18 +417,23 @@ export class AsyncContext {
                 "resonate:scope": "global",
                 "resonate:target": opts.target,
                 "resonate:branch": id,
-                "resonate:parent": this.id,
+                "resonate:parent": breaksLineage ? id : this.id,
                 "resonate:origin": breaksLineage ? id : this.originId,
-                // Prefix is set at the top and propagates down unchanged forever,
-                // independent of origin (which detached/explicit-id may break).
-                "resonate:prefix": this.prefixId,
                 ...opts.tags,
             },
         });
     }
-    // Detached: a globally-scoped promise with its own origin (lineage break) and
-    // an independent lifetime — its timeout is NOT clamped to the parent's.
-    detachedCreateReq({ id, data, opts }) {
+    // Detached: a globally-scoped promise with an independent lifetime — its
+    // timeout is NOT clamped to the parent's. The child keeps the *parent's*
+    // origin rather than re-rooting onto its own id: the server derives the
+    // origin as everything before the first `:` and requires every id in a
+    // lineage to start with `{origin}:`. Its id hangs off the origin
+    // (`${origin}:d${hash}`, bounding recursion), so the origin is also the
+    // resonate:parent it declares — a parent of the spawning context would be
+    // rejected. resonate:branch stays the child's own id: a detached child
+    // roots its own branch. An explicit opts.id still starts a fresh
+    // self-anchored lineage (breaksLineage).
+    detachedCreateReq({ id, data, opts, breaksLineage, }) {
         return this.createReq({
             id,
             timeoutAt: this.clock.now() + opts.timeout,
@@ -438,11 +442,8 @@ export class AsyncContext {
                 "resonate:scope": "global",
                 "resonate:target": opts.target,
                 "resonate:branch": id,
-                "resonate:parent": this.id,
-                "resonate:origin": id,
-                // Prefix carries forward unchanged across the detached re-root (origin
-                // breaks, prefix does not) — this is what keeps recursive ids bounded.
-                "resonate:prefix": this.prefixId,
+                "resonate:parent": breaksLineage ? id : this.originId,
+                "resonate:origin": breaksLineage ? id : this.originId,
                 ...opts.tags,
             },
         });
@@ -458,30 +459,38 @@ export class AsyncContext {
                 "resonate:branch": id,
                 "resonate:parent": this.id,
                 "resonate:origin": this.originId,
-                // Prefix is set at the top and propagates down unchanged forever.
-                "resonate:prefix": this.prefixId,
                 ...tags,
             },
         });
     }
     sleepCreateReq({ id, time }) {
+        // The timer is the promise's own deadline: resonate:timer makes the server
+        // settle it RESOLVED (rather than timed out) when the deadline arrives,
+        // which fires the callbacks every sleeper is suspended on. The
+        // resonate:target is what makes that deadline *happen*: the server only
+        // schedules timeouts for promises carrying an address, so a target-less
+        // timer would simply never fire. The flip side is that a target also
+        // spawns a task, dispatched immediately rather than at the wake; a timer
+        // names no function to run, so the worker that receives it drops it and
+        // lets the deadline do the waking (see AsyncCore.executeUntilBlocked).
         return this.createReq({
             id,
             timeoutAt: Math.min(time, this.timeoutAt),
             data: "",
             tags: {
                 "resonate:scope": "global",
+                "resonate:target": this.options().target,
                 "resonate:branch": id,
                 "resonate:parent": this.id,
                 "resonate:origin": this.originId,
-                // Prefix is set at the top and propagates down unchanged forever.
-                "resonate:prefix": this.prefixId,
                 "resonate:timer": "true",
             },
         });
     }
     seqid() {
-        return `${this.id}.${this.seq}`;
+        // A bare root joins its first lineage segment with ':', deeper segments
+        // join with '.' -- see ids.joinId.
+        return joinId(this.id, `${this.seq}`);
     }
 }
 // Map a settled durable promise record to an outcome.

package/dist/src/async/core.js

@@ -1,4 +1,5 @@
 import exceptions, { ResonateError } from "../exceptions.js";
+import { originOf } from "../ids.js";
 import { isRedirect, isSuccess } from "../network/types.js";
 import { randomUUID } from "../platform.js";
 import { Constant, Exponential, Linear, Never } from "../retries.js";
@@ -53,6 +54,37 @@ export class Core {
     }
     async executeUntilBlocked(task, rootPromise, preload) {
         util.assert(task.state === "acquired", `expected task state to be 'acquired', got '${task.state}'`);
+        // A resonate:timer promise is a durable sleep. It names no function to
+        // run; it only carries a task at all because the target that gets the
+        // server to *schedule* its deadline also spawns one.
+        if (rootPromise.tags["resonate:timer"] === "true") {
+            const collector = new TraceCollector();
+            if (rootPromise.state === "pending") {
+                // Not yet due: drop the task and let the deadline settle the promise,
+                // which is what wakes the sleepers. Dropping means exactly that: no
+                // fulfill (that would end the sleep early), no suspend (a task cannot
+                // await its own promise), and no release (the server re-dispatches a
+                // released task immediately, which would spin). The lease simply
+                // lapses; a re-delivery before the wake is dropped again, and one
+                // after it takes the settled branch below.
+                this.logger.debug({ component: "async-core", taskId: task.id, timeoutAt: rootPromise.timeoutAt }, "dropping not-yet-due timer task");
+                return { kind: "suspended", awaited: [], trace: collector.getTrace() };
+            }
+            // Settled: a durable sleep whose wake has passed. It carries no
+            // function/args, so it cannot go through the run driver; fulfill the
+            // task with the promise's settlement. (The server normally fulfills a
+            // timer's task itself when the deadline settles the promise, so this
+            // only catches a delivery already in flight at that moment.)
+            const status = {
+                kind: "done",
+                id: rootPromise.id,
+                state: rootPromise.state === "resolved" ? "resolved" : "rejected",
+                value: rootPromise.value?.data,
+                trace: collector.getTrace(),
+            };
+            await this.fulfillTask(task, rootPromise, status);
+            return status;
+        }
         const effects = util.buildEffects(this.send, this.codec, { id: task.id, version: task.version }, preload);
         try {
             const status = await this.executeUntilBlockedInner(rootPromise, effects);
@@ -96,7 +128,6 @@ export class Core {
         if (version !== 0)
             util.assert(version === registered.version, "versions must match");
         util.assert(func === registered.name, "names must match");
-        this.heartbeat.start();
         // One trace per pass (mirrors Computation.processGenerator); threaded into
         // the root context and propagated to every child via AsyncContext.child.
         const trace = new TraceCollector();
@@ -117,12 +148,13 @@ export class Core {
         // promise) — only the decoded retry policy applies.
         const outcome = await runWithRetry((attempt) => new AsyncContext({
             id: rootPromise.id,
-            oId: rootPromise.tags["resonate:origin"] ?? rootPromise.id,
-            // The id-generation prefix, propagated unchanged across re-roots (a
-            // detached child resets origin to its own id but carries prefix
-            // forward), so recursive detached ids stay bounded. Falls back to
-            // the id like oId.
-            prId: rootPromise.tags["resonate:prefix"] ?? rootPromise.id,
+            // Take the lineage origin from the promise's resonate:origin tag,
+            // which the dispatcher set: every id in the lineage is
+            // `{origin}:{lineage}`, so this is both the ancestry root and the
+            // anchor this workflow's own child ids extend. A tag-less promise
+            // falls back to deriving it from the id the same way the server
+            // does -- which for a genuine top-level root is the id itself.
+            oId: rootPromise.tags["resonate:origin"] ?? originOf(rootPromise.id),
             func: registered.func.name,
             clock: this.clock,
             registry: this.registry,
@@ -214,7 +246,14 @@ export class Core {
             });
         }
         const rootPromise = this.codec.decodePromise(res.data.promise);
-        return this.executeUntilBlocked(res.data.task, rootPromise, res.data.preload);
+        const acquiredTask = res.data.task;
+        this.heartbeat.start(acquiredTask);
+        try {
+            return await this.executeUntilBlocked(acquiredTask, rootPromise, res.data.preload);
+        }
+        finally {
+            this.heartbeat.stop(acquiredTask);
+        }
     }
 }
 // Validates the root promise's decoded `param.data` shape (copied from

package/dist/src/async/resonate.d.ts

@@ -27,7 +27,6 @@ export declare class Resonate {
     private clock;
     private pid;
     private ttl;
-    private idPrefix;
     private core;
     private codec;
     private network;
@@ -42,7 +41,7 @@ export declare class Resonate {
     private intervalId;
     readonly promises: Promises;
     readonly schedules: Schedules;
-    constructor({ url, group, pid, ttl, token, timeout, verbose, logLevel, logger, encryptor, network, prefix, }?: {
+    constructor({ url, group, pid, ttl, token, timeout, verbose, logLevel, logger, encryptor, network, }?: {
         url?: string;
         group?: string;
         pid?: string;
@@ -54,7 +53,6 @@ export declare class Resonate {
         logger?: Logger;
         encryptor?: Encryptor;
         network?: Network;
-        prefix?: string;
     });
     /** Registers an async function (leaf or workflow) for execution. */
     register<F extends AnyFunc>(name: string, func: F, options?: {

package/dist/src/async/resonate.js

@@ -3,6 +3,7 @@ import { Codec } from "../codec.js";
 import { NoopEncryptor } from "../encryptor.js";
 import exceptions, { ResonateTimeoutException } from "../exceptions.js";
 import { AsyncHeartbeat, NoopHeartbeat } from "../heartbeat.js";
+import { validateRootId } from "../ids.js";
 import { ConsoleLogger } from "../logger.js";
 import { HttpNetwork, PollMessageSource } from "../network/http.js";
 import { LocalNetwork } from "../network/local.js";
@@ -23,7 +24,6 @@ export class Resonate {
     clock;
     pid;
     ttl;
-    idPrefix;
     core;
     codec;
     network;
@@ -38,12 +38,10 @@ export class Resonate {
     intervalId;
     promises;
     schedules;
-    constructor({ url = undefined, group = "default", pid = undefined, ttl = 1 * util.MIN, token = undefined, timeout = undefined, verbose = false, logLevel = undefined, logger = undefined, encryptor = undefined, network = undefined, prefix = undefined, } = {}) {
+    constructor({ url = undefined, group = "default", pid = undefined, ttl = 1 * util.MIN, token = undefined, timeout = undefined, verbose = false, logLevel = undefined, logger = undefined, encryptor = undefined, network = undefined, } = {}) {
         this.clock = new WallClock();
         this.ttl = ttl;
         this.codec = new Codec(encryptor ?? new NoopEncryptor());
-        const resolvedPrefix = prefix ?? getEnv("RESONATE_PREFIX");
-        this.idPrefix = resolvedPrefix ? `${resolvedPrefix}:` : "";
         const resolvedLogLevel = logLevel ?? (verbose ? "debug" : "warn");
         this.logger = logger ?? new ConsoleLogger(resolvedLogLevel);
         this.subscribeEvery = util.MIN;
@@ -83,7 +81,7 @@ export class Resonate {
         }
         this.registry = new Registry();
         this.dependencies = new Map();
-        this.optsBuilder = new OptionsBuilder({ match: this.network.match.bind(this.network), idPrefix: this.idPrefix });
+        this.optsBuilder = new OptionsBuilder({ match: this.network.match.bind(this.network) });
         this.core = new Core({
             pid: this.pid,
             ttl: this.ttl,
@@ -146,7 +144,11 @@ export class Resonate {
         if (!registered) {
             throw exceptions.REGISTRY_FUNCTION_NOT_REGISTERED(typeof funcOrName === "string" ? funcOrName : funcOrName.name, opts.version);
         }
-        id = `${this.idPrefix}${id}`;
+        // Validated at the call site that named the workflow, rather than
+        // surfacing later as an opaque 400 from the server: the id becomes the
+        // origin of its whole lineage, so ':' is rejected outright ('.' is only
+        // read below the origin).
+        validateRootId(id);
         util.assert(registered.version > 0, "function version must be greater than zero");
         const { promise, task } = await this.taskCreate({
             kind: "task.create",
@@ -166,10 +168,10 @@ export class Resonate {
                         },
                         tags: {
                             ...opts.tags,
+                            // A genuine top-level root is its own lineage origin, so
+                            // origin == branch == parent == id here. Every descendant id
+                            // extends it as `{id}:{lineage}`.
                             "resonate:origin": id,
-                            // A genuine top-level root is its own lineage origin AND its own
-                            // id-generation prefix; the prefix then propagates down unchanged.
-                            "resonate:prefix": id,
                             "resonate:branch": id,
                             "resonate:parent": id,
                             "resonate:scope": "global",
@@ -192,7 +194,7 @@ export class Resonate {
         if (typeof funcOrName === "function" && !registered) {
             throw exceptions.REGISTRY_FUNCTION_NOT_REGISTERED(funcOrName.name, opts.version);
         }
-        id = `${this.idPrefix}${id}`;
+        validateRootId(id);
         const func = registered ? registered.name : funcOrName;
         const version = registered ? registered.version : opts.version || 1;
         const promise = await this.promiseCreate({
@@ -204,10 +206,10 @@ export class Resonate {
                 param: { data: { func, args, retry: opts.retryPolicy?.encode(), version }, headers: {} },
                 tags: {
                     ...opts.tags,
+                    // A genuine top-level root is its own lineage origin, so
+                    // origin == branch == parent == id here. Every descendant id
+                    // extends it as `{id}:{lineage}`.
                     "resonate:origin": id,
-                    // A genuine top-level root is its own lineage origin AND its own
-                    // id-generation prefix; the prefix then propagates down unchanged.
-                    "resonate:prefix": id,
                     "resonate:branch": id,
                     "resonate:parent": id,
                     "resonate:scope": "global",
@@ -228,7 +230,15 @@ export class Resonate {
             args,
             version: registered ? registered.version : opts.version || 1,
         });
-        await this.schedules.create(name, cron, `${this.idPrefix}{{.id}}.{{.timestamp}}`, opts.timeout, {
+        // Each firing creates a root promise named from this id, so the schedule
+        // name is bound by the same rules as a run/rpc id. The server stamps the
+        // *whole* templated id onto the fired promise's resonate:origin tag, so
+        // the template must join with a plain '-': a ':' would hide the timestamp
+        // below the origin, collapsing every firing onto one lineage. A '.' is
+        // fine now — it is only read below the origin — but '-' keeps the
+        // timestamp clearly distinct from any dots in the schedule name.
+        validateRootId(name);
+        await this.schedules.create(name, cron, "{{.id}}-{{.timestamp}}", opts.timeout, {
             promiseHeaders: headers,
             promiseData: data,
             promiseTags: { ...opts.tags, "resonate:target": opts.target },
@@ -239,7 +249,8 @@ export class Resonate {
     }
     /** Returns a handle to an existing durable promise by id. */
     async get(id) {
-        id = `${this.idPrefix}${id}`;
+        // get is a lookup, not a create: it takes any id, including a child's
+        // (e.g. "wf:1.2"), so it deliberately does NOT validate.
         const promise = await this.promiseGet({
             kind: "promise.get",
             head: { corrId: randomUUID(), version: util.VERSION },
@@ -292,6 +303,14 @@ export class Resonate {
             try {
                 const res = await this.send(req);
                 if (!isSuccess(res)) {
+                    // Listener registration can be retried for transient server pressure,
+                    // but semantic client errors cannot become valid by waiting.
+                    if (res.head.status !== 429 && res.head.status !== 500) {
+                        throw exceptions.SERVER_ERROR(res.data, false, {
+                            code: res.head.status,
+                            message: res.data,
+                        });
+                    }
                     await delay(retryDelay);
                     continue;
                 }
@@ -321,8 +340,12 @@ export class Resonate {
         };
         return {
             id: promise.id,
-            done: () => this.promiseRegisterListener(registerListenerReq).then((res) => res.state !== "pending"),
-            result: () => this.promiseRegisterListener(registerListenerReq).then((res) => this.subscribe(promise.id, res)),
+            done: () => promise.state === "pending"
+                ? this.promiseRegisterListener(registerListenerReq).then((res) => res.state !== "pending")
+                : Promise.resolve(true),
+            result: () => promise.state === "pending"
+                ? this.promiseRegisterListener(registerListenerReq).then((res) => this.subscribe(promise.id, res))
+                : this.subscribe(promise.id, promise),
         };
     }
     onMessage(msg) {

package/dist/src/computation.js

@@ -1,6 +1,7 @@
 import { InnerContext } from "./context.js";
 import { Coroutine } from "./coroutine.js";
 import exceptions from "./exceptions.js";
+import { originOf } from "./ids.js";
 import { Exponential, Never } from "./retries.js";
 import { TraceCollector } from "./trace.js";
 import * as util from "./util.js";
@@ -50,8 +51,6 @@ export class Computation {
         if (version !== 0)
             util.assert(version === registered.version, "versions must match");
         util.assert(func === registered.name, "names must match");
-        // start heartbeat
-        this.heartbeat.start();
         const retryCtor = retry ? this.retries.get(retry.type) : undefined;
         const retryPolicy = retryCtor
             ? new retryCtor(retry?.data)
@@ -63,11 +62,13 @@ export class Computation {
         }
         const ctxConfig = {
             id: this.id,
-            oId: rootPromise.tags["resonate:origin"] ?? this.id,
-            // The id-generation prefix, propagated unchanged across re-roots (a
-            // detached child resets origin to its own id but carries prefix forward),
-            // so recursive detached ids stay bounded. Falls back to the id like oId.
-            prId: rootPromise.tags["resonate:prefix"] ?? this.id,
+            // Take the lineage origin from the promise's resonate:origin tag, which
+            // the dispatcher set: every id in the lineage is `{origin}:{lineage}`,
+            // so this is both the ancestry root and the anchor this computation's
+            // own child ids extend. A tag-less promise falls back to deriving it
+            // from the id the same way the server does -- which for a genuine
+            // top-level root is the id itself.
+            oId: rootPromise.tags["resonate:origin"] ?? originOf(this.id),
             func: registered.func.name,
             clock: this.clock,
             registry: this.registry,

package/dist/src/context.d.ts

@@ -65,7 +65,6 @@ export declare class Future<T> implements Iterable<Future<T>> {
 export interface Context {
     readonly id: string;
     readonly originId: string;
-    readonly prefixId: string;
     readonly parentId: string;
     readonly branchId: string;
     readonly info: {
@@ -132,7 +131,6 @@ export declare class InnerContext implements Context {
     readonly retryPolicy: RetryPolicy;
     readonly nonRetryableErrors: Array<new (...args: any[]) => Error>;
     readonly originId: string;
-    readonly prefixId: string;
     readonly branchId: string;
     readonly parentId: string;
     readonly clock: Clock;
@@ -156,10 +154,9 @@ export declare class InnerContext implements Context {
         <F extends Func>(func: F, ...args: ParamsWithOptions<F>): RFI<Return<F>>;
         <T>(func: string, ...args: any[]): RFI<T>;
     };
-    constructor({ id, oId, prId, bId, pId, func, clock, registry, dependencies, optsBuilder, timeout, version, retryPolicy, nonRetryableErrors, }: {
+    constructor({ id, oId, bId, pId, func, clock, registry, dependencies, optsBuilder, timeout, version, retryPolicy, nonRetryableErrors, }: {
         id: string;
         oId?: string;
-        prId?: string;
         bId?: string;
         pId?: string;
         func: string;
@@ -256,11 +253,12 @@ export declare class InnerContext implements Context {
         opts: Options;
         breaksLineage: boolean;
     }): PromiseCreateReq;
-    remoteCreateReq({ id, data, opts, breaksLineage, maxTimeout, }: {
+    remoteCreateReq({ id, data, opts, breaksLineage, parent, maxTimeout, }: {
         id: string;
         data: any;
         opts: Options;
         breaksLineage: boolean;
+        parent?: string;
         maxTimeout?: number;
     }): PromiseCreateReq;
     latentCreateOpts({ id, timeout, data, tags, breaksLineage, }: {