yieldstar 0.4.6 → 0.6.0

package/dist/internal/effect-call.d.ts

@@ -0,0 +1,60 @@
+import type { Logger } from "pino";
+import { StepResponse, type DurableObject, type DurableValue, type EffectClient } from "@yieldstar/core";
+/** What `lookup` reports about an effect ID (RFC 005). */
+export type EffectLookup<T> = {
+    status: "settled";
+    result: T;
+} | {
+    status: "not-found";
+} | {
+    status: "unknown";
+};
+/** The effect request a step yields once its descriptor is valid. */
+export type EffectCallRequest = {
+    stepKey: string;
+    effectId: string;
+    operation: string;
+    input: DurableObject;
+    retryIn: number;
+    lookup(effectId: string): Promise<unknown>;
+    perform(effectId: string): Promise<unknown>;
+};
+/**
+ * - `settled`: the effect's result, which the step records.
+ * - `rejected`: the effect exists with a different operation or input.
+ * - `suspended`: the step watches the effect and is due again at `wakeAt`.
+ */
+export type EffectCallOutcome = {
+    status: "settled";
+    result: DurableValue;
+} | {
+    status: "rejected";
+    code: "EFFECT_REQUEST_MISMATCH";
+} | {
+    status: "suspended";
+    wakeAt: number;
+};
+/**
+ * Yielded by `step.effect`. The driver runs the effect with
+ * `executeEffectCall` and resumes the step with its outcome.
+ */
+export declare class StepEffectCall extends StepResponse {
+    static type: string;
+    readonly type = "effect-call";
+    readonly request: EffectCallRequest;
+    constructor(request: EffectCallRequest);
+}
+/**
+ * Runs an effect step's protocol against the runtime's `EffectClient`. Every
+ * failure that must not be recorded rejects with an `InfrastructureError`
+ * whose cause is an `EffectDeliveryError`, so the delivery is retried.
+ */
+export declare function executeEffectCall(request: EffectCallRequest, context: {
+    effects: EffectClient;
+    executionId: string;
+    clock: () => number;
+    /** Checked before every callback, so a lost lease makes no external call. */
+    assertLease: () => void;
+    logger: Logger;
+}): Promise<EffectCallOutcome>;
+//# sourceMappingURL=effect-call.d.ts.map

package/dist/internal/effect-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-call.d.ts","sourceRoot":"","sources":["../../src/internal/effect-call.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAIL,YAAY,EAEZ,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AAEzB,0DAA0D;AAC1D,MAAM,MAAM,YAAY,CAAC,CAAC,IACtB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GAChC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAE1B,qEAAqE;AACrE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,yBAAyB,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5C;;;GAGG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,MAAM,CAAC,IAAI,SAAiB;IAC5B,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;gBAExB,OAAO,EAAE,iBAAiB;CAIvC;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE;IACP,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,iBAAiB,CAAC,CAqH5B"}

package/dist/internal/runtime-call.d.ts

