/**
 * Defines the transport envelopes exchanged by cluster entities.
 *
 * Request envelopes wrap decoded RPC payloads with the target entity address,
 * RPC tag, request id, headers, and optional tracing context. The module also
 * includes acknowledgement envelopes for streamed reply chunks, interrupt
 * envelopes for in-flight requests, JSON codecs for partially decoded
 * envelopes, guards, request constructors, and storage primary-key helpers.
 *
 * @stability unstable
 * @since 4.0.0
 */
import type * as Headers from "../http/Headers.ts";
import type { ReadonlyRecord } from "../Record.ts";
import type * as Rpc from "../rpc/Rpc.ts";
import * as Schema from "../Schema.ts";
import * as SchemaTransformation from "../SchemaTransformation.ts";
import { EntityAddress } from "./EntityAddress.ts";
import { type Snowflake, SnowflakeFromBigInt } from "./Snowflake.ts";
/**
 * Type identifier used to mark runtime cluster envelope values.
 *
 * @stability unstable
 * @category type IDs
 * @since 4.0.0
 */
export declare const TypeId = "~effect/cluster/Envelope";
/**
 * Schema for a value that has already been encoded by the transport's hole
 * codec.
 *
 * **Details**
 *
 * Cluster payloads are encoded twice: the entity payload is encoded with the
 * entity RPC schema, and the result is carried opaquely inside the runner
 * envelope. This schema names that hole so the outer runner encode leaves it
 * alone. It is the identity under `Schema.toCodecJson`, so JSON, NDJSON, and
 * text transports stay wire-compatible. A binary codec compiles it as a
 * bytes leaf.
 *
 * @stability unstable
 * @category schemas
 * @since 4.0.0
 */
export declare const OpaqueHole: Schema.declare<any>;
/**
 * Union of cluster envelopes exchanged for an RPC request.
 *
 * **Details**
 *
 * An envelope is either a request, an acknowledgement for a streamed reply chunk,
 * or an interrupt signal.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type Envelope<R extends Rpc.Any> = Request<R> | AckChunk | Interrupt;
/**
 * JSON-serializable form of a cluster envelope.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export type Encoded = PartialRequestEncoded | AckChunkEncoded | InterruptEncoded;
/**
 * Helper types associated with cluster envelopes.
 *
 * @stability unstable
 * @since 4.0.0
 */
