import type { RunRetention, World } from '#compiled/@workflow/world/index.js';
import { type DynamicStartOptions } from './dynamic-workflow.js';
import { type HealthCheckResult } from './helpers.js';
import { Run } from './run.js';
/**
 * Where a run's stamped spec version came from, recorded on the `start()`
 * span so "why is this run on spec N?" is answerable without reading code.
 */
export type SpecVersionSource = 'same-deployment' | 'explicit' | 'probe' | 'probe-unversioned' | 'probe-malformed' | 'probe-miss' | 'no-probe-channel';
/**
 * The spec version to stamp on a run that another deployment will execute.
 *
 * A run's spec version is a promise about the runtime that reads and writes
 * its event log, and for a cross-deployment start that is the target, not
 * this caller. The capability probe runs inside the target and reports the
 * version the target itself mints (which already honours the target's own
 * `WORKFLOW_SEALED_LOG` switch), so that is the answer, capped at what this
 * caller's World mints: the caller writes `run_created` and the arguments,
 * and must never stamp a version it could not have written itself.
 *
 * When the target does not report a usable version:
 *
 * - a plain-text reply predates the versioned JSON health response, which
 *   arrived with spec 3 (CBOR queue transport), so it is stamped as
 *   event-sourced: such a target cannot read a CBOR `runInput`.
 * - a JSON reply without a usable `specVersion` still proves the target is
 *   at spec 3 or later, so it is stamped with CBOR queue transport rather
 *   than losing it (and resilient start with it) to a malformed field.
 * - a probe that times out, or no probe channel at all, is a guess.
 *   `SPEC_VERSION_SUPPORTS_SLOT_IDENTITY` is the lowest version a v5 runtime
 *   can execute on the Vercel World (it requires slot event ids), so it is
 *   the only floor that keeps same-major targets working. It is NOT safe for
 *   an older-major target such as `stable` (spec 3): that target rejects the
 *   run when it picks it up. No single floor serves both, which is why the
 *   probe budget is generous; the miss is logged and recorded on the span.
 *
 * Once executors attest their version on `run_started` and the backend
 * raises a run to it (vercel/workflow#4366, vercel/workflow-server#1044), a
 * v5 target heals an under-stamped run, and this miss floor may drop, but
 * only once the raise is enabled on the whole server fleet AND every v5
 * target a caller can reach attests its version (a published beta that does
 * not would be stamped below slot identity and fail). Even then a floor
 * below `SPEC_VERSION_SUPPORTS_ATTRIBUTES` would refuse `attributes` on every
 * miss. Tracked in vercel/workflow#4401.
 *
 * Exported for tests.
 */
export declare function resolveCrossDeploymentSpecVersion(probe: Pick<HealthCheckResult, 'healthy' | 'specVersion' | 'format'> | undefined, callerSpecVersion: number): {
    specVersion: number;
    source: SpecVersionSource;
};
/**
 * Reset the `deploymentId: 'latest'` no-op warn-once guard. Test-only,
 * exported so unit tests can exercise the warn path across `start()` calls.
 *
 * @internal
 */
export declare function _resetLatestNoOpWarnForTests(): void;
/**
 * Reset the cross-deployment probe-miss warn-once guard. Test-only.
 *
 * @internal
 */
