import type { EdictHostAdapter } from "../codegen/host-adapter.js";
/** Mutable runtime state shared by all host functions during one execution. */
export interface RuntimeState {
    /** Captured stdout output parts. */
    outputParts: string[];
    /** Late-bound WASM instance — set after instantiation. */
    instance: WasmInstance | null;
    /** Optional sandbox directory for file IO. If unset, readFile/writeFile return Err. */
    sandboxDir?: string;
    /** Optional list of allowed hostnames for HTTP requests. If unset, all hosts are allowed. */
    allowedHosts?: string[];
}
interface WasmInstance {
    readonly exports: {
        [key: string]: unknown;
        memory?: {
            readonly buffer: ArrayBuffer;
        };
    };
}
/** Typed error thrown when a host-side heap allocation exceeds WASM memory bounds. */
export declare class EdictOomError extends Error {
    heapUsed: number;
    heapLimit: number;
    constructor(heapUsed: number, heapLimit: number);
}
/**
 * Context passed to every host builtin factory function.
 * Bundles state, adapter, and shared encoder/decoder so each domain
 * doesn't need to create its own or take a different arg signature.
 */
export interface HostContext {
    state: RuntimeState;
    adapter: EdictHostAdapter;
    encoder: TextEncoder;
    decoder: TextDecoder;
}
export declare function getMemoryBuffer(state: RuntimeState): ArrayBuffer;
/**
 * Centralized heap allocator with bounds checking.
 * Allocates `size` bytes (8-byte aligned) from the bump allocator,
 * throwing EdictOomError if the allocation would exceed WASM memory.
 */
export declare function allocateHeap(state: RuntimeState, size: number): number;
/**
 * Reset the heap to its initial state (full arena wipe).
 * All heap-allocated data (records, arrays, strings, closures) is invalidated.
 * Use between logical execution phases on a reused WASM instance.
 */
export declare function resetHeap(state: RuntimeState): void;
/**
 * Read current heap utilization — bytes used and total available.
 * Zero-cost (reads one WASM global + memory buffer size).
 */
export declare function getHeapUsage(state: RuntimeState): {
    used: number;
    total: number;
};
/**
 * Mark/release wrapper — saves __heap_ptr, runs fn, restores.
 * Useful for host-side code that creates temporary WASM heap allocations
 * (e.g., intermediate string processing) that should be reclaimed after.
 */
export declare function withTemporaryHeap<T>(state: RuntimeState, fn: () => T): T;
/**
 * Read a length-prefixed string from WASM memory.
 * Memory format: [len:i32][data:bytes] at the given pointer.
 * Returns the decoded JS string.
 */
export declare function readString(state: RuntimeState, ptr: number, decoder: TextDecoder): string;
/**
 * Write a string result into WASM memory as length-prefixed format:
 * [len:i32][data:bytes]. Advances __heap_ptr (8-byte aligned).
 * Returns ptr to the length header.
 */
export declare function writeStringResult(state: RuntimeState, str: string, encoder: TextEncoder): number;
/**
 * Allocate a new array on the WASM heap: [length: i32][elem0: i32]...
 * Advances __heap_ptr (8-byte aligned) and returns the new array pointer.
 */
export declare function writeArrayResult(state: RuntimeState, elements: number[]): number;
/**
 * Allocate a Result value on the WASM heap: [tag: i32][pad(4)][value: i32][pad(4)]
 * tag=0 means Ok, tag=1 means Err. Total size = 16 bytes (matches enum layout).
 * Returns the pointer to the Result pair.
 */
export declare function writeResultValue(state: RuntimeState, tag: number, value: number): number;
/**
 * Format a Date using strftime-style tokens.
 * Supported: %Y (year), %m (month 01-12), %d (day 01-31),
 *            %H (hour 00-23), %M (min 00-59), %S (sec 00-59), %% (literal %)
 */
export declare function formatDateString(date: Date, fmt: string): string;
export {};
//# sourceMappingURL=host-helpers.d.ts.map