@restatedev/restate-sdk-gen 1.14.2 → 1.14.4

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import * as restate from "@restatedev/restate-sdk";
+import { ContextDate, InvocationId, Opts, Rand, SendOpts, Target as Target$1 } from "@restatedev/restate-sdk";
 
 //#region src/operation.d.ts
 interface Operation<T> {
   [Symbol.iterator](): Iterator<unknown, T, unknown>;
 }
 declare function gen<T>(body: () => Generator<unknown, T, unknown>): Operation<T>;
-declare function spawn<T>(op: Operation<T>): Operation<Future<T>>;
 type SelectResult<B extends Record<string, Future<unknown>>> = { [K in keyof B]: {
   tag: K;
   future: B[K];
@@ -13,7 +13,10 @@ type SelectResult<B extends Record<string, Future<unknown>>> = { [K in keyof B]:
 declare function select<B extends Record<string, Future<unknown>>>(branches: B): Generator<unknown, SelectResult<B>, unknown>;
 //#endregion
 //#region src/future.d.ts
-interface Future<T> extends Operation<T> {}
+declare const futureBrand: unique symbol;
+interface Future<T> extends Operation<T> {
+  readonly [futureBrand]: unknown;
+}
 /** Extract the value type from a `Future<U>`; `never` for non-Futures. */
 type FutureValue<F> = F extends Future<infer U> ? U : never;
 /**
@@ -47,23 +50,421 @@ interface Channel<T> {
   readonly receive: Future<T>;
 }
 //#endregion
-//#region src/clients.d.ts
+//#region src/invocation-reference.d.ts
+/** Synchronous handle for resolving or rejecting a signal on a target invocation */
+interface SignalReference<T> {
+  resolve(payload?: T): void;
+  reject(reason: string | restate.TerminalError): void;
+}
 /**
- * Same shape as the SDK's `Client<M>` but each handler returns
- * `Future<O>` instead of `InvocationPromise<O>`. The mapped type
- * preserves the original argument list (including the trailing
- * `opts?: Opts<...>` parameter from the SDK).
+ * A typed reference to a running invocation. Returned by `sendClient()` methods
+ * (wrapped in `Future<InvocationReference<O>>`), or created via `invocation(id)`.
+ *
+ * - `attach()` returns a `Future<O>` with the serde from the original descriptor.
+ * - `signal()` sends a named signal to the target invocation.
+ * - `cancel()` cancels the target invocation.
  */
-type FluentClient<C> = { [K in keyof C]: C[K] extends ((...args: infer A) => restate.InvocationPromise<infer R>) ? (...args: A) => Future<R> : C[K] };
+interface InvocationReference<O$1 = unknown> {
+  readonly id: string;
+  attach(serde?: restate.Serde<O$1>): Future<O$1>;
+  signal<T = unknown>(name: string, serde?: restate.Serde<T>): SignalReference<T>;
+  cancel(): void;
+}
+//#endregion
+//#region ../restate-sdk-core/src/core.d.ts
+type ServiceDefinition<P$1 extends string, M> = {
+  name: P$1;
+};
+type Service<M> = M extends ServiceDefinition<string, infer S> ? S : M;
+type ServiceDefinitionFrom<M> = M extends ServiceDefinition<string, unknown> ? M : ServiceDefinition<string, M>;
+type VirtualObjectDefinition<P$1 extends string, M> = {
+  name: P$1;
+};
+type VirtualObject<M> = M extends VirtualObjectDefinition<string, infer O> ? O : M;
+type VirtualObjectDefinitionFrom<M> = M extends VirtualObjectDefinition<string, unknown> ? M : VirtualObjectDefinition<string, M>;
+type WorkflowDefinition<P$1 extends string, M> = {
+  name: P$1;
+};
+type Workflow<M> = M extends WorkflowDefinition<string, infer W> ? W : M;
+type WorkflowDefinitionFrom<M> = M extends WorkflowDefinition<string, unknown> ? M : WorkflowDefinition<string, M>;
+//#endregion
+//#region ../restate-sdk-core/src/standard_schema.d.ts
+/**
+ * This file is copy pasted as is from https://standardschema.dev/
+ */
+/** The Standard Typed interface. This is a base type extended by other specs. */
+interface StandardTypedV1<Input = unknown, Output$1 = Input> {
+  /** The Standard properties. */
+  readonly "~standard": StandardTypedV1.Props<Input, Output$1>;
+}
+declare namespace StandardTypedV1 {
+  /** The Standard Typed properties interface. */
+  interface Props<Input = unknown, Output$1 = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output$1> | undefined;
+  }
+  /** The Standard Typed types interface. */
+  interface Types<Input = unknown, Output$1 = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output$1;
+  }
+  /** Infers the input type of a Standard Typed. */
+  type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Typed. */
+  type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+interface StandardSchemaV1<Input = unknown, Output$1 = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output$1>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output$1 = Input> extends StandardTypedV1.Props<Input, Output$1> {
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output$1> | Promise<Result<Output$1>>;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output$1> = SuccessResult<Output$1> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output$1> {
+    /** The typed output value. */
+    readonly value: Output$1;
+    /** A falsy value for `issues` indicates success. */
+    readonly issues?: undefined;
+  }
+  interface Options {
+    /** Explicit support for additional vendor-specific parameters, if needed. */
+    readonly libraryOptions?: Record<string, unknown> | undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard types interface. */
+  interface Types<Input = unknown, Output$1 = Input> extends StandardTypedV1.Types<Input, Output$1> {}
+  /** Infers the input type of a Standard. */
+  type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+  /** Infers the output type of a Standard. */
+  type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+//#endregion
+//#region ../restate-sdk-core/src/serde_api.d.ts
 /**
- * Same shape as the SDK's `DurablePromise<T>` but each method returns
- * `Future<...>` instead of `Promise<...>`/`RestatePromise<...>`.
+ * Serializer/deserializer pair for any Restate-managed value of type `T` —
+ * handler inputs and outputs, service state, side-effect results,
+ * awakeables, durable promises, and so on.
  *
- * Workflow promises are durable; reads are journaled (so `peek`/`get`
- * are journal-backed Futures), and writes (`resolve`/`reject`) record
- * a journal entry that the user yields on.
+ * A `Serde<T>` is responsible for two conversions:
+ *
+ * - **Wire format**: `serialize` / `deserialize` convert a value `T` to and
+ *   from the raw bytes that flow over the network and get stored in the
+ *   journal.
+ * - **JSON preview (optional)**: `preview.toJsonString` /
+ *   `preview.fromJsonString` convert a value `T` to and from a JSON string,
+ *   used by tooling to render and edit values that humans can read.
+ *
+ * It also advertises metadata (`contentType`, `jsonSchema`) that surfaces in
+ * service discovery.
+ */
+interface Serde<T> {
+  /**
+   * MIME type of the bytes produced by `serialize` (and accepted by
+   * `deserialize`).
+   */
+  contentType?: string;
+  /**
+   * Optional JSON Schema describing the logical shape of `T`. Surfaced in
+   * discovery so that tooling can generate forms, auto-complete payloads,
+   * etc. Has no effect on serialization at runtime.
+   */
+  jsonSchema?: object;
+  /**
+   * Optional bridge between the serde's wire format and a JSON
+   * representation that humans (and tooling like the Restate UI) can read
+   * and edit.
+   *
+   * Only useful for serdes whose wire format isn't already plain JSON —
+   * protobuf, MessagePack, length-prefixed binary, JSON variants that need
+   * post-processing for bigints/dates, etc. Both methods may be async if the
+   * conversion needs I/O.
+   *
+   * ### Preview flow
+   *
+   * Together with `serialize` / `deserialize`, the four functions chain in
+   * both directions between a JSON string and on-the-wire bytes:
+   *
+   * ```text
+   * JSON string  ──fromJsonString──►  T  ──serialize──►  wire bytes
+   * wire bytes   ──deserialize────►  T  ──toJsonString──►  JSON string
+   * ```
+   *
+   * The split keeps `serialize` / `deserialize` responsible for the full
+   * on-the-wire format; `preview` only handles the JSON ↔ `T` bridge.
+   *
+   * @example
+   * ```ts
+   * // Wire format is protobuf; the protobuf-es runtime already ships
+   * // `toJsonString` / `fromJsonString`, so preview is a direct pass-through.
+   * import {
+   *   fromBinary,
+   *   fromJsonString,
+   *   toBinary,
+   *   toJsonString,
+   * } from "@bufbuild/protobuf";
+   * import { PersonSchema, type Person } from "./person_pb.js";
+   *
+   * const personSerde: Serde<Person> = {
+   *   contentType: "application/protobuf",
+   *   serialize(message) { return toBinary(PersonSchema, message); },
+   *   deserialize(bytes) { return fromBinary(PersonSchema, bytes); },
+   *   preview: {
+   *     toJsonString: (v) => toJsonString(PersonSchema, v),
+   *     fromJsonString: (j) => fromJsonString(PersonSchema, j),
+   *   },
+   * };
+   * ```
+   */
+  preview?: {
+    /**
+     * Convert a value into a JSON string for display or editing by humans.
+     * The returned string must round-trip through `fromJsonString` back to
+     * the same logical value.
+     */
+    toJsonString(value: T): Promise<string> | string;
+    /**
+     * Parse a human-supplied JSON string back into a value of type `T`.
+     * Should throw (or reject) if `json` is invalid for this serde.
+     */
+    fromJsonString(json: string): Promise<T> | T;
+  };
+  /**
+   * Convert a value of type `T` into its on-the-wire bytes. This is the
+   * format Restate sends between services and persists in the journal.
+   *
+   * Must be the inverse of `deserialize` — `deserialize(serialize(v))`
+   * should produce a value equivalent to `v`.
+   */
+  serialize(value: T): Uint8Array;
+  /**
+   * Convert on-the-wire bytes back into a value of type `T`. Must be the
+   * inverse of `serialize`.
+   *
+   * May throw if `data` doesn't conform to the expected wire format.
+   */
+  deserialize(data: Uint8Array): T;
+}
+declare namespace serde {
+  class JsonSerde<T> implements Serde<T | undefined> {
+    readonly jsonSchema?: object | undefined;
+    contentType: string;
+    constructor(jsonSchema?: object | undefined);
+    serialize(value: T): Uint8Array;
+    deserialize(data: Uint8Array): T | undefined;
+    schema<U$1>(schema: object): Serde<U$1>;
+  }
+  const json: JsonSerde<any>;
+  const binary: Serde<Uint8Array>;
+  const empty: Serde<void>;
+  /**
+   * A Standard Schema-based serde.
+   *
+   * @param schema the standard schema
+   * @param validateOptions options passed to `StandardSchemaV1.Options.libraryOptions` when validating
+   * @param jsonSchemaOptions options passed to `StandardJsonSchemaV1.Options.libraryOptions` for code generation
+   * @returns a serde that will validate the data with the standard schema
+   */
+  const schema: <T extends {
+    "~standard": StandardSchemaV1.Props;
+  }>(schema: T, validateOptions?: Record<string, unknown>, jsonSchemaOptions?: Record<string, unknown>) => Serde<StandardSchemaV1.InferOutput<T>>;
+}
+//#endregion
+//#region ../restate-sdk-core/src/duration.d.ts
+/**
+ * Duration type. Note that fields are additive.
  */
-type FluentDurablePromise<T> = {
+type Duration = {
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+};
+//#endregion
+//#region ../restate-sdk-core/src/entry_codec.d.ts
+/**
+ * Journal values codec.
+ *
+ * This allows to transform journal values after being serialized, before writing them to the wire.
+ *
+ * Values that are passed through the codec:
+ *
+ * * Handlers input and success output
+ * * ctx.run success results
+ * * Awakeables/Promise success results
+ * * State values
+ *
+ * @experimental
+ */
+type JournalValueCodec = {
+  /**
+   * Encodes the given buffer.
+   *
+   * This will be applied *after* serialization.
+   *
+   * @param buf The buffer to encode. Empty byte buffers should be appropriately handled as well.
+   * @returns The encoded buffer
+   */
+  encode(buf: Uint8Array): Uint8Array;
+  /**
+   * Decodes the given buffer.
+   *
+   * This will be applied *before* deserialization.
+   *
+   * @param buf The buffer to decode.
+   * @returns A promise that resolves to the decoded buffer.
+   */
+  decode(buf: Uint8Array): Promise<Uint8Array>;
+};
+//#endregion
+//#region src/define.d.ts
+/**
+ * Minimal descriptor stored in Descriptor._handlers per handler.
+ */
+type HandlerDescriptor<I$1 = any, O$1 = any> = {
+  readonly _inputSerde?: restate.Serde<I$1>;
+  readonly _outputSerde?: restate.Serde<O$1>;
+};
+/**
+ * The single client-facing type for all definition styles.
+ * - Returned by service() / object() / workflow() (also bindable to serve())
+ * - Returned by restate.interface.service/object/workflow (pure, not bindable)
+ * - Returned by implement() (also bindable)
+ */
+type Descriptor<P$1 extends string = string, H extends Record<string, HandlerDescriptor> = Record<string, HandlerDescriptor>, Kind extends "service" | "object" | "workflow" = "service" | "object" | "workflow"> = {
+  readonly name: P$1;
+  readonly _kind: Kind;
+  readonly _handlers: H;
+};
+/** Kind-specific aliases for the common Descriptor type */
+type ServiceDescriptor<P$1 extends string = string, H extends Record<string, HandlerDescriptor> = Record<string, HandlerDescriptor>> = Descriptor<P$1, H, "service">;
+type ObjectDescriptor<P$1 extends string = string, H extends Record<string, HandlerDescriptor> = Record<string, HandlerDescriptor>> = Descriptor<P$1, H, "object">;
+type WorkflowDescriptor<P$1 extends string = string, H extends Record<string, HandlerDescriptor> = Record<string, HandlerDescriptor>> = Descriptor<P$1, H, "workflow">;
+/** Implemented definition — extends Descriptor and also bindable to serve() */
+type ImplementedServiceDefinition<P$1 extends string, H extends Record<string, HandlerDescriptor>> = restate.ServiceDefinition<P$1, any> & ServiceDescriptor<P$1, H>;
+type ImplementedObjectDefinition<P$1 extends string, H extends Record<string, HandlerDescriptor>> = restate.VirtualObjectDefinition<P$1, any> & ObjectDescriptor<P$1, H>;
+type ImplementedWorkflowDefinition<P$1 extends string, H extends Record<string, HandlerDescriptor>> = restate.WorkflowDefinition<P$1, any> & WorkflowDescriptor<P$1, H>;
+type ImplementedDefinition<P$1 extends string, H extends Record<string, HandlerDescriptor>, Kind extends "service" | "object" | "workflow"> = Kind extends "service" ? ImplementedServiceDefinition<P$1, H> : Kind extends "object" ? ImplementedObjectDefinition<P$1, H> : ImplementedWorkflowDefinition<P$1, H>;
+/** @internal
+ * @internal - Wraps a generator function with optional serde. Produced by typed().
+ * Discriminated by _genFn for runtime detection (distinct from bare gen fns,
+ * which are plain functions rather than objects).
+ */
+type HandlerDef<I$1 = any, O$1 = any> = {
+  readonly _genFn: (input: I$1) => Operation<O$1>;
+} & HandlerDescriptor<I$1, O$1>;
+/** @internal */
+type EntryToDescriptor<E> = E extends HandlerDef<infer I, infer O> ? HandlerDescriptor<I, O> : E extends (() => Operation<infer O>) ? HandlerDescriptor<void, O> : E extends ((input: infer I) => Operation<infer O>) ? HandlerDescriptor<I, O> : HandlerDescriptor;
+/** Map a full handler map type to the corresponding descriptor map type */
+type HandlerDescriptors<H extends Record<string, HandlerOrHandlerDescriptor>> = { [K in keyof H]: EntryToDescriptor<H[K]> };
+/** Options valid for all handler types (no serde — those live in typed()) */
+type GenHandlerOpts = {
+  idempotencyRetention?: restate.Duration | number;
+  journalRetention?: restate.Duration | number;
+  inactivityTimeout?: restate.Duration | number;
+  abortTimeout?: restate.Duration | number;
+  retryPolicy?: restate.RetryPolicy;
+  description?: string;
+  metadata?: Record<string, string>;
+  ingressPrivate?: boolean;
+  explicitCancellation?: boolean;
+};
+/** Handler options for virtual object handlers */
+type GenObjectHandlerOpts = GenHandlerOpts & {
+  shared?: boolean;
+  enableLazyState?: boolean;
+};
+/** Handler options for workflow handlers (shared is implicit from name) */
+type GenWorkflowHandlerOpts = {
+  enableLazyState?: boolean;
+};
+/** @internal */
+type AnyGenFn = (input: any) => Operation<any>;
+/** A handler entry: either a bare generator fn or the result of typed() */
+type HandlerOrHandlerDescriptor = AnyGenFn | HandlerDef<any, any>;
+/** serdes(opts, fn) — explicit Serde per field */
+declare function serdes<I$1, O$1>(opts: {
+  input: restate.Serde<I$1>;
+  output: restate.Serde<O$1>;
+}, fn: (input: I$1) => Operation<O$1>): HandlerDef<I$1, O$1>;
+/** schemas(opts, fn) — Standard Schema (Zod, TypeBox, Valibot, …) per field */
+declare function schemas<SI extends StandardSchemaV1<any>, SO extends StandardSchemaV1<any>>(opts: {
+  input: SI;
+  output: SO;
+}, fn: (input: StandardSchemaV1.InferOutput<SI>) => Operation<StandardSchemaV1.InferOutput<SO>>): HandlerDef<StandardSchemaV1.InferOutput<SI>, StandardSchemaV1.InferOutput<SO>>;
+declare function service<P$1 extends string, H extends Record<string, HandlerOrHandlerDescriptor>>(config: {
+  name: P$1;
+  description?: string;
+  metadata?: Record<string, string>;
+  handlers: H;
+  options?: restate.ServiceOptions & {
+    handlers?: Partial<Record<keyof H, GenHandlerOpts>>;
+  };
+}): ImplementedServiceDefinition<P$1, HandlerDescriptors<H>>;
+declare function object<P$1 extends string, H extends Record<string, HandlerOrHandlerDescriptor>>(config: {
+  name: P$1;
+  description?: string;
+  metadata?: Record<string, string>;
+  handlers: H;
+  options?: restate.ObjectOptions & {
+    handlers?: Partial<Record<keyof H, GenObjectHandlerOpts>>;
+  };
+}): ImplementedObjectDefinition<P$1, HandlerDescriptors<H>>;
+declare function workflow<P$1 extends string, H extends Record<string, HandlerOrHandlerDescriptor>>(config: {
+  name: P$1;
+  description?: string;
+  metadata?: Record<string, string>;
+  handlers: H;
+  options?: restate.WorkflowOptions & {
+    handlers?: Partial<Record<keyof H, GenWorkflowHandlerOpts>>;
+  };
+}): ImplementedWorkflowDefinition<P$1, HandlerDescriptors<H>>;
+//#endregion
+//#region src/clients.d.ts
+/**
+ * A Future<O> that also carries an `invocation` field — a Future<InvocationReference<O>>
+ * for accessing the invocationId, attach, cancel, and signal of the underlying call.
+ */
+type ClientFuture<O$1> = Future<O$1> & {
+  invocation: Future<InvocationReference<O$1>>;
+};
+/** Client type returned by client() — each method returns ClientFuture<O> */
+type GenClient<H extends Record<string, HandlerDescriptor>> = { readonly [K in keyof H]: H[K] extends HandlerDescriptor<infer I, infer O> ? [I] extends [void] ? (opts?: Opts<I, O>) => ClientFuture<O> : (input: I, opts?: Opts<I, O>) => ClientFuture<O> : never };
+/** Client type returned by sendClient() — each method returns Future<InvocationReference<O>> */
+type GenSendClient<H extends Record<string, HandlerDescriptor>> = { readonly [K in keyof H]: H[K] extends HandlerDescriptor<infer I, infer O> ? [I] extends [void] ? (opts?: SendOpts<I>) => Future<InvocationReference<O>> : (input: I, opts?: SendOpts<I>) => Future<InvocationReference<O>> : never };
+//#endregion
+//#region src/durable-promise.d.ts
+/** Same shape as the SDK's DurablePromise<T> but each method returns Future<...>. */
+type GenDurablePromise<T> = {
   peek(): Future<T | undefined>;
   resolve(value?: T): Future<void>;
   reject(errorMsg: string): Future<void>;
@@ -109,6 +510,40 @@ interface State<TState extends TypedState = UntypedState> extends SharedState<TS
 }
 //#endregion
 //#region src/restate-operations.d.ts
+type HandlerRequest = {
+  readonly target: Target$1;
+  /**
+   * The unique id that identifies the current function invocation. This id is guaranteed to be
+   * unique across invocations, but constant across reties and suspensions.
+   */
+  readonly id: InvocationId;
+  readonly key?: string;
+  /**
+   * Request headers - the following headers capture the original invocation headers, as provided to
+   * the ingress.
+   */
+  readonly headers: ReadonlyMap<string, string>;
+  /**
+   * Attempt headers - the following headers are sent by the restate runtime.
+   * These headers are attempt specific, generated by the restate runtime uniquely for each attempt.
+   * These headers might contain information such as the W3C trace context, and attempt specific information.
+   */
+  readonly attemptHeaders: ReadonlyMap<string, string | string[] | undefined>;
+  /**
+   * Raw unparsed request body
+   */
+  readonly body: Uint8Array;
+  /**
+   * Extra arguments provided to the request handler:
+   * Lambda: [Context]
+   * Cloudflare workers: [Env, ExecutionContext]
+   * Deno: [ConnInfo]
+   * Bun: [Server]
+   * These arguments can contain request-specific values that could change after a suspension.
+   * Care should be taken to use them deterministically.
+   */
+  readonly extraArgs: unknown[];
+};
 /**
  * Retry policy for `run`. Mirrors the SDK's `RunOptions` retry knobs
  * but namespaced (no `Retry` prefix on each field) and grouped under
@@ -187,27 +622,25 @@ type RunAction<T> = (opts: RunActionOpts) => Promise<T>;
  */
 declare function wrapActionForCancellation<T>(signal: AbortSignal, action: RunAction<T>): () => Promise<T>;
 /**
- * Run a generator-based workflow against a Restate context.
- *
- * `op` is an `Operation<T>` — typically the result of
- * `gen(function*() { ... })`. Inside the generator body, reach for the
- * free-standing API (`run`, `sleep`, `all`, `state`, …) imported
- * from `@restatedev/restate-sdk-gen`. They read the active scheduler from a
- * synchronous current-fiber slot installed by `Fiber.advance`.
- *
- * `gen()` already takes a factory, so the same `Operation` is re-
- * iterable across multiple `execute()` calls — no need for a builder
- * lambda at this boundary.
- *
- * @example
- *   execute(ctx, gen(function* () {
- *     const greeting = yield* run(async () => "hi", { name: "compose" });
- *     return greeting;
- *   }));
+ * Deterministic date methods that return journal-backed Futures.
+ * Wraps the SDK's `ContextDate` (which returns Promises via internal
+ * `ctx.run()` calls) so that gen-SDK user code can `yield*` them.
  */
-declare function execute<T>(context: restate.Context, op: Operation<T>): Promise<T>;
+interface GenContextDate {
+  now(): Future<number>;
+  toJSON(): Future<string>;
+}
 //#endregion
 //#region src/free.d.ts
+declare const rand: () => restate.Rand;
+declare const date: () => GenContextDate;
+declare const logger: () => Console;
+/**
+ * Returns the current invocation's request metadata plus the optional
+ * virtual-object / workflow key. The `key` field is only present when
+ * the handler belongs to an object or workflow.
+ */
+declare const handlerRequest: () => HandlerRequest;
 /**
  * Run a side-effecting closure as a journal entry. See
  * `RestateOperations.run` for full semantics.
@@ -226,19 +659,24 @@ declare const resolveAwakeable: <T>(id: string, payload?: T, serde?: restate.Ser
 declare const rejectAwakeable: (id: string, reason: string | restate.TerminalError) => void;
 declare const signal: <T>(name: string, serde?: restate.Serde<T>) => Future<T>;
 declare const attach: <T>(invocationId: restate.InvocationId, serde?: restate.Serde<T>) => Future<T>;
-declare const serviceClient: <D>(api: restate.ServiceDefinitionFrom<D>) => FluentClient<restate.Client<restate.Service<D>>>;
-declare const objectClient: <D>(api: restate.VirtualObjectDefinitionFrom<D>, key: string) => FluentClient<restate.Client<restate.VirtualObject<D>>>;
-declare const workflowClient: <D>(api: restate.WorkflowDefinitionFrom<D>, key: string) => FluentClient<restate.Client<restate.Workflow<D>>>;
-declare const serviceSendClient: <D>(api: restate.ServiceDefinitionFrom<D>) => restate.SendClient<restate.Service<D>>;
-declare const objectSendClient: <D>(api: restate.VirtualObjectDefinitionFrom<D>, key: string) => restate.SendClient<restate.VirtualObject<D>>;
-declare const workflowSendClient: <D>(api: restate.WorkflowDefinitionFrom<D>, key: string) => restate.SendClient<restate.Workflow<D>>;
-declare const genericCall: <REQ = Uint8Array, RES = Uint8Array>(call: restate.GenericCall<REQ, RES>) => Future<RES>;
-declare const genericSend: <REQ = Uint8Array>(call: restate.GenericSend<REQ>) => restate.InvocationHandle;
+declare function client<H extends Record<string, HandlerDescriptor>>(def: Descriptor<string, H, "service">): GenClient<H>;
+declare function client<H extends Record<string, HandlerDescriptor>>(def: Descriptor<string, H, "object" | "workflow">, key: string): GenClient<H>;
+declare function sendClient<H extends Record<string, HandlerDescriptor>>(def: Descriptor<string, H, "service">): GenSendClient<H>;
+declare function sendClient<H extends Record<string, HandlerDescriptor>>(def: Descriptor<string, H, "object" | "workflow">, key: string): GenSendClient<H>;
+declare const call: <REQ = Uint8Array, RES = Uint8Array>(c: restate.GenericCall<REQ, RES>) => ClientFuture<RES>;
+declare const send: <REQ = Uint8Array, RES = unknown>(c: restate.GenericSend<REQ>, outputSerde?: restate.Serde<RES>) => Future<InvocationReference<RES>>;
+/**
+ * Create an InvocationReference from a known invocation ID (e.g. retrieved from state).
+ * `attach()` and `cancel()` on the result use the current fiber slot like all free functions.
+ */
+declare function invocation<O$1 = unknown>(id: string, opts?: {
+  outputSerde?: restate.Serde<O$1>;
+}): InvocationReference<O$1>;
 declare const cancel: (invocationId: restate.InvocationId) => void;
 declare const channel: <T>() => Channel<T>;
 declare const state: <TState extends TypedState = UntypedState>() => State<TState>;
 declare const sharedState: <TState extends TypedState = UntypedState>() => SharedState<TState>;
-declare const workflowPromise: <T>(name: string, serde?: restate.Serde<T>) => FluentDurablePromise<T>;
+declare const workflowPromise: <T>(name: string, serde?: restate.Serde<T>) => GenDurablePromise<T>;
 /**
  * Wait for every future to settle; return their values in input order.
  * Heterogeneous-tuple typing — `all([fA, fB])` where `fA: Future<A>`
@@ -264,6 +702,319 @@ declare const any: <const T extends readonly Future<unknown>[] | []>(futures: T)
  * Mirrors `Promise.allSettled`.
  */
 declare const allSettled: <const T extends readonly Future<unknown>[] | []>(futures: T) => Future<{ -readonly [P in keyof T]: FutureSettledResult<T[P] extends Future<infer U> ? U : never> }>;
+/**
+ * Register `op` as a fresh routine and return a `Future<T>` for its
+ * eventual outcome. Eager — the child is already in flight by the time
+ * `spawn` returns. See `RestateOperations.spawn` for full semantics.
+ */
+declare const spawn: <T>(op: Operation<T>) => Future<T>;
+declare namespace interface_d_exports {
+  export { ImplementHandlers, InferInput, InferOutput, implement, json, object$1 as object, schemas$1 as schemas, serdes$1 as serdes, service$1 as service, workflow$1 as workflow };
+}
+/** json<I, O>() — type params, default JSON serde */
+declare function json<I$1 = void, O$1 = void>(): HandlerDescriptor<I$1, O$1>;
+/** serdes(opts) — explicit Serde per field */
+declare function serdes$1<SI extends restate.Serde<any>, SO extends restate.Serde<any>>(opts: {
+  input?: SI;
+  output?: SO;
+}): HandlerDescriptor<SI extends restate.Serde<infer I> ? I : never, SO extends restate.Serde<infer O> ? O : never>;
+/** schemas(opts) — Standard Schema (Zod, TypeBox, Valibot, …) per field */
+declare function schemas$1<SI extends StandardSchemaV1<any>, SO extends StandardSchemaV1<any>>(opts: {
+  input?: SI;
+  output?: SO;
+}): HandlerDescriptor<StandardSchemaV1.InferOutput<NonNullable<SI>>, StandardSchemaV1.InferOutput<NonNullable<SO>>>;
+declare function service$1<P$1 extends string, H extends Record<string, HandlerDescriptor>>(name: P$1, handlers: H): ServiceDescriptor<P$1, H>;
+declare function object$1<P$1 extends string, H extends Record<string, HandlerDescriptor>>(name: P$1, handlers: H): ObjectDescriptor<P$1, H>;
+declare function workflow$1<P$1 extends string, H extends Record<string, HandlerDescriptor>>(name: P$1, handlers: H): WorkflowDescriptor<P$1, H>;
+/** @internal */
+type InferInput<D> = D extends HandlerDescriptor<infer I, any> ? I : any;
+/** @internal */
+type InferOutput<D> = D extends HandlerDescriptor<any, infer O> ? O : any;
+/** @internal */
+type ImplementHandlers<H extends Record<string, HandlerDescriptor>> = { [K in keyof H]: (input: InferInput<H[K]>) => Operation<InferOutput<H[K]>> };
+declare function implement<P$1 extends string, H extends Record<string, HandlerDescriptor>>(iface: ServiceDescriptor<P$1, H>, config: {
+  handlers: ImplementHandlers<H>;
+  options?: restate.ServiceOptions & {
+    handlers?: Partial<Record<keyof H, GenHandlerOpts>>;
+  };
+}): ImplementedServiceDefinition<P$1, H>;
+declare function implement<P$1 extends string, H extends Record<string, HandlerDescriptor>>(iface: ObjectDescriptor<P$1, H>, config: {
+  handlers: ImplementHandlers<H>;
+  options?: restate.ObjectOptions & {
+    handlers?: Partial<Record<keyof H, GenObjectHandlerOpts>>;
+  };
+}): ImplementedObjectDefinition<P$1, H>;
+declare function implement<P$1 extends string, H extends Record<string, HandlerDescriptor>>(iface: WorkflowDescriptor<P$1, H>, config: {
+  handlers: ImplementHandlers<H>;
+  options?: restate.WorkflowOptions & {
+    handlers?: Partial<Record<keyof H, GenWorkflowHandlerOpts>>;
+  };
+}): ImplementedWorkflowDefinition<P$1, H>;
+//#endregion
+//#region ../restate-sdk-clients/src/api.d.ts
+/**
+ * A remote client for a Restate service.
+ *
+ * Use the following client to interact with services defined
+ * - `serviceClient` to create a client for a service.
+ * - `workflowClient` to create a client for a workflow.
+ * - `objectClient` to create a client for a virtual object.
+ *
+ */
+interface Ingress {
+  /**
+   * Create a client from a {@link ServiceDefinition}.
+   */
+  serviceClient<D>(opts: ServiceDefinitionFrom<D>): IngressClient<Service<D>>;
+  /**
+   * Create a client from a {@link WorkflowDefinition}.
+   *
+   * @param key the key of the workflow.
+   */
+  workflowClient<D>(opts: WorkflowDefinitionFrom<D>, key: string): IngressWorkflowClient<Workflow<D>>;
+  /**
+   * Create a client from a {@link VirtualObjectDefinition}.
+   * @param key the key of the virtual object.
+   */
+  objectClient<D>(opts: VirtualObjectDefinitionFrom<D>, key: string): IngressClient<VirtualObject<D>>;
+  /**
+   * Create a client from a {@link ServiceDefinition}.
+   */
+  serviceSendClient<D>(opts: ServiceDefinitionFrom<D>): IngressSendClient<Service<D>>;
+  /**
+   * Create a client from a {@link VirtualObjectDefinition}.
+   */
+  objectSendClient<D>(opts: VirtualObjectDefinitionFrom<D>, key: string): IngressSendClient<VirtualObject<D>>;
+  /**
+   * Resolve an awakeable from the ingress client.
+   */
+  resolveAwakeable<T>(id: string, payload?: T, payloadSerde?: Serde<T>): Promise<void>;
+  /**
+   * Reject an awakeable from the ingress client.
+   */
+  rejectAwakeable(id: string, reason: string): Promise<void>;
+  /**
+   * Obtain the result of a service that was asynchronously submitted (via a sendClient).
+   *
+   * @param send either the send response or the workflow submission as obtained by the respective clients.
+   */
+  result<T>(send: Send<T> | WorkflowSubmission<T>, resultSerde?: Serde<T>): Promise<T>;
+  /** Generic request-response call. Routes directly by service name without a typed definition. */
+  call<I$1 = Uint8Array, O$1 = Uint8Array>(opts: {
+    service: string;
+    handler: string;
+    parameter: I$1;
+    key?: string;
+    opts?: Opts$1<I$1, O$1>;
+  }): Promise<O$1>;
+  /** Generic fire-and-forget send. Routes directly by service name without a typed definition. */
+  send<I$1 = Uint8Array>(opts: {
+    service: string;
+    handler: string;
+    parameter: I$1;
+    key?: string;
+    opts?: SendOpts$1<I$1>;
+  }): Promise<Send>;
+}
+interface IngressCallOptions<I$1 = unknown, O$1 = unknown> {
+  /**
+   * Key to use for idempotency key.
+   *
+   * See https://docs.restate.dev/operate/invocation#invoke-a-handler-idempotently for more details.
+   */
+  idempotencyKey?: string;
+  /**
+   * Headers to attach to the request.
+   */
+  headers?: Record<string, string>;
+  input?: Serde<I$1>;
+  output?: Serde<O$1>;
+  /**
+   * Timeout to be used when executing the request. In milliseconds.
+   *
+   * Same as {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal#aborting_a_fetch_with_timeout_or_explicit_abort | AbortSignal.timeout()}.
+   *
+   * This field is exclusive with `signal`, and using both of them will result in a runtime failure.
+   */
+  timeout?: number;
+  /**
+   * Signal to abort the underlying `fetch` operation. See {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal}.
+   *
+   * This field is exclusive with `timeout`, and using both of them will result in a runtime failure.
+   */
+  signal?: AbortSignal;
+}
+interface IngressSendOptions<I$1> extends IngressCallOptions<I$1, void> {
+  /**
+   * If set, the invocation will be enqueued now to be executed after the provided delay. In milliseconds.
+   */
+  delay?: number | Duration;
+}
+declare class Opts$1<I$1, O$1> {
+  readonly opts: IngressCallOptions<I$1, O$1>;
+  /**
+   * Create a call configuration from the provided options.
+   *
+   * @param opts the call configuration
+   */
+  static from<I$1 = unknown, O$1 = unknown>(opts: IngressCallOptions<I$1, O$1>): Opts$1<I$1, O$1>;
+  constructor(opts: IngressCallOptions<I$1, O$1>);
+}
+declare class SendOpts$1<I$1 = unknown> {
+  readonly opts: IngressSendOptions<I$1>;
+  /**
+   * @param opts Create send options
+   */
+  static from<I$1 = unknown>(opts: IngressSendOptions<I$1>): SendOpts$1<I$1>;
+  delay(): number | undefined;
+  constructor(opts: IngressSendOptions<I$1>);
+}
+type InferArgType<P$1> = P$1 extends [infer A, ...any[]] ? A : unknown;
+type IngressClient<M> = { [K in keyof M as M[K] extends never ? never : K]: M[K] extends ((arg: any, ...args: infer P) => PromiseLike<infer O>) ? (...args: [...P, ...[opts?: Opts$1<InferArgType<P>, O>]]) => PromiseLike<O> : never };
+/**
+ * Represents the output of a workflow.
+ */
+interface Output<O$1> {
+  /**
+   * Whether the output is ready.
+   */
+  ready: boolean;
+  /**
+   * The output of the workflow.
+   */
+  result: O$1;
+}
+/**
+ * Represents a successful workflow submission.
+ *
+ */
+type WorkflowSubmission<T> = {
+  /**
+   * The invocation id of the workflow. You can use that id to
+   * with the introspection tools (restate cli, logging, metrics)
+   *
+   */
+  readonly invocationId: string;
+  readonly status: "Accepted" | "PreviouslyAccepted";
+  readonly attachable: true;
+};
+/**
+ * A client for a workflow.
+ *
+ * This client represents the workflow definition, with the following additional methods:
+ * - `workflowSubmit` to submit the workflow.
+ * - `workflowAttach` to attach to the workflow and wait for its completion
+ * - `workflowOutput` to check if the workflow's output is ready/available.
+ *
+ * Once a workflow is submitted, it can be attached to, and the output can be retrieved.
+ *
+ * @typeParam M the type of the workflow.
+ */
+type IngressWorkflowClient<M> = Omit<{ [K in keyof M as M[K] extends never ? never : K]: M[K] extends ((arg: any, ...args: infer P) => PromiseLike<infer O>) ? (...args: [...P, ...[opts?: Opts$1<InferArgType<P>, O>]]) => PromiseLike<O> : never } & {
+  /**
+   * Submit this workflow.
+   *
+   * This instructs restate to execute the 'run' handler of the workflow, idempotently.
+   * The workflow will be executed asynchronously, and the promise will resolve when the workflow has been accepted.
+   * Please note that submitting a workflow does not wait for it to completion, and it is safe to retry the submission,
+   * in case of failure.
+   *
+   * @param argument the same argument type as defined by the 'run' handler.
+   */
+  workflowSubmit: M extends Record<string, unknown> ? M["run"] extends ((arg: any, ...args: infer I) => Promise<infer O>) ? (...args: [...I, ...[opts?: SendOpts$1<InferArgType<I>>]]) => Promise<WorkflowSubmission<O>> : never : never;
+  /**
+   * Attach to this workflow.
+   *
+   * This instructs restate to attach to the workflow and wait for it to complete.
+   * It is only possible to 'attach' to a workflow that has been previously submitted.
+   * The promise will resolve when the workflow has completed either successfully with a result,
+   * or be rejected with an error.
+   * This operation is safe to retry many times, and it will always return the same result.
+   *
+   * @returns a promise that resolves when the workflow has completed.
+   */
+  workflowAttach: M extends Record<string, unknown> ? M["run"] extends ((...args: any) => Promise<infer O>) ? (opts?: Opts$1<void, O>) => Promise<O> : never : never;
+  /**
+   * Try retrieving the output of this workflow.
+   *
+   * This instructs restate to check if the workflow's output is ready/available.
+   * The returned Output object will have a 'ready' field set to true if the output is ready.
+   * If the output is ready, the 'result' field will contain the output.
+   * note: that this operation will not wait for the workflow to complete, to do so use 'workflowAttach'.
+   *
+   * @returns a promise that resolves if the workflow's output is ready/available.
+   */
+  workflowOutput: M extends Record<string, unknown> ? M["run"] extends ((...args: any) => Promise<infer O>) ? (opts?: Opts$1<void, O>) => Promise<Output<O>> : never : never;
+}, "run">;
+/**
+ * A send response.
+ *
+ * @typeParam T the type of the response.
+ */
+type Send<T = unknown> = {
+  /**
+   * The invocation id of the send.
+   */
+  invocationId: string;
+  /**
+   * The status of the send.
+   */
+  status: "Accepted" | "PreviouslyAccepted";
+  attachable: boolean;
+};
+type IngressSendClient<M> = { [K in keyof M as M[K] extends never ? never : K]: M[K] extends ((arg: any, ...args: infer P) => PromiseLike<infer O>) ? (...args: [...P, ...[opts?: SendOpts$1<InferArgType<P>>]]) => Promise<Send<O>> : never };
+type ConnectionOpts = {
+  /**
+   * Restate ingress URL.
+   * For example: http://localhost:8080
+   */
+  url: string;
+  /**
+   * Headers to attach on every request.
+   * Use this to attach authentication headers.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Default serde to use for ingress payloads when no operation-specific serde
+   * is provided. Applies to handler calls, workflow attaches/output polling,
+   * awakeable resolution, and attached invocation results.
+   *
+   * Defaults to `restate.serde.json`.
+   */
+  serde?: Serde<any>;
+  /**
+   * Codec to use for input/outputs. Check {@link JournalValueCodec} for more details
+   *
+   * @experimental
+   */
+  journalValueCodec?: JournalValueCodec;
+};
+declare namespace ingress_d_exports {
+  export { ConnectionOpts, GenIngress, Ingress, IngressClient, IngressHandlerClient, IngressSendClient, IngressSendHandlerClient, IngressWorkflowClient, Opts$1 as Opts, Send, SendOpts$1 as SendOpts, client$1 as client, connect, sendClient$1 as sendClient };
+}
+/**
+ * Connect to the Restate Ingress.
+ *
+ * @param opts connection options
+ * @returns a connection the the restate ingress
+ */
+declare function connect(opts: ConnectionOpts): GenIngress;
+/**
+ * Minimal ingress interface required by the sdk-gen ingress helpers.
+ * Structurally compatible with `Ingress` from `@restatedev/restate-sdk-clients`
+ * — any object returned by `connect()` satisfies this.
+ */
+type GenIngress = Omit<Ingress, "serviceClient" | "serviceSendClient" | "objectClient" | "objectSendClient" | "workflowClient">;
+type InferInput$1<D> = D extends HandlerDescriptor<infer I, any> ? I : unknown;
+type InferOutput$1<D> = D extends HandlerDescriptor<any, infer O> ? O : unknown;
+/** Typed ingress call client — each method returns Promise<O> */
+type IngressHandlerClient<H extends Record<string, HandlerDescriptor>> = { readonly [K in keyof H]: (input: InferInput$1<H[K]>, opts?: Opts$1<InferInput$1<H[K]>, InferOutput$1<H[K]>>) => Promise<InferOutput$1<H[K]>> };
+/** Typed ingress send client — each method returns Promise<Send> */
+type IngressSendHandlerClient<H extends Record<string, HandlerDescriptor>> = { readonly [K in keyof H]: [InferInput$1<H[K]>] extends [void] ? (opts?: SendOpts$1<void>) => Promise<Send> : (input: InferInput$1<H[K]>, opts?: SendOpts$1<InferInput$1<H[K]>>) => Promise<Send> };
+declare function client$1<H extends Record<string, HandlerDescriptor>>(ingress: GenIngress, def: Descriptor<string, H, "service">): IngressHandlerClient<H>;
+declare function client$1<H extends Record<string, HandlerDescriptor>>(ingress: GenIngress, def: Descriptor<string, H, "object" | "workflow">, key: string): IngressHandlerClient<H>;
+declare function sendClient$1<H extends Record<string, HandlerDescriptor>>(ingress: GenIngress, def: Descriptor<string, H, "service">): IngressSendHandlerClient<H>;
+declare function sendClient$1<H extends Record<string, HandlerDescriptor>>(ingress: GenIngress, def: Descriptor<string, H, "object" | "workflow">, key: string): IngressSendHandlerClient<H>;
 //#endregion
-export { type Channel, type FluentClient, type FluentDurablePromise, type Future, type FutureFulfilledResult, type FutureRejectedResult, type FutureSettledResult, type FutureValue, type FutureValues, type Operation, type RetryOptions, type RunAction, type RunActionOpts, type RunOpts, type SelectResult, type SharedState, type State, type TypedState, type UntypedState, all, allSettled, any, attach, awakeable, cancel, channel, execute, gen, genericCall, genericSend, objectClient, objectSendClient, race, rejectAwakeable, resolveAwakeable, run, select, serviceClient, serviceSendClient, sharedState, signal, sleep, spawn, state, workflowClient, workflowPromise, workflowSendClient, wrapActionForCancellation };
+export { type AnyGenFn, type Channel, type ClientFuture, type ContextDate, type Descriptor, type Duration, type EntryToDescriptor, type Future, type FutureFulfilledResult, type FutureRejectedResult, type FutureSettledResult, type FutureValue, type FutureValues, type GenClient, type GenContextDate, type GenDurablePromise, type GenHandlerOpts, type GenObjectHandlerOpts, type GenSendClient, type GenWorkflowHandlerOpts, type HandlerDef, type HandlerDescriptor, type HandlerDescriptors, type HandlerOrHandlerDescriptor, type HandlerRequest, type ImplementHandlers, type ImplementedDefinition, type ImplementedObjectDefinition, type ImplementedServiceDefinition, type ImplementedWorkflowDefinition, type InferInput, type InferOutput, type InvocationReference, type ObjectDescriptor, type Operation, type Rand, type RetryOptions, type RunAction, type RunActionOpts, type RunOpts, type SelectResult, type Serde, type Service, type ServiceDefinition, type ServiceDefinitionFrom, type ServiceDescriptor, type SharedState, type SignalReference, type StandardSchemaV1, type StandardTypedV1, type State, type TypedState, type UntypedState, type VirtualObject, type VirtualObjectDefinition, type VirtualObjectDefinitionFrom, type Workflow, type WorkflowDefinition, type WorkflowDefinitionFrom, type WorkflowDescriptor, all, allSettled, any, attach, awakeable, call, cancel, channel, client, ingress_d_exports as clients, date, gen, handlerRequest, interface_d_exports as iface, implement, invocation, logger, object, race, rand, rejectAwakeable, resolveAwakeable, run, schemas, select, send, sendClient, serde, serdes, service, sharedState, signal, sleep, spawn, state, workflow, workflowPromise, wrapActionForCancellation };
 //# sourceMappingURL=index.d.ts.map