export declare function _resetProbeMissWarnForTests(): void;
export interface StartOptionsBase {
    /**
     * The world to use for the workflow run creation,
     * by default the world is inferred from the environment variables.
     */
    world?: World;
    /**
     * The spec version to use for the workflow run. Defaults to the spec
     * version of the deployment that will execute the run: the configured
     * World's for a same-deployment start, and for a cross-deployment start
     * (`deploymentId` naming another deployment) the version the target
     * reports on its capability probe, capped at the configured World's.
     */
    specVersion?: number;
    /**
     * Optional region identifier for the new run. Currently consumed only
     * by `@workflow/world-vercel`, which embeds the region into the tagged
     * run ID and routes the initial workflow message to the matching
     * regional queue. When omitted, the world falls back to its own
     * default (for `world-vercel`: the `VERCEL_REGION` environment
     * variable, then the server-side default region `iad1`; a concrete,
     * routable region is always chosen).
     *
     * Worlds without a regional dimension ignore this field.
     */
    region?: string;
    /**
     * Plaintext attributes to seed on the run as it is created.
     *
     * Available for native-attributes runs (spec version 4 and later).
     */
    attributes?: Record<string, string>;
    /**
     * Permit reserved `$`-prefixed keys in `attributes`. The `$` namespace
     * is reserved for framework/library code built on top of the workflow
     * SDK (telemetry, agent metadata, platform-emitted tags, etc.); user
     * code MUST NOT write keys in it, and validation rejects them so
     * accidental collisions with tooling-owned keys can't slip through.
     *
     * Only flip this to `true` if your caller is itself a framework or
     * library that owns a `$`-prefixed sub-namespace and knows the
     * conventions of any other tools writing into it. Same semantics as
     * the `setAttributes` option of the same name.
     */
    allowReservedAttributes?: boolean;
    /**
     * Set a preference for data retention after run completion.
     *
     * **Experimental.** Both the unit and the set of accepted values are expected
     * to change.
     *
     * Worlds control the retention of user data (event payloads and stream
     * chunks), the event log, and any analytics data. Options are:
     * - `'default'`: same as omission, the World will decide. On Vercel, this
     *   is based on your team's plan.
     * - `0`: data is deleted as soon as your run completes or fails. On
     *   Vercel, user data is deleted, but metadata may persist for your plan's
     *   default retention period.
     *
     * The value is a duration, with zero being the only valid option currently.
     *
     * **Known limitation at `0`.** The purge races your own read of the run's
     * result and generally wins, so `await run.returnValue` on a
     * `experimental_retention: 0` run usually throws `RunExpiredError` rather
     * than resolving. If you need the result, return it through a channel you
     * control, e.g. a step that writes it to external storage.
     *
     * Recorded on the run as the reserved `$retention` attribute, so it
     * requires a World implementing spec version 4 or later. `'default'` is
     * not written at all, keeping it exactly equivalent to omitting the
     * option. Retention is enforced by the World: the first-party Worlds
     * (Vercel, Local, Postgres) implement it, and a World that does not
     * recognize the value keeps the data.
     */
    experimental_retention?: RunRetention;
    /**
     * The ID of an existing run this run is being replayed from, if any.
     *
     * Recorded on the new run's `executionContext` as `replayedFromRunId` so
     * tooling (e.g. the dashboard runs list) can show that a run originated as
     * a replay and link back to its source. Set automatically by
     * {@link recreateRunFromExisting}; there's usually no reason to pass it
     * directly.
     *
     * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
     * to the source run, so `start()` validates the exact shape and rejects
     * anything else rather than persist a lineage link that points at garbage.
     */
    replayedFromRunId?: string;
    /**
     * Queue namespace of the target deployment. Scopes the workflow queue
     * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
     * default `__wkf_workflow_*`, and is also used for the cross-deployment
     * capability probe. Falls back to `WORKFLOW_QUEUE_NAMESPACE` in the
     * calling process.
     *
     * Within a deployment the env fallback is correct. Cross-context callers
     * (e.g. the observability dashboard replaying a run) must pass the
     * TARGET deployment's namespace explicitly: the env fallback resolves in
     * the caller's process, and a run enqueued to a topic the target has no
     * consumer for is never picked up.
     */
    namespace?: string;
}
export interface StartOptionsWithDeploymentId extends StartOptionsBase {
    /**
     * The deployment ID to use for the workflow run.
     *
     * By default, this is automatically inferred from environment variables
     * when deploying to Vercel.
     *
     * Set to `'latest'` to automatically resolve the most recent deployment
     * for the current environment (same production target or git branch).
     * This is only meaningful in worlds with atomic, immutable deployments
     * (currently Vercel). In other worlds (local dev, Postgres) there is no
     * notion of multiple deployments to resolve between, so `'latest'` has no
     * effect: a warning is logged and the run targets the current deployment.
     *
     * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
     * since there is no guarantee the types will be consistent across deployments.
     */
    deploymentId: 'latest' | (string & {});
}
export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
    deploymentId?: undefined;
}
/**
 * Options for starting a workflow run.
 */
export type StartOptions = StartOptionsWithDeploymentId | StartOptionsWithoutDeploymentId;
export type { DynamicStartOptions, DynamicWorkflowOptions, DynamicWorkflowStepReference, } from './dynamic-workflow.js';
/**
 * Represents an imported workflow function.
 */
export type WorkflowFunction<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
/**
 * Represents the generated metadata of a workflow function.
 */
export type WorkflowMetadata = {
    workflowId: string;
};
/**
 * Starts a workflow run.
 *
 * @param workflow - The imported workflow function to start.
 * @param args - The arguments to pass to the workflow (optional).
 * @param options - The options for the workflow run (optional).
 * @returns The unique run ID for the newly started workflow invocation.
 */
export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: unknown[], options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: TArgs, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
export declare function start(source: string, args: unknown[], options: DynamicStartOptions): Promise<Run<unknown>>;
export declare function start(source: string, options: DynamicStartOptions): Promise<Run<unknown>>;
//# sourceMappingURL=start.d.ts.map