import type { Analytics } from './analytics.js';
import type { AttributeChange, ExperimentalSetAttributesResult } from './attributes.js';
import type { CreateEventParams, CreateEventRequest, Event, EventResult, GetEventParams, ListEventsByCorrelationIdParams, ListEventsParams, RunCreatedEventRequest } from './events.js';
import type { GetHookParams, Hook, ListHooksParams } from './hooks.js';
import type { Queue } from './queue.js';
import type { GetWorkflowRunParams, ListWorkflowRunsParams, WorkflowRun, WorkflowRunWithoutData } from './runs.js';
import type { GetChunksOptions, PaginatedResponse, StreamChunksResponse, StreamInfoResponse } from './shared.js';
import type { GetStepParams, ListWorkflowRunStepsParams, Step, StepWithoutData } from './steps.js';
export interface Streamer {
    /**
     * Override the default flush interval (in milliseconds) for buffered stream writes.
     * Chunks are accumulated in a buffer and flushed together on this interval.
     *
     * The default is 10ms, which is appropriate for HTTP-based backends where
     * each flush is a network round-trip. For backends with sub-millisecond writes
     * (e.g., Redis, local filesystem), a lower value (or 0 for immediate flushing) reduces
     * end-to-end stream latency.
     *
     * Not supported by all worlds.
     */
    streamFlushIntervalMs?: number;
    streams: {
        write(runId: string, name: string, chunk: string | Uint8Array): Promise<void>;
        /**
         * Write multiple chunks to a stream in a single operation.
         * This is an optional optimization for world implementations that can
         * batch multiple writes efficiently (e.g., single HTTP request for world-vercel).
         *
         * If not implemented, the caller should fall back to sequential write() calls.
         *
         * @param runId - The run ID
         * @param name - The stream name
         * @param chunks - Array of chunks to write, in order
         */
        writeMulti?(runId: string, name: string, chunks: (string | Uint8Array)[]): Promise<void>;
        close(runId: string, name: string): Promise<void>;
        /**
         * Read from a stream starting at the given chunk index.
         * Positive values skip that many chunks from the start (0-based).
         * Negative values start that many chunks before the current end
         * (e.g. -3 on a 10-chunk stream starts at chunk 7). Clamped to 0.
         */
        get(runId: string, name: string, startIndex?: number): Promise<ReadableStream<Uint8Array>>;
        list(runId: string): Promise<string[]>;
        /**
         * Fetch stream chunks with cursor-based pagination.
         *
         * Unlike `get` (which returns a live `ReadableStream` that waits
         * for new chunks in real-time), `getChunks` returns a snapshot of currently
         * available chunks in a standard paginated response.
         *
         * @param runId - The workflow run ID that owns the stream
         * @param name - The stream name/ID
         * @param options - Pagination options (limit defaults to 100, max 1000)
         * @returns Paginated chunks with a `done` flag indicating stream completion
         */
        getChunks(runId: string, name: string, options?: GetChunksOptions): Promise<StreamChunksResponse>;
        /**
         * Retrieve lightweight metadata about a stream.
         *
         * Returns the tail index (index of the last known chunk, 0-based) and
         * whether the stream is complete. This is useful for resolving a negative
         * `startIndex` into an absolute position before connecting to a stream.
         *
         * @param runId - The workflow run ID that owns the stream
         * @param name - The stream name/ID
         */
        getInfo(runId: string, name: string): Promise<StreamInfoResponse>;
    };
}
/**
 * Storage interface for workflow data.
 *
 * Workflow storage models an append-only event log, so all state changes are handled through `events.create()`.
 * Run/Step/Hook entities provide materialized views into the current state, but entities can't be modified directly.
 *
 * User-originated state changes are also handled via events:
 * - run_cancelled event for run cancellation
 * - hook_disposed event for explicit hook disposal (optional)
 *
 * When a workflow reaches a terminal state, its Hooks can no longer be resumed.
 * Worlds normally remove them and release their tokens. A Hook with minimum
 * retention remains readable and keeps its token unavailable until its retention
 * ends. A hook_disposed event always removes the Hook and releases its token.
 */