export declare namespace Envelope {
    /**
     * Envelope type for any RPC protocol.
     *
     * @stability unstable
     * @category models
     * @since 4.0.0
     */
    type Any = Envelope<any>;
}
/**
 * Runtime envelope for an RPC request addressed to a specific entity.
 *
 * **Details**
 *
 * It carries the request ID, entity address, RPC tag, decoded payload, request
 * headers, and optional tracing context.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface Request<in out Rpc extends Rpc.Any> {
    readonly [TypeId]: typeof TypeId;
    readonly _tag: "Request";
    readonly requestId: Snowflake;
    readonly address: EntityAddress;
    readonly tag: Rpc.Tag<Rpc>;
    readonly payload: Rpc.Payload<Rpc>;
    readonly headers: Headers.Headers;
    readonly traceId?: string;
    readonly spanId?: string;
    readonly sampled?: boolean;
}
declare const PartialRequest_base: Schema.Opaque<PartialRequest, Schema.Struct<{
    readonly _tag: Schema.tag<"Request">;
    readonly requestId: SnowflakeFromBigInt;
    readonly address: typeof EntityAddress;
    readonly tag: Schema.String;
    readonly payload: Schema.declare<any, any>;
    readonly headers: Schema.Headers;
    readonly traceId: Schema.optional<Schema.String>;
    readonly spanId: Schema.optional<Schema.String>;
    readonly sampled: Schema.optional<Schema.Boolean>;
}>, {}> & Omit<Schema.Struct<{
    readonly _tag: Schema.tag<"Request">;
    readonly requestId: SnowflakeFromBigInt;
    readonly address: typeof EntityAddress;
    readonly tag: Schema.String;
    readonly payload: Schema.declare<any, any>;
    readonly headers: Schema.Headers;
    readonly traceId: Schema.optional<Schema.String>;
    readonly spanId: Schema.optional<Schema.String>;
    readonly sampled: Schema.optional<Schema.Boolean>;
}>, keyof Schema.Top>;
/**
 * Schema for a request envelope before its RPC payload has been decoded.
 *
 * **Details**
 *
 * The envelope metadata is decoded, while the payload remains `unknown` until it
 * is decoded with the target RPC payload schema.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export declare class PartialRequest extends PartialRequest_base {
}
/**
 * Serialized JSON shape of a request envelope.
 *
 * **Details**
 *
 * Identifiers are encoded as strings and the RPC payload remains unknown until
 * decoded with the RPC schema.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface PartialRequestEncoded {
    readonly _tag: "Request";
    readonly requestId: string;
    readonly address: {
        readonly shardId: {
            readonly group: string;
            readonly id: number;
        };
        readonly entityType: string;
        readonly entityId: string;
    };
    readonly tag: string;
    readonly payload: unknown;
    readonly headers: ReadonlyRecord<string, string>;
    readonly traceId?: string;
    readonly spanId?: string;
    readonly sampled?: boolean;
}
declare const AckChunk_base: Schema.Class<AckChunk, Schema.Struct<{
    readonly _tag: Schema.tag<"AckChunk">;
    readonly id: SnowflakeFromBigInt;
    readonly address: typeof EntityAddress;
    readonly requestId: SnowflakeFromBigInt;
    readonly replyId: SnowflakeFromBigInt;
}>, {}>;
/**
 * Represents an envelope acknowledging receipt of a streamed reply chunk for a
 * request.
 *
 * **Details**
 *
 * The `replyId` identifies the chunk reply that has been received.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export declare class AckChunk extends AckChunk_base {
    /**
     * Marks this value as a cluster envelope for runtime guards.
     *
     * @stability unstable
     * @since 4.0.0
     */
    readonly [TypeId] = "~effect/cluster/Envelope";
    /**
     * Returns a copy of this acknowledgement associated with the supplied request id.
     *
     * @stability unstable
     * @since 4.0.0
     */
    withRequestId(requestId: Snowflake): AckChunk;
}
/**
 * Serialized JSON shape of an `AckChunk` envelope.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface AckChunkEncoded {
    readonly _tag: "AckChunk";
    readonly id: string;
    readonly address: {
        readonly shardId: {
            readonly group: string;
            readonly id: number;
        };
        readonly entityType: string;
        readonly entityId: string;
    };
    readonly requestId: string;
    readonly replyId: string;
}
declare const Interrupt_base: Schema.Class<Interrupt, Schema.Struct<{
    readonly _tag: Schema.tag<"Interrupt">;
    readonly id: SnowflakeFromBigInt;
    readonly address: typeof EntityAddress;
    readonly requestId: SnowflakeFromBigInt;
}>, {}>;
/**
 * Represents an envelope used to interrupt an in-flight entity request.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export declare class Interrupt extends Interrupt_base {
    /**
     * Marks this value as a cluster envelope for runtime guards.
     *
     * @stability unstable
     * @since 4.0.0
     */
    readonly [TypeId] = "~effect/cluster/Envelope";
    /**
     * Returns a copy of this interrupt associated with the supplied request id.
     *
     * @stability unstable
     * @since 4.0.0
     */
    withRequestId(requestId: Snowflake): Interrupt;
}
/**
 * Serialized JSON shape of an `Interrupt` envelope.
 *
 * @stability unstable
 * @category models
 * @since 4.0.0
 */
