import type { AnyProtocolMessage } from './types';
export type ProtocolEncoding = 'json' | 'msgpack';
/** Strict canonical wire data or the explicit path-aware compatibility adapter. */
export type ProtocolCodecMode = 'strict' | 'legacy';
/** Runtime schema parsing policy; independent of encoding and codec mode. */
export type ProtocolValidationLevel = 'off' | 'warning' | 'error';
/** Direction selects the complete envelope schema used for a single validation pass. */
export type ProtocolMessageDirection = 'renderer-to-simulator' | 'simulator-to-renderer' | 'any';
export interface ProtocolValidationIssue {
    code: string;
    path: Array<string | number>;
    message: string;
}
export interface ProtocolValidationWarning {
    level: 'warning';
    direction: ProtocolMessageDirection;
    message: string;
    issues: ProtocolValidationIssue[];
}
export interface ProtocolValidationOptions {
    /** Off by default; warning continues and error rejects with ProtocolValidationError. */
    level?: ProtocolValidationLevel;
    /** Validate against one directional envelope or the union of both directions. */
    direction?: ProtocolMessageDirection;
    /** Non-fatal observer used only by warning mode. Exceptions from it are ignored. */
    onWarning?: (warning: ProtocolValidationWarning) => void;
}
export interface ProtocolCodecWarning {
    code: 'legacy_alias' | 'legacy_discarded' | 'legacy_duplicate';
    message: string;
    path: string;
}
export interface ProtocolCodecOptions {
    /** Select once at session setup; it is deliberately immutable afterwards. */
    mode?: ProtocolCodecMode;
    onWarning?: (warning: ProtocolCodecWarning) => void;
    /** Runtime schema validation is opt-in and performs at most one envelope parse per message. */
    validation?: ProtocolValidationOptions;
}
export declare class ProtocolValidationError extends Error {
    readonly direction: ProtocolMessageDirection;
    readonly issues: ProtocolValidationIssue[];
    constructor(direction: ProtocolMessageDirection, message: string, issues: ProtocolValidationIssue[]);
}
/** Raised when compatibility mode cannot represent a canonical message without data loss. */
export declare class UnsupportedLegacyMessageError extends Error {
    constructor(message: string);
}
/** Generic MessagePack helpers for persistence formats outside the wire codec. */
export declare function encodeMessagePack(value: unknown): Uint8Array;
export declare function decodeMessagePack<T>(data: Uint8Array | ArrayBuffer): T;
export declare function detectProtocolEncoding(data: string | Uint8Array | ArrayBuffer): ProtocolEncoding;
/**
 * Select compatibility for a missing/older peer version and strict mode for
 * the current contract or newer. Versions are compared by parsed major/minor
 * numbers, never lexically; callers retain the selection for the session.
 */
export declare function selectProtocolCodecMode(protocolVersion: string | undefined): ProtocolCodecMode;
/**
 * Session-local protocol codec. Strict canonical mode is the default. Legacy
 * conversion is deliberately opt-in, path-aware, and limited to the explicit
 * message/field aliases implemented below: arbitrary user maps are untouched,
 * conflicting aliases reject the message, and lossy outbound conversion throws
 * UnsupportedLegacyMessageError. JSON and MessagePack share the same semantic
 * normalization and optional validation path.
 */
export declare class ProtocolCodec {
    readonly mode: ProtocolCodecMode;
    private readonly onWarning?;
    private validation;
    constructor(options?: ProtocolCodecOptions);
    /** Update validation policy without recreating the session-local compatibility state. */
    setValidation(options: ProtocolValidationOptions): void;
    /**
     * v0.2 did not echo a state-sync request id on its boundary messages.  A
     * codec is session-local so it is the one safe place to retain the one
     * outstanding legacy transaction correlation id.
     */
    private legacyStateSyncRequestId;
    encode(message: AnyProtocolMessage, encoding: ProtocolEncoding): string | Uint8Array;
    decode(data: string | Uint8Array | ArrayBuffer): AnyProtocolMessage;
    private validate;
}
export declare function createProtocolCodec(options?: ProtocolCodecOptions): ProtocolCodec;
/** Canonical convenience encoder; runtime schema validation remains opt-in. */
export declare function encodeProtocolMessage(message: AnyProtocolMessage, encoding: ProtocolEncoding, options?: ProtocolCodecOptions): string | Uint8Array;
/** Canonical convenience decoder; runtime schema validation remains opt-in. */
export declare function decodeProtocolMessage(data: string | Uint8Array | ArrayBuffer, options?: ProtocolCodecOptions): AnyProtocolMessage;
//# sourceMappingURL=codec.d.ts.map