export interface Storage {
    runs: {
        get(id: string, params: GetWorkflowRunParams & {
            resolveData: 'none';
        }): Promise<WorkflowRunWithoutData>;
        get(id: string, params?: GetWorkflowRunParams & {
            resolveData?: 'all';
        }): Promise<WorkflowRun>;
        get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun | WorkflowRunWithoutData>;
        /**
         * Retrieves several runs as one snapshot. The result preserves the input
         * order and contains `null` for run IDs that do not exist.
         */
        getMany?: {
            (ids: readonly string[], params: GetWorkflowRunParams & {
                resolveData: 'none';
            }): Promise<(WorkflowRunWithoutData | null)[]>;
            (ids: readonly string[], params?: GetWorkflowRunParams & {
                resolveData?: 'all';
            }): Promise<(WorkflowRun | null)[]>;
            (ids: readonly string[], params?: GetWorkflowRunParams): Promise<(WorkflowRun | WorkflowRunWithoutData | null)[]>;
        };
        list(params: ListWorkflowRunsParams & {
            resolveData: 'none';
        }): Promise<PaginatedResponse<WorkflowRunWithoutData>>;
        list(params?: ListWorkflowRunsParams & {
            resolveData?: 'all';
        }): Promise<PaginatedResponse<WorkflowRun>>;
        list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun | WorkflowRunWithoutData>>;
        /**
         * Apply a batch of attribute changes to a run. Merge semantics:
         * - `value: string` upserts the key
         * - `value: null` removes the key
         * - keys not listed in `changes` are untouched
         *
         * Returns the post-merge attribute snapshot on the run.
         *
         * Pass `options.allowReservedAttributes: true` to permit keys
         * starting with the reserved `$` prefix. Default behavior rejects
         * those keys so user code can't accidentally collide with
         * framework / tooling namespaces; framework callers that own a
         * sub-namespace flip this on.
         *
         * OPTIONAL. World implementations may omit this method; the SDK
         * helper (`setAttributes` in `@workflow/core`) feature-detects its
         * absence and no-ops with a one-time warning so third-party /
         * community worlds keep working without adopting the experimental
         * API.
         *
         * EXPERIMENTAL: this method exists as a stopgap until the
         * `attr_set` event type lands in a future spec version. When that
         * happens, `setAttributes` will dispatch through `events.create`
         * instead, and this method is expected to be removed. See the
         * `attributes-mvp` changelog entry for the migration shape.
         */
        experimentalSetAttributes?(runId: string, changes: AttributeChange[], options?: {
            allowReservedAttributes?: boolean;
        }): Promise<ExperimentalSetAttributesResult>;
    };
    steps: {
        get(runId: string, stepId: string, params: GetStepParams & {
            resolveData: 'none';
        }): Promise<StepWithoutData>;
        get(runId: string, stepId: string, params?: GetStepParams & {
            resolveData?: 'all';
        }): Promise<Step>;
        get(runId: string, stepId: string, params?: GetStepParams): Promise<Step | StepWithoutData>;
        list(params: ListWorkflowRunStepsParams & {
            resolveData: 'none';
        }): Promise<PaginatedResponse<StepWithoutData>>;
        list(params: ListWorkflowRunStepsParams & {
            resolveData?: 'all';
        }): Promise<PaginatedResponse<Step>>;
        list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step | StepWithoutData>>;
    };
    events: {
        /**
         * Create a run_created event to start a new workflow run.
         * The runId may be provided by the client or left as null for the server to generate.
         *
         * @param runId - Client-generated runId, or null for server-generated
         * @param data - The run_created event data
         * @param params - Optional parameters for event creation
         * @returns Promise resolving to the created event and run entity
         */
        create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
        /**
         * Create an event for an existing workflow run and atomically update the entity.
         * Returns both the event and the affected entity (run/step/hook).
         *
         * @param runId - The workflow run ID (required for all events except run_created)
         * @param data - The event to create
         * @param params - Optional parameters for event creation
         * @returns Promise resolving to the created event and affected entity
         */
        create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
        get(runId: string, eventId: string, params?: GetEventParams): Promise<Event>;
        list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
        listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
    };
    hooks: {
        /**
         * Returns a Hook by ID. A Hook kept by minimum retention remains readable
         * after its run ends, but cannot be resumed.
         */
        get(hookId: string, params?: GetHookParams): Promise<Hook>;
        /**
         * Returns the Hook that owns a token, including a Hook kept by minimum
         * retention after its run ends.
         */
        getByToken(token: string, params?: GetHookParams): Promise<Hook>;
        /**
         * Lists Hooks, including Hooks kept by minimum retention after their runs
         * end.
         */
        list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
    };
}
/**
 * Optional feature capabilities a World implementation declares so the core
 * runtime can enable optimizations that depend on backend behavior, instead
 * of inferring support from environment variables alone. Every capability
 * defaults to "unsupported" when absent — runtime fast paths that rely on
 * one must fail closed (keep their conservative behavior) unless the World
 * explicitly declares it.
 */
