// The WebAssembly interface of a wasmQ module (quantum-wasmq.md).
// SPDX-License-Identifier: Apache-2.0
//
// A wasmQ module is a core WebAssembly module (quantum-wasmq.md §3). Its exports are the
// Component Model's canonical lowering of the functions below, so a component host can
// wrap it, and a host of this profile calls it directly. An OpenQASM 3 `extern` lowers to
// one of two forms (§5.2): scalar, every argument and the result at most 64 bits, each a
// u64 or s64; or list, each `bit[n]` a list<u8>, the lowest bit first. A module with a
// list-form export or a prior exports its memory as `memory`, where a host reaches it.
// In the profile's second version (§11) an argument may also be an `angle[k]`, which
// lowers as a `uint[k]` does: one u64, the `m` of the angle `2πm/2^k`, in either form.
//
// The direction is the hardware's: the quantum program calls the module. A module
// imports nothing (§3.2), so this package has no interface a module imports.

package wai:wasmq@0.1.0;

/// What a receipt names when a run stops (§6.2).
interface receipt {
    enum fault-reason {
        unreachable,
        memory-out-of-bounds,
        table-out-of-bounds,
        indirect-call-null,
        indirect-call-type,
        integer-divide-by-zero,
        integer-overflow,
        invalid-conversion-to-integer,
        fuel-exhausted,
        stack-exhausted,
        bad-result,
    }
}

/// A module's lifecycle (§5.3), every export optional: the seed, then each prior in the
/// order the contract lists them, then `init`, each metered.
world module {
    /// The seed for this instance: the run's, or the shot's when an instance lives for a shot.
    export wasmq-seed: func(seed: u64);
    /// Prior `index` of the module's priors, its bytes as the contract pins them.
    export wasmq-prior: func(index: u32, bytes: list<u8>);
    export init: func();
}

/// The reference decoder (§8.1): the engine's qLDPC decoder. Prior 0 is a code's parity
/// checks; a syndrome goes in, a correction comes out.
world qldpc-decoder {
    include module;
    /// The list form: `extern decode(bit[m]) -> bit[n];` for any code.
    export decode: func(syndrome: list<u8>) -> list<u8>;
    /// The scalar form: `extern decode64(bit[m]) -> bit[n];`, m and n at most 64.
    export decode64: func(syndrome: u64) -> u64;
}

/// The reference planner (§8.2): the engine's neutral-atom rearrangement. Prior 0 is the
/// target register; an occupancy goes in, the moves come out as masks.
world atom-planner {
    export wasmq-prior: func(index: u32, bytes: list<u8>);
    /// The list form: `extern plan(bit[n]) -> bit[2n+1];`.
    export plan: func(occupancy: list<u8>) -> list<u8>;
    /// The scalar form, for at most 31 sites.
    export plan64: func(occupancy: u64) -> u64;
}

/// A callout of the profile's second version that takes an angle (§11.1):
/// `extern f(angle[8], uint[8]) -> bit[16];`, the angle the `m` of `2πm/2^8` as a u64, its
/// integer as a u64, and its result in the low 16 bits of a u64.
world angle-callout {
    export f: func(angle: u64, value: u64) -> u64;
}