export interface InterruptEncoded {
    readonly _tag: "Interrupt";
    readonly id: string;
    readonly address: {
        readonly shardId: {
            readonly group: string;
            readonly id: number;
        };
        readonly entityType: string;
        readonly entityId: string;
    };
    readonly requestId: string;
}
/**
 * Schema for partially decoded cluster envelopes.
 *
 * **Details**
 *
 * It accepts `PartialRequest`, `AckChunk`, and `Interrupt` envelope values.
 *
 * @stability unstable
 * @category schemas
 * @since 4.0.0
 */
export declare const Partial: Schema.Union<readonly [
    typeof PartialRequest,
    typeof AckChunk,
    typeof Interrupt
]>;
/**
 * Decoded value type produced by the `Partial` envelope schema.
 *
 * @stability unstable
 * @category schemas
 * @since 4.0.0
 */
export type Partial = typeof Partial.Type;
/**
 * JSON codec for partial cluster envelopes.
 *
 * @stability unstable
 * @category schemas
 * @since 4.0.0
 */
export declare const PartialJson: Schema.Codec<AckChunk | Interrupt | PartialRequest, Encoded>;
/**
 * Schema for mutable arrays of JSON-encoded partial cluster envelopes.
 *
 * @stability unstable
 * @category schemas
 * @since 4.0.0
 */
export declare const PartialArray: Schema.mutable<Schema.$Array<Schema.Codec<AckChunk | Interrupt | PartialRequest, Encoded>>>;
/**
 * Helper types associated with request envelopes.
 *
 * @stability unstable
 * @since 4.0.0
 */
export declare namespace Request {
    /**
     * Request envelope type for any RPC protocol.
     *
     * @stability unstable
     * @category models
     * @since 4.0.0
     */
    type Any = Request<any>;
}
/**
 * Returns `true` when the supplied value is a runtime cluster envelope.
 *
 * **Details**
 *
 * The check is based on the envelope type identifier.
 *
 * @stability unstable
 * @category guards
 * @since 4.0.0
 */
export declare const isEnvelope: (u: unknown) => u is Envelope<any>;
/**
 * Constructs a runtime request envelope and attaches the envelope type identifier.
 *
 * **Details**
 *
 * Tracing fields are included only when a `traceId` is provided.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export declare const makeRequest: <Rpc extends Rpc.Any>(options: {
    readonly requestId: Snowflake;
    readonly address: EntityAddress;
    readonly tag: Rpc.Tag<Rpc>;
    readonly payload: Rpc.Payload<Rpc>;
    readonly headers: Headers.Headers;
    readonly traceId?: string | undefined;
    readonly spanId?: string | undefined;
    readonly sampled?: boolean | undefined;
}) => Request<Rpc>;
/**
 * Schema for runtime cluster envelopes recognized by their type identifier.
 *
 * @stability unstable
 * @category serialization
 * @since 4.0.0
 */
export declare const Envelope: Schema.declare<Envelope<any>, Envelope<any>>;
/**
 * Schema for runtime request envelopes.
 *
 * @stability unstable
 * @category serialization
 * @since 4.0.0
 */
export declare const Request: Schema.declare<Request.Any, Request.Any>;
/**
 * Transforms plain request data with `makeRequest` and encodes
 * request envelopes back to their raw representation.
 *
 * @stability unstable
 * @category serialization
 * @since 4.0.0
 */
export declare const RequestTransform: SchemaTransformation.Transformation<Request.Any, any>;
/**
 * Returns the storage primary key for a request envelope whose payload has a
 * primary key, or `null` when the envelope is not a keyed request.
 *
 * @stability unstable
 * @category getters
 * @since 4.0.0
 */
export declare const primaryKey: <R extends Rpc.Any>(envelope: Envelope<R>) => string | null;
/**
 * Builds a storage primary-key string from an entity address, RPC tag, and
 * payload primary-key ID.
 *
 * @stability unstable
 * @category constructors
 * @since 4.0.0
 */
export declare const primaryKeyByAddress: (options: {
    readonly address: EntityAddress;
    readonly tag: string;
    readonly id: string;
}) => string;
export {};
//# sourceMappingURL=Envelope.d.ts.map