export interface WorldCapabilities {
    /**
     * Supports `experimental_minRetention` for Hooks. Missing or inactive means
     * the runtime rejects retained Hooks before registration.
     */
    hookRetention?: {
        active: boolean;
    };
    /**
     * The World enforces the optimistic-concurrency precondition guard: an
     * event creation carrying a `stateUpdatedAt` snapshot is rejected with a
     * `PreconditionFailedError` (412) when a newer out-of-band event (e.g. a
     * received hook) was recorded after that snapshot. Worlds that accept but
     * ignore `stateUpdatedAt` must leave this unset so runtime optimizations
     * that rely on the 412 fence (see `WORKFLOW_PRECONDITION_GUARD`) are not
     * enabled without an actual fence behind them.
     */
    preconditionGuard?: boolean;
    /**
     * The World's queue supports `maxConcurrency`-limited consumption — in
     * particular the per-run flow topics consumed with `maxConcurrency: 1`
     * that `WORKFLOW_SEQUENTIAL_REPLAYS=1` uses to serialize a run's
     * orchestrator invocations. Worlds whose queue has no concurrency-limit
     * concept must leave this unset.
     *
     * Note this declares queue *support*, not deployed configuration: the
     * serialization also requires the build-time half (a flow trigger emitted
     * with `maxConcurrency: 1`), which a runtime process cannot verify today.
     * The core runtime therefore does not yet take any fast path from this
     * capability alone — it exists so a future build-verified signal can be
     * combined with it (and so Worlds document the contract explicitly).
     */
    maxConcurrency?: boolean;
}
/**
 * The "World" interface represents how Workflows are able to communicate with the outside world.
 */
