@fluidgrids/workflows 2026.1028.2 → 2026.1030.1

package/dist/workflow-BGnv8SS6.d.ts

@@ -0,0 +1,803 @@
+import { a as Json, J as JsonObject, b as WorkflowInterface } from './types-V7jEEUaL.js';
+import { M as Headers, e as RetryPolicy, i as ActivityCancellationType, b as WorkflowInfoSnapshot, P as ParentClosePolicy, C as ChildCancellationType, at as VersioningBehavior, ay as WorkflowIdReusePolicy, ax as WorkflowIdConflictPolicy, f as RunRetryPolicy } from './types-DGx-b9eq.js';
+
+/**
+ * Node operation descriptors: what a builder call needs to know about the node
+ * it emits. Generated clients (`.fluidgrids/nodes.ts`) are lists of these;
+ * the built-in internal nodes and triggers ship here so `nodes.internal.*` and
+ * `triggers.*` work without a registry.
+ */
+
+/** A file reference in node inputs and outputs. */
+interface FileRef {
+    fileId: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+}
+declare const OPERATION_TYPES: unique symbol;
+/** One node operation. `In` and `Out` type the arguments and the output. */
+interface Operation<In = Record<string, Json>, Out = Json> {
+    readonly kind: 'operation';
+    readonly nodeType: string;
+    /** Written as the node's `version` unless the call overrides it. */
+    readonly version?: string;
+    /** Written as the node's `operation_name` unless the call overrides it. */
+    readonly operation?: string;
+    readonly role?: 'trigger';
+    /** Type-level only; never present at run time. */
+    readonly [OPERATION_TYPES]?: {
+        input: In;
+        output: Out;
+    };
+}
+/** A trigger operation. */
+type TriggerOperation<In = Record<string, Json>, Out = Json> = Operation<In, Out> & {
+    readonly role: 'trigger';
+};
+/** Describe a node operation (generated clients call this). */
+declare function op<In = Record<string, Json>, Out = Json>(nodeType: string, version?: string, operation?: string): Operation<In, Out>;
+/** Describe a trigger operation (generated clients call this). */
+declare function trigger<In = Record<string, Json>, Out = Json>(nodeType: string, version?: string, operation?: string): TriggerOperation<In, Out>;
+/** True for a value made by {@link op} or {@link trigger}. */
+declare function isOperation(value: unknown): value is Operation<unknown, unknown>;
+/** Built-in trigger nodes (`wspace-workflow-svc` `triggers/manifests`). */
+declare const triggers: {
+    readonly api: TriggerOperation<Record<string, Json>, Json>;
+    readonly manual: TriggerOperation<Record<string, Json>, Json>;
+    readonly schedule: TriggerOperation<Record<string, Json>, Json>;
+    readonly webhook: TriggerOperation<Record<string, Json>, Json>;
+    readonly form: TriggerOperation<Record<string, Json>, Json>;
+    readonly errorTrigger: TriggerOperation<Record<string, Json>, Json>;
+    readonly workflowCall: TriggerOperation<Record<string, Json>, Json>;
+    readonly rssFeed: TriggerOperation<Record<string, Json>, Json>;
+    readonly httpPoll: TriggerOperation<Record<string, Json>, Json>;
+    readonly databasePoll: TriggerOperation<Record<string, Json>, Json>;
+    readonly emailImap: TriggerOperation<Record<string, Json>, Json>;
+    readonly fileUpload: TriggerOperation<Record<string, Json>, Json>;
+    readonly recordChange: TriggerOperation<Record<string, Json>, Json>;
+    readonly stateChange: TriggerOperation<Record<string, Json>, Json>;
+};
+/** Built-in internal nodes (`wspace-workflow-svc` `internalnodes/manifests`, plus the two IR v2 nodes). */
+declare const internalNodes: {
+    readonly merge: Operation<Record<string, Json>, Json>;
+    readonly if: Operation<Record<string, Json>, Json>;
+    readonly switch: Operation<Record<string, Json>, Json>;
+    readonly loop: Operation<Record<string, Json>, Json>;
+    readonly set: Operation<Record<string, Json>, Json>;
+    readonly filter: Operation<Record<string, Json>, Json>;
+    readonly aggregate: Operation<Record<string, Json>, Json>;
+    readonly wait: Operation<Record<string, Json>, Json>;
+    readonly noop: Operation<Record<string, Json>, Json>;
+    readonly code: Operation<Record<string, Json>, Json>;
+    readonly http: Operation<Record<string, Json>, Json>;
+    readonly transform: Operation<Record<string, Json>, Json>;
+    readonly validate: Operation<Record<string, Json>, Json>;
+    readonly log: Operation<Record<string, Json>, Json>;
+    readonly error: Operation<Record<string, Json>, Json>;
+    readonly subworkflow: Operation<Record<string, Json>, Json>;
+    readonly compareDatasets: Operation<Record<string, Json>, Json>;
+    readonly splitOut: Operation<Record<string, Json>, Json>;
+    readonly limit: Operation<Record<string, Json>, Json>;
+    readonly dedupe: Operation<Record<string, Json>, Json>;
+    readonly sort: Operation<Record<string, Json>, Json>;
+    readonly dataTable: Operation<Record<string, Json>, Json>;
+    readonly respondToWebhook: Operation<Record<string, Json>, Json>;
+    readonly sendAndWait: Operation<Record<string, Json>, Json>;
+    readonly codeWorkflow: Operation<Record<string, Json>, Json>;
+    readonly waitForSignal: Operation<Record<string, Json>, Json>;
+    /** Phase C: signal another run (`fluidgrids.run-control`). */
+    readonly signalRun: Operation<Record<string, Json>, Json>;
+    /** Phase C: upsert the run's search attributes (`fluidgrids.search-attributes`). */
+    readonly setSearchAttributes: Operation<Record<string, Json>, Json>;
+};
+/** Node clients that need no registry: the internal nodes and `custom()`. */
+declare const nodes: {
+    readonly internal: {
+        readonly merge: Operation<Record<string, Json>, Json>;
+        readonly if: Operation<Record<string, Json>, Json>;
+        readonly switch: Operation<Record<string, Json>, Json>;
+        readonly loop: Operation<Record<string, Json>, Json>;
+        readonly set: Operation<Record<string, Json>, Json>;
+        readonly filter: Operation<Record<string, Json>, Json>;
+        readonly aggregate: Operation<Record<string, Json>, Json>;
+        readonly wait: Operation<Record<string, Json>, Json>;
+        readonly noop: Operation<Record<string, Json>, Json>;
+        readonly code: Operation<Record<string, Json>, Json>;
+        readonly http: Operation<Record<string, Json>, Json>;
+        readonly transform: Operation<Record<string, Json>, Json>;
+        readonly validate: Operation<Record<string, Json>, Json>;
+        readonly log: Operation<Record<string, Json>, Json>;
+        readonly error: Operation<Record<string, Json>, Json>;
+        readonly subworkflow: Operation<Record<string, Json>, Json>;
+        readonly compareDatasets: Operation<Record<string, Json>, Json>;
+        readonly splitOut: Operation<Record<string, Json>, Json>;
+        readonly limit: Operation<Record<string, Json>, Json>;
+        readonly dedupe: Operation<Record<string, Json>, Json>;
+        readonly sort: Operation<Record<string, Json>, Json>;
+        readonly dataTable: Operation<Record<string, Json>, Json>;
+        readonly respondToWebhook: Operation<Record<string, Json>, Json>;
+        readonly sendAndWait: Operation<Record<string, Json>, Json>;
+        readonly codeWorkflow: Operation<Record<string, Json>, Json>;
+        readonly waitForSignal: Operation<Record<string, Json>, Json>;
+        /** Phase C: signal another run (`fluidgrids.run-control`). */
+        readonly signalRun: Operation<Record<string, Json>, Json>;
+        /** Phase C: upsert the run's search attributes (`fluidgrids.search-attributes`). */
+        readonly setSearchAttributes: Operation<Record<string, Json>, Json>;
+    };
+    /**
+     * Any node type, including ones the registry snapshot does not know. Typed
+     * as JSON in and out.
+     */
+    readonly custom: (nodeType: string, operation?: string, version?: string) => Operation<Record<string, Json>, Json>;
+};
+
+/**
+ * User activities (Phase C, 11 §2.2, §2.29, CWD9): functions a self-hosted
+ * worker runs for workflow code.
+ *
+ * - {@link declareActivity} names an activity and its default task queue. The
+ *   declaration is all workflow code needs: `ctx.activity(decl, { args })`
+ *   issues `SCHEDULE_ACTIVITY` of kind `user`.
+ * - {@link implementActivity} attaches the function to a declaration, for the
+ *   worker. {@link defineActivity} does both in one step.
+ * - {@link dynamicActivity} handles every activity name the worker has no
+ *   implementation for.
+ *
+ * Implementations belong to the worker, not to the workflow bundle: `lower()`
+ * reports `durable.activityImplInBundle` when a workflow module pulls one in.
+ *
+ * Pure JavaScript; declarations run inside the isolate.
+ */
+
+declare const ACTIVITY_MARKER = "fluidgrids.activity";
+declare const ACTIVITY_IMPL_MARKER = "fluidgrids.activity-impl";
+declare const ACTIVITY_TYPES: unique symbol;
+/** The name `*` a dynamic activity is registered under. */
+declare const DYNAMIC_ACTIVITY_NAME = "*";
+interface ActivityDeclarationOptions {
+    /** The task queue the activity runs on unless the call names another; default the workflow's. */
+    taskQueue?: string;
+    input?: SchemaLike;
+    output?: SchemaLike;
+    description?: string;
+}
+/** A declared user activity. */
+interface ActivityDefinition<In = Json, Out = Json> {
+    readonly __fluidgrids: typeof ACTIVITY_MARKER;
+    readonly name: string;
+    readonly options: ActivityDeclarationOptions;
+    /** Type-level only (functions, so any definition is assignable to the `never`/`unknown` one). */
+    readonly [ACTIVITY_TYPES]?: {
+        args: (args: In) => void;
+        result: () => Out;
+    };
+}
+/** What a running activity attempt knows. */
+interface ActivityInfo {
+    readonly runId: string;
+    readonly workspaceId?: string;
+    readonly workflowKey?: string;
+    readonly activityId: string;
+    /** The activity name (for a dynamic activity, the requested one). */
+    readonly activityName: string;
+    readonly taskQueue: string;
+    /** 1-based. */
+    readonly attempt: number;
+    /** Details the previous attempt recorded with `heartbeat` (11 §2.4). */
+    readonly heartbeatDetails?: Json;
+    readonly headers: Headers;
+}
+/** The context an activity function receives. */
+interface ActivityContext {
+    readonly info: ActivityInfo;
+    /**
+     * Record progress (at most 32 KiB of details, kept for the next attempt)
+     * and learn whether to stop. When the attempt was paused (`pauseActivity`,
+     * 11 §2.28) `paused` is true; the activity should then throw
+     * `ActivityPausedError`, which is not retried while the activity is paused.
+     */
+    heartbeat(details?: unknown): Promise<{
+        cancelRequested: boolean;
+        paused: boolean;
+    }>;
+    /** Aborted when the workflow requests cancellation or the worker shuts down. */
+    readonly cancellationSignal: AbortSignalLike;
+    /**
+     * Hand completion to an outside system (11 §2.2): returns a task token and
+     * ends this attempt without completing it. The outside system finishes it
+     * with `completeActivityAsync(token, result)` or the activity webhook.
+     */
+    completeAsync(): Promise<string>;
+    /** Credentials of a connection the activity declares (H2 rules apply on self-hosted workers). */
+    connection(name: string): Promise<Record<string, Json>>;
+}
+/** The part of `AbortSignal` activities may rely on. */
+interface AbortSignalLike {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+type ActivityFunction<In = Json, Out = Json> = (ctx: ActivityContext, args: In) => Out | Promise<Out>;
+/** A user activity's implementation, for a worker. */
+interface ActivityImplementation<In = Json, Out = Json> extends ActivityDefinition<In, Out> {
+    readonly implementation: typeof ACTIVITY_IMPL_MARKER;
+    readonly fn: ActivityFunction<In, Out>;
+    /** True for {@link dynamicActivity}: `fn` receives `(ctx, args)` for any name. */
+    readonly dynamic: boolean;
+}
+/** Throw a `TypeError` unless `name` is a valid activity name. */
+declare function checkActivityName(name: string): void;
+/** Throw a `TypeError` unless `queue` is a valid task queue name. */
+declare function checkTaskQueueName(queue: string, what?: string): void;
+/** Declare a user activity for workflow code. */
+declare function declareActivity<In = Json, Out = Json>(name: string, options?: ActivityDeclarationOptions): ActivityDefinition<In, Out>;
+/** Attach the worker-side function to a declaration. */
+declare function implementActivity<In, Out>(definition: ActivityDefinition<In, Out>, fn: ActivityFunction<In, Out>): ActivityImplementation<In, Out>;
+/** Declare and implement a user activity in one step. */
+declare function defineActivity<In = Json, Out = Json>(name: string, options: ActivityDeclarationOptions, fn: ActivityFunction<In, Out>): ActivityImplementation<In, Out>;
+declare function defineActivity<In = Json, Out = Json>(name: string, fn: ActivityFunction<In, Out>): ActivityImplementation<In, Out>;
+/**
+ * Handle every activity name the worker has no implementation for (11
+ * §2.29); `ctx.info.activityName` is the requested name.
+ */
+declare function dynamicActivity<Out = Json>(fn: ActivityFunction<Json, Out>, options?: Pick<ActivityDeclarationOptions, 'taskQueue' | 'description'>): ActivityImplementation<Json, Out>;
+/** True for a value made by {@link declareActivity} (or an implementation). */
+declare function isActivityDefinition(value: unknown): value is ActivityDefinition<never, unknown>;
+/** True for a value made by {@link implementActivity}, {@link defineActivity} or {@link dynamicActivity}. */
+declare function isActivityImplementation(value: unknown): value is ActivityImplementation<never, unknown>;
+/** An activity attempt is about to run its function. */
+interface ActivityExecuteInput {
+    args: Json;
+    readonly headers: Headers;
+    readonly info: ActivityInfo;
+}
+/** Interceptors around an activity's execution, on the worker (11 §2.10). */
+interface ActivityInboundInterceptor {
+    execute?(input: ActivityExecuteInput, next: (input: ActivityExecuteInput) => Promise<unknown>): Promise<unknown>;
+}
+/** Interceptors of what an activity issues, on the worker. */
+interface ActivityOutboundInterceptor {
+    heartbeat?(details: unknown, next: (details: unknown) => Promise<unknown>): Promise<unknown>;
+    getLogAttributes?(input: Record<string, Json>, next: (input: Record<string, Json>) => Record<string, Json>): Record<string, Json>;
+    getMetricTags?(input: Record<string, string>, next: (input: Record<string, string>) => Record<string, string>): Record<string, string>;
+}
+/** The implementation that serves `name`: an exact one, else a dynamic one. */
+declare function findActivityImplementation(implementations: readonly ActivityImplementation<never, unknown>[], name: string): ActivityImplementation<never, unknown> | undefined;
+/**
+ * Run one activity attempt through the inbound interceptors (first
+ * outermost). Workers and the test environment use it.
+ */
+declare function executeActivity(implementation: ActivityImplementation<never, unknown>, ctx: ActivityContext, args: Json, interceptors?: readonly ActivityInboundInterceptor[]): Promise<unknown>;
+
+/**
+ * Signal, query and update definitions (spec 02 §4, 05). Signals work in Phase
+ * B; queries and updates can be declared (they appear in the interface) but
+ * custom handlers are Phase C.
+ */
+declare const PAYLOAD: unique symbol;
+interface SignalDefinition<Payload = unknown> {
+    readonly kind: 'signal';
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema of the payload, written into the workflow interface. */
+    readonly schema?: Record<string, unknown>;
+    /** Type-level only. */
+    readonly [PAYLOAD]?: Payload;
+}
+interface QueryDefinition<Result = unknown, Args = unknown> {
+    readonly kind: 'query';
+    readonly name: string;
+    readonly description?: string;
+    readonly [PAYLOAD]?: {
+        result: Result;
+        args: Args;
+    };
+}
+interface UpdateDefinition<Args = unknown, Result = unknown> {
+    readonly kind: 'update';
+    readonly name: string;
+    readonly description?: string;
+    readonly [PAYLOAD]?: {
+        result: Result;
+        args: Args;
+    };
+}
+interface DefinitionOptions {
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+/** Declare a signal. */
+declare function defineSignal<Payload = unknown>(name: string, options?: DefinitionOptions): SignalDefinition<Payload>;
+/** Declare a query. Handlers are Phase C; the declaration appears in the interface. */
+declare function defineQuery<Result = unknown, Args = unknown>(name: string, options?: {
+    description?: string;
+}): QueryDefinition<Result, Args>;
+/** Declare an update. Handlers are Phase C; the declaration appears in the interface. */
+declare function defineUpdate<Args = unknown, Result = unknown>(name: string, options?: {
+    description?: string;
+}): UpdateDefinition<Args, Result>;
+
+/** A duration: milliseconds, or a string such as `'30s'` or `'PT2H'`. */
+type Duration = number | string;
+/** Milliseconds of `value`; throws a `TypeError` naming `what` when it is not a duration. */
+declare function toMs(value: Duration, what?: string): number;
+
+/**
+ * The `WorkflowContext` a tier-2 workflow function receives (spec 02 §4). The
+ * runtime (`src/runtime/`) implements it; this module is types only.
+ */
+
+/** Options of `ctx.run`. */
+interface RunOptions<In> {
+    args: In;
+    /** Connection name, resolved by the service at `SCHEDULE_ACTIVITY`. */
+    connection?: string;
+    /** Default: 1 s, x2, at most 100 s, unlimited attempts (Temporal's policy). */
+    retry?: Partial<RetryPolicy>;
+    startToCloseTimeout?: Duration;
+    scheduleToCloseTimeout?: Duration;
+    scheduleToStartTimeout?: Duration;
+    heartbeatTimeout?: Duration;
+    cancellationType?: ActivityCancellationType;
+    /** 1 (highest) to 5; default 3. */
+    priority?: number;
+    /** Label in the History tab (at most 200 characters). */
+    summary?: string;
+    runOn?: string;
+    /** Overrides the operation name the descriptor carries. */
+    operation?: string;
+    /** Overrides the node version the descriptor carries. */
+    nodeVersion?: string;
+    headers?: Headers;
+    /** Fairness within the queue (11 §2.11); default the workspace id. */
+    fairnessKey?: string;
+    /** 0.1 to 10; default 1. */
+    fairnessWeight?: number;
+}
+/**
+ * Options of `ctx.activity` (Phase C, user activities). The task queue is
+ * the option, else the declaration's, else the workflow's own queue.
+ */
+interface ActivityOptions<In> {
+    args: In;
+    taskQueue?: string;
+    /** Default: 1 s, x2, at most 100 s, unlimited attempts (Temporal's policy). */
+    retry?: Partial<RetryPolicy>;
+    startToCloseTimeout?: Duration;
+    scheduleToCloseTimeout?: Duration;
+    scheduleToStartTimeout?: Duration;
+    heartbeatTimeout?: Duration;
+    cancellationType?: ActivityCancellationType;
+    /** 1 (highest) to 5; default 3. */
+    priority?: number;
+    fairnessKey?: string;
+    fairnessWeight?: number;
+    /** Label in the History tab (at most 200 characters). */
+    summary?: string;
+    /** Connections the worker may resolve for this activity (at most 16, H2). */
+    connections?: string[];
+    headers?: Headers;
+}
+/** Options of `ctx.handleUpdate` and `ctx.setDefaultUpdateHandler` (05 §6, 11 §2.39). */
+interface UpdateHandlerOptions<Args> {
+    /**
+     * Runs before the update is accepted, without changing the run; throw to
+     * reject it (nothing is written to history and the caller gets the error).
+     * It is skipped when a replay re-delivers an update that history accepted.
+     */
+    validate?: (args: Args) => void;
+    /** Default `WARN_AND_ABANDON`. */
+    unfinishedPolicy?: HandlerUnfinishedPolicy;
+    description?: string;
+}
+/** Options of `ctx.setDefaultUpdateHandler`. */
+interface DefaultUpdateHandlerOptions {
+    validate?: (name: string, args: unknown) => void;
+    unfinishedPolicy?: HandlerUnfinishedPolicy;
+}
+/**
+ * Fire-and-forget calls to worker-side code (11 §2.31, self-hosted workers):
+ * `ctx.sinks.<sink>.<fn>(...args)`. Calls are reported once, when the task
+ * completes, never during replay or in a query. Managed runs ignore them.
+ */
+type WorkflowSinks = Readonly<Record<string, Readonly<Record<string, (...args: Json[]) => void>>>>;
+/** Options of `ctx.localActivity` (11 §2.12). */
+interface LocalActivityOptions<In> {
+    args: In;
+    /** Connection name, resolved by the worker that runs the task. */
+    connection?: string;
+    /** Default: 1 s, x2, at most 100 s, unlimited attempts, bounded by the task's 30 s budget. */
+    retry?: Partial<RetryPolicy>;
+    /** At most 30 s (the default). */
+    startToCloseTimeout?: Duration;
+    /** Label in the History tab (at most 200 characters). */
+    summary?: string;
+    /** Overrides the operation name the descriptor carries. */
+    operation?: string;
+    /** Overrides the node version the descriptor carries. */
+    nodeVersion?: string;
+}
+/**
+ * Run-level retry of a workflow (11 §2.17): a run that fails with a retryable
+ * failure, or whose run timeout expires, starts again as a new run of the same
+ * chain with `ctx.info.attempt + 1` and `ctx.info.lastFailure`.
+ */
+interface WorkflowRetryOptions {
+    /** Attempts in total, the first one included; absent means unlimited (bounded by the execution timeout). */
+    maxAttempts?: number;
+    /** Delay before the second attempt; default 1 s. */
+    initialDelay?: Duration;
+    /** Default 2. */
+    backoffMultiplier?: number;
+    /** Largest delay; default 100 s, or 100 times `initialDelay` when that is given. */
+    maxDelay?: Duration;
+    /** Free-form failure types that are never retried. */
+    nonRetryableErrorTypes?: string[];
+}
+/** A run addressed by its workflow id (11 §2.1): the open run of the chain. */
+interface WorkflowIdTarget {
+    workflowKey: string;
+    workflowId: string;
+    /** Pins the chain whose first run this is. */
+    firstRunId?: string;
+}
+/** Another run of the workspace: a run id or a workflow id. */
+type ExternalRunTarget = string | {
+    runId: string;
+} | WorkflowIdTarget;
+/** What happens to a handler still running when the workflow finishes (11 §2.18). */
+type HandlerUnfinishedPolicy = 'WARN_AND_ABANDON' | 'ABANDON';
+/** Options of `ctx.onSignal`. */
+interface SignalHandlerOptions {
+    /** Default `WARN_AND_ABANDON`: a warning when the workflow finishes while this handler runs. */
+    unfinishedPolicy?: HandlerUnfinishedPolicy;
+}
+/** Options of `ctx.child` and `ctx.startChild` (11 §2.35). */
+interface ChildOptions {
+    input?: unknown;
+    /** `active` (default), `vN` or `@alias`. */
+    version?: string;
+    taskQueue?: string;
+    /** Default `TERMINATE` for `ctx.child`, `ABANDON` for `ctx.startChild` (DB13). */
+    parentClosePolicy?: ParentClosePolicy;
+    /**
+     * How the awaitable reacts when its scope is cancelled. Unset, it rejects at
+     * once and the child is left to the parent-close policy; set, the SDK sends
+     * a cancel request to the child (`REQUEST_CANCEL_EXTERNAL_RUN`, a parity
+     * command).
+     */
+    cancellationType?: ChildCancellationType;
+    workflowId?: string;
+    priority?: number;
+    summary?: string;
+    details?: string;
+    context?: JsonObject;
+    startDelay?: Duration;
+    executionTimeout?: Duration;
+    runTimeout?: Duration;
+    workflowTaskTimeout?: Duration;
+    /** Run-level retry of the child. */
+    retry?: WorkflowRetryOptions;
+    versioningBehavior?: VersioningBehavior;
+    idReusePolicy?: WorkflowIdReusePolicy;
+    idConflictPolicy?: WorkflowIdConflictPolicy;
+    headers?: Headers;
+    /** Fairness of the child's tasks (11 §2.11). */
+    fairnessKey?: string;
+    fairnessWeight?: number;
+}
+/** A started child run. */
+interface ChildHandle<Out = Json> {
+    readonly childId: string;
+    readonly runId: string;
+    result(): Promise<Out>;
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Request cancellation of the child (parity command `REQUEST_CANCEL_EXTERNAL_RUN`). */
+    cancel(): Promise<void>;
+}
+/** A handle to another run of the workspace (11 §2.24). */
+interface ExternalRunHandle {
+    /** The run id of a run-id target; empty for a workflow-id target. */
+    readonly runId: string;
+    /** The workflow key and id of a workflow-id target. */
+    readonly workflowKey?: string;
+    readonly workflowId?: string;
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Resolves when the cancel request was delivered, not when the run ends. */
+    cancel(): Promise<void>;
+}
+/** A cancellation scope (11 §2.24). */
+interface CancellationScope {
+    /** Rejects with `CancelledFailure` when the scope is cancelled. */
+    readonly cancelRequested: Promise<never>;
+    readonly consideredCancelled: boolean;
+    cancel(): void;
+}
+interface CancellationScopeOptions {
+    /** A durable timer that cancels the scope when it fires. */
+    timeout?: Duration;
+    nonCancellable?: boolean;
+}
+/** `ctx.cancellationScope(fn, options)` and `ctx.cancellationScope.current()`. */
+interface CancellationScopeFunction {
+    <T>(fn: (ctx: WorkflowContext) => Promise<T>, options?: CancellationScopeOptions): Promise<T>;
+    current(): CancellationScope;
+}
+/** What workflow code knows about its run. */
+interface WorkflowInfo extends WorkflowInfoSnapshot {
+    readonly workflowFn: string;
+    /** Events in the history when the current workflow task started. */
+    readonly historyLength: number;
+    /** UTF-8 bytes of their payloads. */
+    readonly historyBytes: number;
+    /** True from 80 % of the history cap; continue as new soon. */
+    readonly continueAsNewSuggested: boolean;
+    readonly isReplaying: boolean;
+}
+/** Logging from workflow code; lines are emitted once, never during replay. */
+interface WorkflowLogger {
+    debug(message: string, data?: Json): void;
+    info(message: string, data?: Json): void;
+    warn(message: string, data?: Json): void;
+    error(message: string, data?: Json): void;
+}
+/**
+ * Compensations run in reverse order, each in its own non-cancellable scope,
+ * so they still run after a cancel request. A compensation receives that
+ * scope's `ctx`; use it for every call after the compensation's first await.
+ */
+interface Saga {
+    add(compensation: (ctx: WorkflowContext) => unknown): void;
+    compensate(): Promise<void>;
+}
+/** Options of `ctx.continueAsNew`; each defaults to the current run's value (11 §2.20). */
+/**
+ * The R1 continue-as-new retry option: the activity retry shape. R1 wrote it
+ * into `CONTINUE_AS_NEW` unchanged and the Phase B service ignored it.
+ *
+ * @deprecated Since R2; give a run-level {@link WorkflowRetryOptions}.
+ */
+type LegacyContinueAsNewRetry = Partial<RetryPolicy>;
+interface ContinueAsNewOptions {
+    taskQueue?: string;
+    /**
+     * The run-level retry policy of the new run. The R1 activity shape
+     * (`retryDelay`, `maxRetries`) is still accepted and written as R1 wrote it;
+     * it has no effect, as in Phase B.
+     */
+    retry?: WorkflowRetryOptions | LegacyContinueAsNewRetry;
+    workflowTaskTimeout?: Duration;
+    /** The new run's memo. */
+    context?: JsonObject;
+    versioningBehavior?: VersioningBehavior;
+}
+/** A child target: a workflow key (graph or durable) or a tier-2 function of the same bundle. */
+type ChildTarget<Out> = string | DurableWorkflow<never, Out> | DurableWorkflow<Json, Out>;
+/** The context of a tier-2 workflow function. */
+interface WorkflowContext {
+    readonly info: WorkflowInfo;
+    readonly log: WorkflowLogger;
+    /** Run a canvas node operation as a durable activity (`SCHEDULE_ACTIVITY`, kind `node`). */
+    run<In, Out>(operation: Operation<In, Out>, options: RunOptions<In>): Promise<Out>;
+    /** A durable timer. */
+    sleep(duration: Duration, options?: {
+        summary?: string;
+    }): Promise<void>;
+    /** Resolves `true` once `predicate` holds after an event, or `false` when `timeout` passes first. */
+    condition(predicate: () => boolean, timeout?: Duration): Promise<boolean>;
+    /** The next signal of this name (buffered signals first). */
+    signalReceived<P>(signal: SignalDefinition<P> | string): Promise<P>;
+    /** Handle every signal of this name, buffered ones first. */
+    onSignal<P>(signal: SignalDefinition<P> | string, handler: (payload: P) => unknown): void;
+    onSignal<P>(signal: SignalDefinition<P> | string, options: SignalHandlerOptions, handler: (payload: P) => unknown): void;
+    /** Handle signals no other handler or waiter takes. */
+    setDefaultSignalHandler(handler: (name: string, payload: unknown) => unknown): void;
+    /** Start a child run and wait for its result. */
+    child<Out = Json>(target: ChildTarget<Out>, options?: ChildOptions): Promise<Out>;
+    /** Start a child run; resolves once it has started. */
+    startChild<Out = Json>(target: ChildTarget<Out>, options?: ChildOptions): Promise<ChildHandle<Out>>;
+    /** Signal another run of the workspace (by run id or workflow id); resolves on delivery. */
+    signalRun<P>(target: ExternalRunTarget, signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Signal the parent run. */
+    signalParent<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    getRunHandle(target: ExternalRunTarget): ExternalRunHandle;
+    /** Shorthand for `getRunHandle(target).cancel()`. */
+    cancelRun(target: ExternalRunTarget): Promise<void>;
+    /** The workflow clock (the task's start time), in epoch milliseconds. */
+    now(): number;
+    /** A deterministic random number in [0, 1), seeded per run. */
+    random(): number;
+    /** A deterministic version-4 UUID. */
+    uuid(): string;
+    /** Record a value once (`RECORD_SIDE_EFFECT`); replays return the recorded value. */
+    sideEffect<T extends Json>(fn: () => T): T;
+    /** In-place versioning (spec 06 §4). */
+    patched(patchId: string): boolean;
+    deprecatePatch(patchId: string): void;
+    /** Live Markdown status for the run page and `__metadata` (at most 20 KiB). */
+    setCurrentDetails(markdown: string): void;
+    /** Merge keys into the run's context (parity command `UPSERT_CONTEXT`). */
+    upsertContext(entries: JsonObject): void;
+    /** End this run and start a fresh history (parity command `CONTINUE_AS_NEW`). */
+    continueAsNew(input: unknown, options?: ContinueAsNewOptions): Promise<never>;
+    /**
+     * Run `fn` in a new cancellation scope. `fn` gets a `ctx` bound to the
+     * scope: use it inside `fn`. This outer `ctx` joins the scope only while
+     * `fn` runs synchronously; after an await it is back in its own scope, so
+     * concurrent branches never share a scope by accident.
+     */
+    readonly cancellationScope: CancellationScopeFunction;
+    /** `cancellationScope(fn, { nonCancellable: true })`; the same `ctx` rule applies. */
+    nonCancellable<T>(fn: (ctx: WorkflowContext) => Promise<T>): Promise<T>;
+    /**
+     * Run `fn` when the current scope is cancelled. An error thrown by `fn` is
+     * handled like an error thrown by the workflow; the other handlers still run.
+     */
+    onCancel(fn: () => void): void;
+    isCancellation(error: unknown): boolean;
+    saga(): Saga;
+    /** Resolves when no asynchronous signal or update handler is running; cancellation does not interrupt the wait. */
+    allHandlersFinished(): Promise<void>;
+    /**
+     * Run a user activity on a self-hosted worker (Phase C,
+     * `SCHEDULE_ACTIVITY` of kind `user`). Needs `fluidgrids.self-hosted-workers`;
+     * the `managed` queue refuses user activities.
+     */
+    activity<In, Out>(activity: ActivityDefinition<In, Out> | string, options: ActivityOptions<In>): Promise<Out>;
+    /**
+     * Run a short, idempotent node operation inside the workflow task (11
+     * §2.12): the worker that runs the task executes it and the task records one
+     * `LOCAL_ACTIVITY_COMPLETED` or `LOCAL_ACTIVITY_FAILED` marker
+     * (`RECORD_LOCAL_ACTIVITY`). Replays return the recorded outcome and never
+     * run it again. The activity allow-list of `ctx.run` applies; a user
+     * function instead of a node operation is Phase C and throws
+     * `PhaseCFeatureError`.
+     */
+    localActivity<In, Out>(operation: Operation<In, Out>, options: LocalActivityOptions<In>): Promise<Out>;
+    localActivity(fn: (...args: never[]) => unknown, options?: unknown): Promise<never>;
+    /**
+     * Answer a custom query (Phase C): `handler` runs after the history is
+     * replayed and must return a value without changing the run (commands and
+     * sinks throw `QueryHandlerSideEffect`).
+     */
+    handleQuery<Result, Args>(query: QueryDefinition<Result, Args> | string, handler: (args: Args) => Result): void;
+    /** Answer queries no handler takes (Phase C). */
+    setDefaultQueryHandler(handler: (name: string, args: unknown) => unknown): void;
+    /**
+     * Handle an update (Phase C, 05 §6): `validate` may reject it (no history),
+     * the handler's result or failure completes it (`UPDATE_COMPLETED`). The
+     * handler may await activities, timers and children.
+     */
+    handleUpdate<Args, Result>(update: UpdateDefinition<Args, Result> | string, handler: (args: Args) => Result | Promise<Result>, options?: UpdateHandlerOptions<Args>): void;
+    /** Handle updates no handler takes (Phase C, 11 §2.29). */
+    setDefaultUpdateHandler(handler: (name: string, args: unknown) => unknown, options?: DefaultUpdateHandlerOptions): void;
+    setDefaultUpdateHandler(options: DefaultUpdateHandlerOptions, handler: (name: string, args: unknown) => unknown): void;
+    /**
+     * Upsert the run's search attributes (Phase C, 11 §2.8,
+     * `UPSERT_SEARCH_ATTRIBUTES`); a null value removes one. The service
+     * validates the values against the workspace definitions.
+     */
+    upsertSearchAttributes(attributes: JsonObject): void;
+    /** Worker-side sinks (Phase C, self-hosted workers). */
+    readonly sinks: WorkflowSinks;
+}
+
+/**
+ * `workflow()`: declare a tier-2 durable workflow function (spec 02 §4).
+ *
+ * The value is inert data plus the function: nothing runs at module load.
+ * `lower()` reads it to report `code.exports.workflows[exportName]`, and the
+ * runtime (`src/runtime/`) calls the function by export name inside a
+ * workflow task.
+ */
+
+declare const DURABLE_MARKER = "fluidgrids.durable-workflow";
+/**
+ * A payload schema: a JSON Schema object, or a schema library value with a
+ * `toJSONSchema()` method. Anything else (a zod schema without one, for
+ * example) types the code but leaves the interface without that schema.
+ */
+type SchemaLike = Record<string, unknown> | {
+    toJSONSchema(): unknown;
+};
+/** How a standalone tier-2 workflow starts (lowered to its trigger node). */
+type TriggerSpec = Operation<never, unknown> | Operation<Record<string, Json>, Json> | {
+    operation: Operation<never, unknown> | Operation<Record<string, Json>, Json>;
+    args?: JsonObject;
+    id?: string;
+};
+interface DurableWorkflowOptions {
+    /** Display name of the standalone workflow. */
+    title?: string;
+    description?: string;
+    input?: SchemaLike;
+    output?: SchemaLike;
+    signals?: ReadonlyArray<SignalDefinition<never> | SignalDefinition<unknown>>;
+    /** Declared queries; `ctx.handleQuery` answers them (Phase C). */
+    queries?: ReadonlyArray<QueryDefinition<unknown, unknown>>;
+    /** Declared updates; `ctx.handleUpdate` handles them (Phase C). */
+    updates?: ReadonlyArray<UpdateDefinition<unknown, unknown>>;
+    /**
+     * Accept names the interface does not declare (11 §2.29), written as
+     * `interface.open`. `lower()` also sets a kind open when the declaring
+     * module registers a default handler for it.
+     */
+    open?: {
+        signals?: boolean;
+        queries?: boolean;
+        updates?: boolean;
+    };
+    /** Default `managed`. */
+    taskQueue?: string;
+    /** Lowers to the trigger node of the standalone workflow (default `internal:api`). */
+    trigger?: TriggerSpec;
+    /**
+     * Whether the function is a workflow of its own (07 §4): by default, when it
+     * declares a trigger or nothing in the project embeds it with `wf.codeWorkflow`.
+     */
+    standalone?: boolean;
+    /** Error classes that fail the run instead of the workflow task (11 §2.25). */
+    failureErrorTypes?: ReadonlyArray<abstract new (...args: never[]) => Error>;
+    /** `PINNED` (default) or `AUTO_UPGRADE` (11 §2.27); lowered to `config.versioningBehavior`. */
+    versioningBehavior?: VersioningBehavior;
+    /** Run-level retry (11 §2.17); lowered to `config.retry`. */
+    retry?: WorkflowRetryOptions;
+    /** Bounds the whole continue-as-new and retry chain (11 §2.20); `config.executionTimeout`. */
+    executionTimeout?: Duration;
+    /** Bounds one run; `config.timeout`. */
+    runTimeout?: Duration;
+    /** The replay budget of one workflow task, at most 120 s; `config.workflowTaskTimeout`. */
+    workflowTaskTimeout?: Duration;
+}
+/** The largest `workflowTaskTimeout` (11 §2.20). */
+declare const MAX_WORKFLOW_TASK_TIMEOUT_MS = 120000;
+/** A declared tier-2 workflow. */
+interface DurableWorkflow<In = Json, Out = Json> {
+    readonly __fluidgrids: typeof DURABLE_MARKER;
+    /** The workflow key it gets when it is standalone. */
+    readonly name: string;
+    readonly options: DurableWorkflowOptions;
+    readonly fn: (ctx: WorkflowContext, input: In) => Promise<Out>;
+    /**
+     * True for {@link dynamicWorkflow}: it serves every function name the
+     * bundle does not export (`code.exports.workflows["*"]`, 11 §2.29).
+     */
+    readonly dynamic?: boolean;
+}
+/** Declare a tier-2 workflow. `name` is its workflow key when it is standalone. */
+declare function workflow<In = Json, Out = Json>(name: string, options: DurableWorkflowOptions, fn: (ctx: WorkflowContext, input: In) => Promise<Out>): DurableWorkflow<In, Out>;
+declare function workflow<In = Json, Out = Json>(name: string, fn: (ctx: WorkflowContext, input: In) => Promise<Out>): DurableWorkflow<In, Out>;
+/**
+ * Declare a dynamic workflow (Phase C, 11 §2.29): it runs for every
+ * `workflowFn` the bundle does not export, and receives the requested name.
+ * `lower()` writes it to `code.exports.workflows["*"]`, so a start or a child
+ * naming any function of the workflow key reaches it. One per bundle.
+ */
+declare function dynamicWorkflow<Out = Json>(name: string, options: DurableWorkflowOptions, fn: (ctx: WorkflowContext, workflowFn: string, input: Json) => Promise<Out>): DurableWorkflow<Json, Out>;
+declare function dynamicWorkflow<Out = Json>(name: string, fn: (ctx: WorkflowContext, workflowFn: string, input: Json) => Promise<Out>): DurableWorkflow<Json, Out>;
+/** True for a value made by {@link workflow}. */
+declare function isDurableWorkflow(value: unknown): value is DurableWorkflow<never, unknown>;
+/** The JSON Schema of a {@link SchemaLike}, or undefined when it has none. */
+declare function jsonSchemaOf(schema: SchemaLike | undefined): JsonObject | undefined;
+/** The workflow `interface` (spec 01 §4) a tier-2 declaration describes. */
+declare function interfaceOf(definition: DurableWorkflow<never, unknown>): WorkflowInterface;
+/** The history form (milliseconds, defaults filled in) of a run-level retry option. */
+declare function runRetryPolicyOf(retry: WorkflowRetryOptions): RunRetryPolicy;
+/**
+ * The `CONTINUE_AS_NEW` `options.retry` of a `ctx.continueAsNew` retry option
+ * (C-SCHEMA `canOptions`).
+ *
+ * - An option with an activity-only key (`retryDelay`, `maxRetries`,
+ *   `retryOnErrorTypes`) is the R1 shape. It is written exactly as R1 wrote it
+ *   (activity form, defaults filled in), so an R1 workflow issues the same
+ *   command and keeps its Phase B behaviour: the service ignores that shape.
+ * - Anything else is a run-level retry policy (R2), checked for unknown keys.
+ *   Keys both shapes share (`maxDelay`, `backoffMultiplier`,
+ *   `nonRetryableErrorTypes`) alone mean the R2 shape.
+ * - Mixing an activity-only key with `maxAttempts` or `initialDelay` throws.
+ */
+declare function continueAsNewRetryOf(retry: WorkflowRetryOptions | LegacyContinueAsNewRetry): RunRetryPolicy | RetryPolicy;
+
+export { continueAsNewRetryOf as $, ACTIVITY_IMPL_MARKER as A, type SchemaLike as B, type CancellationScope as C, DURABLE_MARKER as D, type ExternalRunHandle as E, type FileRef as F, type SignalDefinition as G, type HandlerUnfinishedPolicy as H, type SignalHandlerOptions as I, type TriggerSpec as J, type UpdateHandlerOptions as K, type LegacyContinueAsNewRetry as L, MAX_WORKFLOW_TASK_TIMEOUT_MS as M, type WorkflowIdTarget as N, type Operation as O, type WorkflowInfo as P, type QueryDefinition as Q, type RunOptions as R, type Saga as S, type TriggerOperation as T, type UpdateDefinition as U, type WorkflowLogger as V, type WorkflowContext as W, type WorkflowRetryOptions as X, type WorkflowSinks as Y, checkActivityName as Z, checkTaskQueueName as _, ACTIVITY_MARKER as a, declareActivity as a0, defineActivity as a1, defineQuery as a2, defineSignal as a3, defineUpdate as a4, dynamicActivity as a5, dynamicWorkflow as a6, executeActivity as a7, findActivityImplementation as a8, implementActivity as a9, interfaceOf as aa, internalNodes as ab, isActivityDefinition as ac, isActivityImplementation as ad, isDurableWorkflow as ae, isOperation as af, jsonSchemaOf as ag, nodes as ah, op as ai, runRetryPolicyOf as aj, toMs as ak, trigger as al, triggers as am, workflow as an, type AbortSignalLike as b, type ActivityContext as c, type ActivityDeclarationOptions as d, type ActivityDefinition as e, type ActivityExecuteInput as f, type ActivityFunction as g, type ActivityImplementation as h, type ActivityInboundInterceptor as i, type ActivityInfo as j, type ActivityOptions as k, type ActivityOutboundInterceptor as l, type CancellationScopeFunction as m, type CancellationScopeOptions as n, type ChildHandle as o, type ChildOptions as p, type ChildTarget as q, type ContinueAsNewOptions as r, DYNAMIC_ACTIVITY_NAME as s, type DefaultUpdateHandlerOptions as t, type DefinitionOptions as u, type DurableWorkflow as v, type DurableWorkflowOptions as w, type Duration as x, type ExternalRunTarget as y, type LocalActivityOptions as z };