@@ -0,0 +1,39 @@
+import { StepResponse, type ExecutionClient, type StoreClient } from "@yieldstar/core";
+export type RuntimeClients = {
+    stores: StoreClient;
+    executions: ExecutionClient;
+};
+export type RuntimeCallResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * Yielded by a step that needs a runtime client. Steps never call runtime
+ * clients themselves: the driver makes the call outside workflow code and
+ * resumes the step with a `RuntimeCallResult`. Only failures that belong to
+ * workflow code (see `isWorkflowFacingError`) resume the step; any other
+ * failure is an infrastructure error and ends the delivery without an outcome.
+ */
+export declare class StepRuntimeCall<T = unknown> extends StepResponse {
+    static type: string;
+    readonly type = "runtime-call";
+    readonly call: (clients: RuntimeClients) => Promise<T>;
+    constructor(call: (clients: RuntimeClients) => Promise<T>);
+}
+/** Marks an error thrown by a workflow-supplied callback run by a client. */
+export declare class StepCallbackError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Wraps a workflow-supplied callback (updater, selector, claim, initial state)
+ * that a runtime client will run, so its errors reach workflow code rather
+ * than being mistaken for infrastructure errors.
+ */
+export declare function workflowCallback<A extends unknown[], R>(fn: (...args: A) => R, assertResult?: (result: R) => void): (...args: A) => R;
+export declare function executeRuntimeCall<T>(request: StepRuntimeCall<T>, clients: RuntimeClients): Promise<RuntimeCallResult<T>>;
+/** Runs a heap operation, tagging its failure as an infrastructure error. */
+export declare function infrastructure<T>(fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=runtime-call.d.ts.map

package/dist/internal/runtime-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-call.d.ts","sourceRoot":"","sources":["../../src/internal/runtime-call.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,YAAY,EAGZ,KAAK,eAAe,EACpB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAC3B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAElC;;;;;;GAMG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,YAAY;IAC5D,MAAM,CAAC,IAAI,SAAkB;IAC7B,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;gBAE3C,IAAI,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC;CAI1D;AAED,6EAA6E;AAC7E,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,OAAO;CAI3B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,EACrD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACrB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GACjC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAUnB;AAED,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAS/B;AAWD,6EAA6E;AAC7E,wBAAsB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxE"}

package/dist/internal/serialise.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialise.d.ts","sourceRoot":"","sources":["../../src/internal/serialise.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,YAAY,EAEb,MAAM,iBAAiB,CAAC;AAGzB,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAShE;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAuBxE"}
+{"version":3,"file":"serialise.d.ts","sourceRoot":"","sources":["../../src/internal/serialise.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,YAAY,EAIb,MAAM,iBAAiB,CAAC;AAGzB,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAShE;AAED,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAyBxE"}

package/dist/internal/step-record.d.ts

@@ -0,0 +1,13 @@
+import { StepResponse } from "@yieldstar/core";
+/**
+ * Encodes a step response for its step record, and returns the response that
+ * workflow code must see: the record decoded again, so that a first run sees
+ * exactly what replay reads. A result the codec rejects is recorded as a step
+ * error with `WorkflowValueError` (`INVALID_STEP_VALUE`).
+ */
+export declare function encodeStepRecord(response: StepResponse, stepKey: string): {
+    json: string;
+    response: StepResponse;
+};
+export declare function decodeStepRecord(json: string): StepResponse;
+//# sourceMappingURL=step-record.d.ts.map

package/dist/internal/step-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-record.d.ts","sourceRoot":"","sources":["../../src/internal/step-record.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,YAAY,EAOb,MAAM,iBAAiB,CAAC;AAEzB;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,CAG1C;AA8CD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAmC3D"}

package/dist/internal/step-runner.d.ts

@@ -1,4 +1,7 @@
-import { StepResponse, StepError, StepResult } from "@yieldstar/core";
+import { defineStore, type Draft, type DurableObject, type DurableStoreSchema, type IfDurable, type StandardSchemaV1, StepResponse, StepError, StepResult, type StoreDefinition, type StoreDeleteFromResult, type StoreKey, type StoreSelector, type StoreSnapshot, type StoreState, type StoreUpdateFromResult, type StoreUpdateResult, type Durable } from "@yieldstar/core";
+import type { WorkflowEvent } from "@yieldstar/core";
+import { type EffectLookup } from "./effect-call";
+export type { EffectLookup };
 /**
  * @description A library of step generators, each of which:
  * @yields a StepResponse to workflow consumers
@@ -7,16 +10,98 @@ import { StepResponse, StepError, StepResult } from "@yieldstar/core";
  * @throws any error caught when running the user-defined function,
  * once retries have been exhausted, or if there are no retry semantics
  */
-export declare const stepRunner: {
+export { defineStore };
+export type WorkflowStore<T> = {
+    readonly definition: StoreDefinition<any>;
+    readonly id: string;
+    readonly key: StoreKey;
+    get(key?: string): AsyncGenerator<StepResponse, StoreSnapshot<T>>;
+    select<R>(key: string, selector: StoreSelector<T, R> & DurableSelector<T, R>): AsyncGenerator<StepResponse, R>;
+    update(key: string, updater: (draft: Draft<T>) => void | T): AsyncGenerator<StepResponse, StoreUpdateResult<T>>;
+    updateFrom(key: string, snapshot: StoreSnapshot<T>, updater: (draft: Draft<T>) => void | T): AsyncGenerator<StepResponse, StoreUpdateFromResult<T>>;
+    deleteFrom(key: string, snapshot: StoreSnapshot<T>): AsyncGenerator<StepResponse, StoreDeleteFromResult>;
+    when<R>(selector: StoreSelector<T, R | undefined | null | false> & DurableMatchSelector<T, R>): AsyncGenerator<StepResponse, NonNullable<R>>;
+    when<R>(key: string, selector: StoreSelector<T, R | undefined | null | false> & DurableMatchSelector<T, R>): AsyncGenerator<StepResponse, NonNullable<R>>;
+    take<R>(key: string, selector: StoreSelector<T, R | undefined | null | false> & DurableMatchSelector<T, R>, claim: (draft: Draft<T>, selected: NonNullable<R>) => void): AsyncGenerator<StepResponse, NonNullable<R>>;
+};
+/** A store selector whose result, which the step records, is durable. */
+type DurableSelector<T, R> = IfDurable<R, StoreSelector<T, Durable<R>>>;
+/**
+ * A `when` or `take` selector whose match is durable. `false` is excluded
+ * before the check so that `R` is inferred as it would be without it.
+ */
+type DurableMatchSelector<T, R> = IfDurable<Exclude<R, false>, StoreSelector<T, Durable<Exclude<R, false>> | undefined | null | false>>;
+export type StepRunner = ReturnType<typeof createStepRunner>;
+export declare function createStepRunner(params: {
+    event: WorkflowEvent;
+    clock: () => number;
+}): {
     run: typeof run;
-    delay: typeof delay;
+    delay: {
+        (retryInterval: number): any;
+        (key: string, retryInterval: number): any;
+    };
     poll: typeof poll;
+    store: <Schema extends StandardSchemaV1>(definition: StoreDefinition<Schema> & {
+        schema: DurableStoreSchema<Schema>;
+    }, params?: {
+        id?: string;
+    }) => WorkflowStore<StoreState<Schema>>;
+    start: <Params extends Record<string, any>>(stepKey: string, target: {
+        workflowId: string;
+        params?: Params & Durable<Params>;
+    }) => AsyncGenerator<StepResponse, {
+        executionId: string;
+    }, StepResult | StepError>;
+    effect: <T, Input extends Record<string, any> = DurableObject>(stepKey: string, descriptor: EffectDescriptor<T, Input> & DurableEffectResult<T>) => AsyncGenerator<StepResponse, T, StepResult | StepError>;
+};
+/**
+ * Describes one external operation for `step.effect`. `effectId` names the
+ * operation in the external system, so every caller that means it, in any
+ * execution or runtime, uses the same ID, and no caller reuses it for another
+ * operation. The external system must guarantee that repeated `perform` calls
+ * for one ID make one operation with one result, that `not-found` proves no
+ * call exists or can still finish, and that `settled` never changes.
+ */
+export type EffectDescriptor<T, Input = DurableObject> = {
+    effectId: string;
+    /** Names the version of the behaviour of `input`, `lookup` and `perform`. */
+    operation: string;
+    input: Input & Durable<Input>;
+    /** Milliseconds before an uncertain outcome is looked up again. */
+    retryIn: number;
+    /** Reports what the external system knows about `effectId`. */
+    lookup(effectId: string): Promise<EffectLookup<T>>;
+    /** Performs the operation under `effectId`. */
+    perform(effectId: string): Promise<T>;
 };
-export type StepRunner = typeof stepRunner;
-declare function run<T extends any>(fn: () => T | Promise<T>): AsyncGenerator<StepResponse, T, StepResult | StepError>;
-declare function run<T extends any>(key: string, fn: () => T | Promise<T>): AsyncGenerator<StepResponse, T, StepResult | StepError>;
-declare function delay(retryInterval: number): any;
-declare function delay(key: string, retryInterval: number): any;
+/**
+ * Checks the effect's result type without taking part in its inference. A
+ * `perform` that resolves with nothing settles the effect with `undefined`.
+ */
+type DurableEffectResult<T> = [T] extends [void] ? unknown : IfDurable<T, {
+    perform(effectId: string): Promise<Durable<T>>;
+}>;
+export type StepRunOptions<S extends StandardSchemaV1> = {
+    /**
+     * Validates the step's decoded value, on the first run and on every
+     * replay; the step returns the schema's output. The step function must
+     * return the schema's input as a durable value.
+     */
+    schema: S;
+};
+/**
+ * A step function whose result, or the value its promise resolves to, is a
+ * durable value. Checking the whole function type keeps the result's type as
+ * TypeScript infers it, and names the offending property in the error.
+ */
+export type DurableStepFn<F> = F extends () => infer R ? () => R extends PromiseLike<infer U> ? PromiseLike<DurableUnion<U>> : DurableUnion<R> : never;
+type DurableUnion<T> = T extends unknown ? Durable<T> : never;
+declare function run<F extends () => unknown>(fn: F & DurableStepFn<F>): AsyncGenerator<StepResponse, Awaited<ReturnType<F>>, StepResponse>;
+declare function run<F extends () => unknown>(key: string, fn: F & DurableStepFn<F>): AsyncGenerator<StepResponse, Awaited<ReturnType<F>>, StepResponse>;
+declare function run<S extends StandardSchemaV1>(fn: () => StepSchemaInput<S> | PromiseLike<StepSchemaInput<S>>, options: StepRunOptions<S>): AsyncGenerator<StepResponse, StandardSchemaV1.InferOutput<S>, StepResponse>;
+declare function run<S extends StandardSchemaV1>(key: string, fn: () => StepSchemaInput<S> | PromiseLike<StepSchemaInput<S>>, options: StepRunOptions<S>): AsyncGenerator<StepResponse, StandardSchemaV1.InferOutput<S>, StepResponse>;
+type StepSchemaInput<S extends StandardSchemaV1> = Durable<StandardSchemaV1.InferInput<S>>;
 type PollOpts = {
     maxAttempts: number;
     retryInterval: number;
@@ -24,5 +109,4 @@ type PollOpts = {
 type PollPredicate = () => boolean | Promise<boolean>;
 declare function poll(opts: PollOpts, predicate: PollPredicate): any;
 declare function poll(key: string, opts: PollOpts, predicate: PollPredicate): any;
-export {};
 //# sourceMappingURL=step-runner.d.ts.map

package/dist/internal/step-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-runner.d.ts","sourceRoot":"","sources":["../../src/internal/step-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EAEZ,SAAS,EACT,UAAU,EAGX,MAAM,iBAAiB,CAAC;AAIzB;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU;;;;CAAuB,CAAC;AAE/C,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC;AAE3C,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AAE3D,iBAAS,GAAG,CAAC,CAAC,SAAS,GAAG,EACxB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,cAAc,CAAC,YAAY,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC,CAAC;AAiD3D,iBAAS,KAAK,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AAC3C,iBAAS,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;AA6BxD,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/D,KAAK,aAAa,GAAG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtD,iBAAS,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC;AAC7D,iBAAS,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,GAAG,GAAG,CAAC"}
+{"version":3,"file":"step-runner.d.ts","sourceRoot":"","sources":["../../src/internal/step-runner.ts"],"names":[],"mappings":"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"}

package/dist/internal/utils.d.ts

@@ -1,3 +1,14 @@
 export declare const isIterable: <T>(i: T | Iterable<T>) => i is Iterable<T>;
+/**
+ * Derives a replay-stable cache key from the call site of a keyless step.
+ *
+ * IMPORTANT: `stepFn` must be the synchronously-executing function that the
+ * user called directly (e.g. the `step.run` wrapper) – NOT an async generator
+ * body. Async generator bodies don't run until the first `.next()`, by which
+ * point the user's frame is no longer on the stack. `Error.captureStackTrace`
+ * omits every frame above (and including) `stepFn`, so the first captured
+ * frame is the user's call site (file:line:column), which is deterministic
+ * across executions of the same workflow code.
+ */
 export declare function getCallSiteHash(stepFn: Function): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/internal/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAIjE,CAAC;AAGF,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,UAe/C"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/internal/utils.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAIjE,CAAC;AAGF;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAkBxD"}

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "yieldstar",
-  "version": "0.4.6",
+  "version": "0.6.0",
   "license": "MIT",
   "author": "Daniel Grant",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/notationlabs/yieldstar.git",
+    "directory": "packages/yieldstar"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
     "nanoid": "^5.1.5",
     "pino": "^9.9.0",
-    "serialize-error": "^11.0.3",
-    "@yieldstar/core": "0.4.6"
+    "@yieldstar/core": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.18.0"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outfile dist/index.js --target bun --packages=external"
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --packages=external"
   }
 }

package/src/exports/errors.ts

@@ -1,3 +1,5 @@
+import { registerErrorClass } from "@yieldstar/core";
+
 export class RetryableError extends Error {
   maxAttempts: number;
   retryInterval: number;
@@ -11,3 +13,5 @@ export class RetryableError extends Error {
     this.retryInterval = opts.retryInterval;
   }
 }
+
+registerErrorClass("RetryableError", RetryableError);

package/src/exports/sdk-http.ts

@@ -2,12 +2,13 @@ import type {
   EventParamsOf,
   WorkflowRouter,
   TriggerEvent,
-  ExecutionEvent,
   WorkflowGeneratorReturnType,
+  ExecutionAdmissionErrorCode,
+} from "@yieldstar/core";
+import {
+  ExecutionAdmissionError,
+  durableValueCodec,
 } from "@yieldstar/core";
-import { nanoid } from "nanoid";
-import { deserializeError } from "serialize-error";
-import { errorWithOriginalStack } from "@yieldstar/core";
 
 type TriggerAck = {
   executionId: string;
@@ -19,60 +20,92 @@ type TriggerResponse<W extends WorkflowRouter, K extends string & keyof W> = {
   waitForResult: () => Promise<WorkflowGeneratorReturnType<W[K]>>;
 };
 
+const admissionErrorCodes: ExecutionAdmissionErrorCode[] = [
+  "EXECUTION_ID_CONFLICT",
+  "INVALID_EXECUTION_EVENT",
+];
+
 export function createHttpSdkFactory<W extends WorkflowRouter>() {
   return (params: {
     url: string;
     fetchOptions?: Omit<RequestInit, "body" | "method">;
   }) => {
     return {
+      /**
+       * Admits an execution through the trigger route. When `executionId` is
+       * omitted the runtime chooses one, which the response carries. The body
+       * is encoded with the durable value codec, so params and context reach
+       * the runtime unchanged.
+       * @throws {ExecutionAdmissionError} on `409 Conflict` or an invalid event,
+       * including params or context the codec rejects, before any request
+       */
       async trigger<K extends string & keyof W>(
         event: TriggerEvent<K, EventParamsOf<W[K]>>
       ): Promise<TriggerResponse<W, K>> {
-        const executionEvent: ExecutionEvent = {
-          executionId: event?.executionId ?? nanoid(),
-          workflowId: event?.workflowId as string,
-          params: event?.params,
-          context: event?.context,
-        };
-
+        const request: Record<string, unknown> = { workflowId: event?.workflowId };
+        if (event?.executionId !== undefined) request.executionId = event.executionId;
+        if (event && "params" in event) request.params = event.params;
+        if (event?.context !== undefined) request.context = event.context;
+        const encoding = durableValueCodec.encode(request);
+        if (encoding.status === "invalid") {
+          throw new ExecutionAdmissionError(
+            "INVALID_EXECUTION_EVENT",
+            `Event cannot be stored without loss: ${encoding.message}`
+          );
+        }
         const res = await fetch(`${params.url}/trigger`, {
           ...params.fetchOptions,
           method: "POST",
-          body: JSON.stringify(executionEvent),
+          headers: { "content-type": "application/json" },
+          body: encoding.canonical,
         });
 
         if (res.ok) {
+          const ack = (await res.json()) as TriggerAck;
           return {
-            executionId: executionEvent.executionId,
-            ack: () => res.json() as Promise<TriggerAck>,
-            waitForResult: () =>
-              this.waitForResult<K>({
-                executionId: executionEvent.executionId,
-              }),
+            executionId: ack.executionId,
+            ack: async () => ack,
+            waitForResult: () => this.waitForResult<K>(ack),
           };
-        } else {
-          throw res.statusText;
         }
+
+        const body = (await res.json().catch(() => undefined)) as
+          | { code?: ExecutionAdmissionErrorCode; message?: string }
+          | undefined;
+        if (body?.code && admissionErrorCodes.includes(body.code)) {
+          throw new ExecutionAdmissionError(body.code, body.message ?? res.statusText);
+        }
+        throw res.statusText;
       },
       async waitForResult<K extends string & keyof W>(
         ack: TriggerAck
       ): Promise<WorkflowGeneratorReturnType<W[K]>> {
-        // todo: set up subscription first (maybe just use ws)
         const res = await fetch(`${params.url}/events`, {
           method: "POST",
           body: JSON.stringify({ executionId: ack.executionId }),
           ...params.fetchOptions,
         });
 
+        if (res.status !== 500 && !res.ok) {
+          throw res.statusText;
+        }
+
+        const decoding = durableValueCodec.decode(await res.text());
+        if (decoding.status === "invalid") {
+          throw new Error(`Invalid workflow outcome: ${decoding.message}`);
+        }
+
         if (res.status === 500) {
-          const error = await res.json();
-          throw errorWithOriginalStack(
-            deserializeError(error),
-            this.waitForResult
-          );
+          const error =
+            decoding.value instanceof Error
+              ? decoding.value
+              : new Error(String(decoding.value));
+          // Thrown as revived, so it keeps its registered class and the
+          // stack recorded where it was first thrown.
+          throw error;
         }
 
-        return res.json() as Promise<WorkflowGeneratorReturnType<W[K]>>;
+        return decoding.value as WorkflowGeneratorReturnType<W[K]>;
       },
     };
   };

package/src/exports/sdk-local.ts

@@ -1,43 +1,69 @@
 import type {
   EventParamsOf,
+  ExecutionClient,
   WorkflowRouter,
   WorkflowInvoker,
   TriggerEvent,
-  ExecutionEvent,
   WorkflowGeneratorReturnType,
 } from "@yieldstar/core";
-import { nanoid } from "nanoid";
+import {
+  ExecutionAdmissionError,
+  waitForExecutionOutcome,
+} from "@yieldstar/core";
 
 type TriggerAck = {
   executionId: string;
 };
 
 export function createLocalSdk<W extends WorkflowRouter>(
-  invoker: WorkflowInvoker
+  runtime: { executions: ExecutionClient },
+  options?: {
+    /** Lets `triggerAndWait` settle as soon as the dispatcher acknowledges. */
+    invoker?: WorkflowInvoker;
+    /** Milliseconds between reads of the execution record. @default 25 */
+    pollInterval?: number;
+  }
 ) {
+  const { executions } = runtime;
+
   return {
+    /**
+     * Admits an execution and resolves once admission commits. A dispatcher
+     * delivers it; this does not wait for a worker to start.
+     * @throws {ExecutionAdmissionError} when the ID is already in use or the
+     * event cannot be stored without loss
+     */
     async trigger<K extends string & keyof W>(
       event: TriggerEvent<K, EventParamsOf<W[K]>>
     ): Promise<TriggerAck> {
-      const executionEvent: ExecutionEvent = {
-        executionId: event.executionId ?? nanoid(),
+      const admission = await executions.admit({
+        executionId: event.executionId,
         workflowId: event.workflowId,
         params: event.params,
-      };
-      await invoker.execute(executionEvent);
-      return { executionId: executionEvent.executionId };
+        context: new Map(Object.entries(event.context ?? {})),
+      });
+      if (admission.status === "rejected") {
+        throw new ExecutionAdmissionError(admission.code, admission.message);
+      }
+      return { executionId: admission.executionId };
     },
+    /**
+     * Admits an execution and waits for its record to reach a terminal
+     * status. Resolves with the result, or rejects with the recorded error.
+     */
     async triggerAndWait<K extends string & keyof W>(
       event: TriggerEvent<K, EventParamsOf<W[K]>>
     ): Promise<WorkflowGeneratorReturnType<W[K]>> {
-      const executionId = event.executionId ?? nanoid();
-      const workflowCompletePromise = new Promise((resolve) => {
-        invoker.workflowEndEmitter.once(executionId, resolve);
+      const { executionId } = await this.trigger(event);
+      const outcome = await waitForExecutionOutcome(executions, executionId, {
+        emitter: options?.invoker?.workflowEndEmitter,
+        pollInterval: options?.pollInterval,
       });
-      await this.trigger({ ...event, executionId });
-      return workflowCompletePromise as Promise<
-        WorkflowGeneratorReturnType<W[K]>
-      >;
+      if (!outcome) {
+        throw new Error(`Execution "${executionId}" has no record`);
+      }
+      if (outcome.status === "failed") throw outcome.error;
+      return outcome.result as WorkflowGeneratorReturnType<W[K]>;
     },
   };
 }