export interface World extends Queue, Streamer, Storage {
    /**
     * Optional analytics read namespace for observability surfaces.
     *
     * These APIs return metadata-only rows intended for UI/CLI listing and
     * trace views. Payload-bearing fields remain on the canonical runtime
     * storage APIs (`runs`, `steps`, `events`, `hooks`) and their RemoteRef
     * resolution path.
     */
    analytics?: Analytics;
    /**
     * The Workflow protocol spec version this World implements.
     *
     * Current runtimes require this to exactly match their
     * `SPEC_VERSION_CURRENT` before they create or replay runs.
     */
    specVersion: number;
    /**
     * Feature capabilities this World implementation supports — see
     * {@link WorldCapabilities}. Absent (or absent members) means
     * "unsupported": runtime optimizations gated on a capability fail closed.
     */
    capabilities?: WorldCapabilities;
    /**
     * Whether calling `process.exit(1)` from a queue handler is observed by
     * the World as a delivery failure that will be retried.
     *
     * Set to `true` for worlds running inside a managed serverless platform
     * (e.g. `world-vercel`) where the platform fails the invocation when the
     * function process exits non-zero, and the queue redelivers the message
     * via a separate fresh invocation.
     *
     * Set to `false` (the default) for in-process worlds (e.g. `world-local`,
     * dev servers) where calling `process.exit()` would terminate the host
     * process — including the user's `pnpm dev` — without producing a
     * redelivery. Such worlds should instead surface failures via the event
     * log and return normally.
     *
     * The core runtime reads this when deciding how to handle an exhausted
     * replay budget: when `true` it exits so the queue redelivers; when
     * `false` it writes `run_failed` best-effort and returns. See
     * `packages/core/src/runtime/replay-budget.ts`.
     */
    processExitTriggersQueueRedelivery?: boolean;
    /**
     * A function that will be called to start any background tasks needed by the World implementation.
     * For example, in the case of a queue backed World, this would start the queue processing.
     */
    start?(): Promise<void>;
    /**
     * Release any resources held by the World implementation (connection pools, listeners, etc.).
     * After calling `close()`, the World instance should not be used again.
     *
     * This is important for CLI commands and short-lived processes that need to exit cleanly
     * without relying on `process.exit()`.
     */
    close?(): Promise<void>;
    /**
     * Resolve the most recent deployment ID for the current deployment's environment.
     *
     * Used when `deploymentId: 'latest'` is passed to `start()`. The implementation
     * determines the latest deployment that shares the same environment (e.g., same
     * "production" target or same git branch for "preview" deployments) as the
     * current deployment.
     *
     * Not all World implementations support this — it is only implemented by
     * world-vercel where deployment routing is meaningful.
     */
    resolveLatestDeploymentId?(): Promise<string>;
    /**
     * Retrieve the AES-256 encryption key for a specific workflow run.
     *
     * The returned key is a ready-to-use 32-byte AES-256 key. The World
     * implementation handles all key retrieval and derivation internally
     * (e.g., HKDF from a deployment key). The core encryption module uses
     * this key directly for AES-GCM encrypt/decrypt operations.
     *
     * Two overloads:
     *
     * - `getEncryptionKeyForRun(run)` — Preferred. Pass a `WorkflowRun` when
     *   the run entity already exists. The World reads any context it needs
     *   (e.g., `deploymentId`) directly from the run.
     *
     * - `getEncryptionKeyForRun(runId, context?)` — Used when the run entity
     *   is not locally available, such as `start()` before run creation or a
     *   forwarded writable stream carrying its owning deployment context. The
     *   `context` parameter carries opaque world-specific data (e.g.,
     *   `{ deploymentId }` for world-vercel) needed to resolve the correct key.
     *   When `context` is omitted, the World assumes the current deployment.
     *
     * When not implemented, encryption is disabled — data is stored unencrypted.
     */
    getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
    getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
    /**
     * Mint a new workflow run ID.
     *
     * Called by `start()` to generate the unique ID for a newly-created run.
     * The returned value is the "bare" ID (without any `wrun_` prefix); the
     * core attaches the prefix.
     *
     * Implementations are free to embed world-specific metadata in the ID
     * (e.g., a region identifier) as long as the returned string remains a
     * valid ULID. When omitted, `start()` falls back to generating a standard
     * monotonic ULID.
     *
     * @param options - The full options bag passed to `start()` (typed as
     *   `Record<string, unknown>` here to avoid a circular dependency with
     *   `@workflow/core`). Worlds should read only the fields they
     *   recognise — for example, `@workflow/world-vercel` reads
     *   `options.region` to embed a region identifier. Unrecognised keys
     *   must be ignored. `start()` always passes an object (an empty one
     *   when it was called with no options), but implementations should
     *   tolerate `undefined` for direct callers.
     */
    createRunId?(options?: Readonly<Record<string, unknown>>): string;
    /**
     * World-specific display fields for a run.
     *
     * Tooling — e.g. the `workflow inspect` CLI — calls this to enrich a
     * run's listing row / detail output with fields only the world can
     * derive: a region decoded from the run ID, placement read off the
     * run's `executionContext`, a shard, a billing tier, etc. Consumers
     * render each returned key as an additional column/property; when the
     * hook is absent, no extra fields appear at all.
     *
     * The contract:
     * - **Cheap and pure.** Called once per displayed run, so avoid I/O —
     *   prefer deriving fields from the entity you are given.
     * - **Read only what you recognise.** The argument is the run entity
     *   as the caller has it (a full storage run, or a leaner analytics
     *   row) — typed loosely for the same reason as {@link createRunId}.
     *   Tolerate missing fields.
     * - **Must not throw.**
     * - A `null` field value means "applicable but undeterminable" and is
     *   preserved as `null` in structured output (vs. the hook being
     *   absent, where the key does not exist at all). Return `null` or an
     *   empty object to add nothing for a given run.
     */
    describeRun?(run: Readonly<Record<string, unknown>>): Record<string, string | null> | null | Promise<Record<string, string | null> | null>;
}
//# sourceMappingURL=interfaces.d.ts.map