import { z } from "zod";
import { type TrapCondition } from "./traps.js";
export declare const INSTRUCTION_CATEGORIES: readonly ["control", "numeric", "parametric", "variable", "table", "memory", "ref", "i31", "struct", "array", "extern", "vec"];
export type InstructionCategory = (typeof INSTRUCTION_CATEGORIES)[number];
export declare const WASM_VERSIONS: readonly ["1.0", "2.0", "3.0"];
export type WasmVersion = (typeof WASM_VERSIONS)[number];
/** A single instruction record exposed by the MCP tools. */
export interface InstructionRecord {
    /** Lowercase wasm syntax mnemonic, e.g. `"i32.add"`, `"br_if"`. */
    mnemonic: string;
    /**
     * Binary opcode encoding as a byte sequence. Single-byte for
     * classic opcodes (`[0x6A]` for `i32.add`); multi-byte for
     * prefix-encoded families (`[0xFD, 0x89, 0x02]` for vector
     * `i8x16.relaxed_laneselect`).
     */
    opcodes: number[];
    /** Spec category this instruction belongs to. */
    category: InstructionCategory;
    /**
     * Minimum spec version that introduced this instruction.
     * `"1.0"` (MVP), `"2.0"` (Wasm 2), `"3.0"` (Wasm 3 — exception
     * handling, GC, threads, tail calls, relaxed SIMD).
     */
    version: WasmVersion;
    /**
     * Stack type signature. `params_raw` / `results_raw` are the raw
     * LaTeX strings as upstream wrote them (e.g. `"[t_1^\\ast~\\I32]"`);
     * the runtime keeps them verbatim because the full stack-type
     * grammar (polymorphic, type variables, vector splats) is richer
     * than a flat list. A future release may add a fully decoded
     * `params` / `results` alongside.
     */
    signature: {
        params_raw: string;
        results_raw: string;
    };
    /**
     * Fragment identifiers within the rendered spec — e.g.
     * `valid-br_if`, `exec-br_if`. Stable across spec releases.
     */
    anchors: {
        validation: string;
        execution: string;
    };
    /**
     * Full URLs into the rendered spec at
     * `https://webassembly.github.io/spec/core/`. Built from `anchors`
     * by `instructionUrl`.
     */
    urls: {
        validation: string;
        execution: string;
    };
    /**
     * Whether this instruction can trap at runtime. `true` iff `traps`
     * is non-empty. A quick boolean for "does this trap?" without
     * inspecting the conditions.
     */
    can_trap: boolean;
    /**
     * The runtime conditions under which this instruction traps, each
     * with the spec's canonical trap name. Empty for instructions that
     * never trap (e.g. `i32.add`). Derived at build time from the
     * spec's operator partiality + trapping instruction families; see
     * `src/parser/traps.ts`.
     */
    traps: TrapCondition[];
}
export declare const InstructionRecordSchema: z.ZodObject<{
    mnemonic: z.ZodString;
    opcodes: z.ZodArray<z.ZodNumber>;
    category: z.ZodEnum<{
        array: "array";
        control: "control";
        extern: "extern";
        i31: "i31";
        memory: "memory";
        numeric: "numeric";
        parametric: "parametric";
        ref: "ref";
        struct: "struct";
        table: "table";
        variable: "variable";
        vec: "vec";
    }>;
    version: z.ZodEnum<{
        "1.0": "1.0";
        "2.0": "2.0";
        "3.0": "3.0";
    }>;
    signature: z.ZodObject<{
        params_raw: z.ZodString;
        results_raw: z.ZodString;
    }, z.core.$strip>;
    anchors: z.ZodObject<{
        validation: z.ZodString;
        execution: z.ZodString;
    }, z.core.$strip>;
    urls: z.ZodObject<{
        validation: z.ZodURL;
        execution: z.ZodURL;
    }, z.core.$strip>;
    can_trap: z.ZodBoolean;
    traps: z.ZodArray<z.ZodObject<{
        condition: z.ZodString;
        name: z.ZodString;
    }, z.core.$strip>>;
}, z.core.$strip>;
export interface RawInstruction {
    version: number | null;
    name: string | null;
    opcode: string | null;
    type: string | null;
    validation: string | null;
    execution: string | null;
    operator: string | null;
    validation2: string | null;
    execution2: string | null;
}
export interface RawMacro {
    body: string;
    kind: "instruction" | "type" | "other";
    category: string | null;
    section: string;
    anchor: string;
}
export interface RawDump {
    instructions: RawInstruction[];
    macros: Record<string, RawMacro>;
}
/** Build a full anchor URL into the rendered spec. */
export declare function instructionUrl(anchor: string): string;
/** Parse `\hex{0C}` or `\hex{FD}~~\hex{89}~~\hex{02}` into a byte array. */
export declare function parseOpcode(latex: string): number[];
/**
 * Resolve a LaTeX name like `\I32.\ADD` or `\BR~l` into the wasm
 * syntax mnemonic. The leading `\` macros are expanded via the
 * macro table; everything from the first `~` onwards is dropped
 * (immediate operands aren't part of the mnemonic).
 */
export declare function resolveMnemonic(nameLatex: string, macros: Record<string, RawMacro>): string | null;
/** Split a `type` LaTeX string like `[a] \to [b]` into params/results. */
export declare function parseSignature(typeLatex: string): {
    params_raw: string;
    results_raw: string;
};
/**
 * Resolve the category of an instruction by finding its primary
 * macro in the name and looking up its instruction-category tag.
 * For `\I32.\ADD` the primary macro is `\ADD` (an instruction macro);
 * `\I32` is a type macro and contributes no category.
 */
export declare function resolveCategory(nameLatex: string, macros: Record<string, RawMacro>): InstructionCategory | null;
export interface NormalizeReport {
    records: InstructionRecord[];
    skipped: {
        /** Opcode slots upstream marks as reserved (version 0.0, name null). */
        reserved: number;
        /**
         * Structural delimiters like `else` and `end` — listed in the
         * appendix for opcode-coverage reasons but with no validation or
         * execution prose, since they're not standalone instructions.
         */
        structural: {
            name: string;
            opcode: string | null;
        }[];
        missing_macro: {
            name: string;
            opcode: string | null;
        }[];
        missing_category: {
            name: string;
            opcode: string | null;
        }[];
        incomplete: {
            name: string | null;
            opcode: string | null;
            reason: string;
        }[];
    };
}
/**
 * Normalise a raw dump into clean instruction records. Reserved /
 * inactive opcodes (version 0.0 with `name: null`) are skipped and
 * reported. Any instruction whose macro / category can't be
 * resolved is also skipped and reported so the build can surface
 * upstream changes the parser doesn't yet handle.
 */
export declare function normalizeInstructions(dump: RawDump): NormalizeReport;