/**
 * Payload compression utilities for transparent gzip/brotli compression
 * at the storage layer. Uses a 2-byte header (magic byte `0xC1` + algorithm
 * byte) for format detection and cross-algorithm reads.
 *
 * @module core/compression
 */
/**
 * Identifies the compression algorithm applied to storage payloads.
 * `'gzip'` and `'brotli'` compress before storage; `'none'` disables
 * compression. Pass to {@link EngineOptions.compression} or to
 * {@link createCompressor}.
 *
 * @example
 * ```ts
 * import { createCompressor, type CompressionAlgorithm } from '@lostgradient/weft';
 *
 * const algorithm: CompressionAlgorithm = 'brotli';
 * const compressor = createCompressor(algorithm);
 * const data = new TextEncoder().encode('payload'.repeat(100));
 * const compressed = compressor.compress(data);
 * console.log(compressed instanceof Uint8Array); // true
 * ```
 */
export type CompressionAlgorithm = 'gzip' | 'brotli' | 'none';
/**
 * Configuration for storage-layer compression. Pass as
 * {@link EngineOptions.compression} to enable payload compression on
 * checkpoints and activity results. `threshold` prevents compression of
 * small payloads (default 4 096 bytes); `algorithm` picks the codec.
 *
 * @example
 * ```ts
 * import { Engine, type CompressionOptions } from '@lostgradient/weft';
 *
 * const compression: CompressionOptions = {
 *   algorithm: 'brotli',
 *   threshold: 8_192,
 * };
 * const engine = new Engine({ compression });
 * void engine;
 * ```
 */
export type CompressionOptions = {
    /** Minimum size in bytes before compression kicks in. Default: 4096. */
    threshold?: number;
    /** Algorithm to use. Default: 'gzip'. */
    algorithm?: CompressionAlgorithm;
};
/**
 * A compression implementation returned by {@link createCompressor} or
 * {@link createBunCompressor}. The `compress` method accepts raw bytes
 * and returns compressed bytes (or a promise). Provide a custom
 * `Compressor` if you need to swap in a different algorithm.
 *
 * @example
 * ```ts
 * import { createCompressor, type Compressor } from '@lostgradient/weft';
 *
 * const compressor: Compressor = createCompressor('gzip');
 * const payload = new TextEncoder().encode('hello'.repeat(200));
 * const compressed = await compressor.compress(payload);
 * console.log(compressor.algorithm);            // 'gzip'
 * console.log(compressed.byteLength < payload.byteLength); // true
 * ```
 */
export type Compressor = {
    compress(data: Uint8Array): Uint8Array | Promise<Uint8Array>;
    readonly algorithm: CompressionAlgorithm;
};
/**
 * Create a compressor backed by the portable runtime layer.
 *
 * - `gzip`: uses Bun's native gzip when available, otherwise `node:zlib`
 * - `brotli`: uses `node:zlib` brotli (available in both Bun and Node)
 * - `none`: pass-through (no compression)
 *
 * @example
 * ```ts
 * import { createBunCompressor } from '@lostgradient/weft';
 *
 * const compressor = createBunCompressor('gzip');
 * const data = new TextEncoder().encode('hello world'.repeat(100));
 * const compressed = await compressor.compress(data);
 * console.log(compressed.byteLength < data.byteLength); // true
 * ```
 */
export declare function createBunCompressor(algorithm: CompressionAlgorithm): Compressor;
/**
 * Create a compressor. Preferred portable factory — delegates to the runtime
 * abstraction layer for gzip and brotli implementations.
 *
 * @example
 * ```ts
 * import { createCompressor } from '@lostgradient/weft';
 *
 * const gzip = createCompressor('gzip');
 * const brotli = createCompressor('brotli');
 * const none = createCompressor('none');
 *
 * const payload = new TextEncoder().encode('workflow state'.repeat(50));
 * const compressed = gzip.compress(payload);
 * console.log(compressed instanceof Uint8Array); // true
 * ```
 */
export declare function createCompressor(algorithm: CompressionAlgorithm): Compressor;
/**
 * Compress a payload, prepending a 2-byte header: magic byte (`0xC1`) +
 * algorithm byte.
 *
 * If the data is below the threshold or the algorithm is `'none'`, the payload
 * is stored with a `[0xC1, 0x00]` header and no compression is applied.
 */
export declare function compressPayload(data: Uint8Array, compressor: Compressor, threshold: number): Promise<Uint8Array>;
/**
 * Decompress a payload by reading the 2-byte header (magic + algorithm).
 *
 * - `[0xC1, 0x00]` → uncompressed, return the rest as-is
 * - `[0xC1, 0x01]` → gzip-compressed, decompress
 * - `[0xC1, 0x02]` → brotli-compressed, decompress
 *
 * Empty payloads are valid only when framed as `[0xC1, 0x00]`. Unframed empty
 * input is rejected because it cannot prove which storage format produced it.
 */
export declare function decompressPayload(data: Uint8Array): Promise<Uint8Array>;
/** Resolve partial compression options into a fully specified configuration. */
export declare function resolveCompressionOptions(options?: CompressionOptions): Required<CompressionOptions>;