xqvm 0.2.0

// Copyright (C) 2026 Postquant Labs Incorporated
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

use crate::bytecode::codec;
use crate::{Instruction, InstructionBuilder, Program, Register};

use super::error::VerifierError;
use super::jump_target::JumpTargetPhase;
use super::loop_nesting::LoopNestingPhase;
use super::phase::{Phase, Verifier};
use super::register_type::RegisterTypePhase;
use super::stack_depth::StackDepthPhase;
use super::structural::StructuralPhase;
use super::verify;

fn bytes(instrs: &[Instruction]) -> Vec<u8> {
    instrs.iter().flat_map(codec::encode).collect()
}

// --- StructuralPhase ---

#[test]
fn structural_accepts_valid_stream() {
    let mut b = InstructionBuilder::new();
    let _ = b.emit_push(1).emit_push(2).emit_add().emit_halt();
    assert!(StructuralPhase.run(&b.build().unwrap()).is_ok());
}

#[test]
fn structural_rejects_truncated_push2() {
    // PUSH2 (0x12) needs 2 operand bytes; supply only 1.
    let prog = Program::new(vec![0x12, 0x00]);
    let err = StructuralPhase.run(&prog).unwrap_err();
    assert_eq!(err.variant_name(), "TruncatedInstruction");
}

#[test]
fn structural_rejects_reserved_opcode() {
    // 0x0D is the reserved gap in the opcode table.
    let err = StructuralPhase.run(&Program::new(vec![0x0D])).unwrap_err();
    assert_eq!(err.variant_name(), "BadOpcode");
}

// --- JumpTargetPhase ---

#[test]
fn jump_target_accepts_valid_label() {
    // TARGET(.0) then JUMP1 0.
    let code = bytes(&[
        Instruction::Target {},
        Instruction::Jump1 { label: 0 },
        Instruction::Halt {},
    ]);
    assert!(JumpTargetPhase.run(&Program::new(code)).is_ok());
}

#[test]
fn jump1_to_nonexistent_label() {
    // No TARGETs; label 0 is undefined.
    let code = bytes(&[Instruction::Jump1 { label: 0 }, Instruction::Halt {}]);
    let err = JumpTargetPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UndefinedJumpTarget");
}

#[test]
fn jumpi1_to_nonexistent_label() {
    let code = bytes(&[Instruction::JumpI1 { label: 0 }, Instruction::Halt {}]);
    let err = JumpTargetPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UndefinedJumpTarget");
}

#[test]
fn jump2_to_nonexistent_label() {
    let code = bytes(&[Instruction::Jump2 { label: 0 }, Instruction::Halt {}]);
    let err = JumpTargetPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UndefinedJumpTarget");
}

#[test]
fn jump2_label_out_of_range_with_one_target() {
    // One TARGET (id 0); JUMP2 label=1 is out of range.
    let code = bytes(&[
        Instruction::Target {},
        Instruction::Jump2 { label: 1 },
        Instruction::Halt {},
    ]);
    let err = JumpTargetPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UndefinedJumpTarget");
}

// --- LoopNestingPhase ---

#[test]
fn loop_nesting_accepts_balanced_range() {
    let mut b = InstructionBuilder::new();
    let _ = b
        .emit_push(0)
        .emit_push(3)
        .emit_range()
        .emit_next()
        .emit_halt();
    assert!(LoopNestingPhase.run(&b.build().unwrap()).is_ok());
}

#[test]
fn unmatched_range_at_eof() {
    let code = bytes(&[Instruction::Range {}, Instruction::Halt {}]);
    let err = LoopNestingPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UnmatchedLoop");
}

#[test]
fn next_outside_any_loop() {
    let code = bytes(&[Instruction::Next {}, Instruction::Halt {}]);
    let err = LoopNestingPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "NoActiveLoop");
}

#[test]
fn lval_outside_loop() {
    let code = bytes(&[Instruction::LVal { reg: Register(0) }, Instruction::Halt {}]);
    let err = LoopNestingPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "NoActiveLoop");
}

#[test]
fn lidx_outside_loop() {
    let code = bytes(&[Instruction::Lidx { reg: Register(0) }, Instruction::Halt {}]);
    let err = LoopNestingPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "NoActiveLoop");
}

#[test]
fn nested_loops_balanced() {
    // RANGE { RANGE { NEXT } NEXT } HALT
    let code = bytes(&[
        Instruction::Range {},
        Instruction::Range {},
        Instruction::Next {},
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    assert!(LoopNestingPhase.run(&Program::new(code)).is_ok());
}

#[test]
fn nested_loops_outer_unmatched() {
    // RANGE { RANGE { NEXT } HALT -- outer RANGE has no NEXT
    let code = bytes(&[
        Instruction::Range {},
        Instruction::Range {},
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    let err = LoopNestingPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "UnmatchedLoop");
    // Outermost opener is at offset 0.
    assert!(matches!(
        err,
        VerifierError::UnmatchedLoop {
            offset: 0,
            depth: 1
        }
    ));
}

// --- RegisterTypePhase ---

#[test]
fn reg_type_stow_then_load_ok() {
    let code = bytes(&[
        Instruction::Push1 { val: [7] },
        Instruction::Stow { reg: Register(0) },
        Instruction::Load { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code)).is_ok());
}

#[test]
fn reg_type_load_unset_register_is_error() {
    let code = bytes(&[Instruction::Load { reg: Register(1) }, Instruction::Halt {}]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "ReadUnsetRegister");
}

#[test]
fn reg_type_output_unset_register_is_error() {
    let code = bytes(&[
        Instruction::Push1 { val: [0] }, // output slot index
        Instruction::Output { reg: Register(2) },
        Instruction::Halt {},
    ]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "ReadUnsetRegister");
}

#[test]
fn reg_type_drop_clears_register() {
    // STOW r0, DROP r0, LOAD r0 -- Load after Drop should error.
    let code = bytes(&[
        Instruction::Push1 { val: [1] },
        Instruction::Stow { reg: Register(0) },
        Instruction::Drop { reg: Register(0) },
        Instruction::Load { reg: Register(0) },
        Instruction::Halt {},
    ]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "ReadUnsetRegister");
}

#[test]
fn reg_type_wrong_type_for_load() {
    // BQMX writes Model to r0; LOAD expects Int.
    let code = bytes(&[
        Instruction::Push1 { val: [4] }, // size
        Instruction::Bqmx { reg: Register(0) },
        Instruction::Load { reg: Register(0) },
        Instruction::Halt {},
    ]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "RegisterTypeMismatch");
}

#[test]
fn reg_type_input_satisfies_any_read() {
    // INPUT writes Any; subsequent LOAD should not error.
    let code = bytes(&[
        Instruction::Push1 { val: [0] }, // calldata index
        Instruction::Input { reg: Register(0) },
        Instruction::Load { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code)).is_ok());
}

#[test]
fn reg_type_bqmx_then_getline_ok() {
    let code = bytes(&[
        Instruction::Push1 { val: [4] },
        Instruction::Bqmx { reg: Register(0) },
        Instruction::Push1 { val: [0] },
        Instruction::GetLine { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code)).is_ok());
}

#[test]
fn reg_type_veci_then_getline_mismatch() {
    // VECI writes VecInt to r0; GETLINE expects Model.
    let code = bytes(&[
        Instruction::VecI { reg: Register(0) },
        Instruction::Push1 { val: [0] },
        Instruction::GetLine { reg: Register(0) },
        Instruction::Halt {},
    ]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "RegisterTypeMismatch");
}

#[test]
fn reg_type_energy_wrong_sample_slot() {
    // BQMX r0=Model, BSMX r1=Sample, ENERGY with model=r1, sample=r0.
    // r1 is Sample (ok for model slot? no -- model slot requires Model).
    let code = bytes(&[
        Instruction::Push1 { val: [2] },
        Instruction::Bqmx { reg: Register(0) }, // r0 = Model
        Instruction::Push1 { val: [2] },
        Instruction::Bsmx { reg: Register(1) }, // r1 = Sample
        // Energy with model=r1(Sample) -- should fail
        Instruction::Energy {
            model: Register(1),
            sample: Register(0),
        },
        Instruction::Halt {},
    ]);
    let err = RegisterTypePhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "RegisterTypeMismatch");
}

#[test]
fn reg_type_correct_energy_program() {
    let code = bytes(&[
        Instruction::Push1 { val: [2] },
        Instruction::Bqmx { reg: Register(0) }, // r0 = Model
        Instruction::Push1 { val: [2] },
        Instruction::Bsmx { reg: Register(1) }, // r1 = Sample
        Instruction::Energy {
            model: Register(0),
            sample: Register(1),
        },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code)).is_ok());
}

#[test]
fn reg_type_veclen_accepts_vec_xqmx() {
    let code = bytes(&[
        Instruction::VecX { reg: Register(0) }, // r0 = VecXqmx
        Instruction::VecLen { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code)).is_ok());
}

#[test]
fn reg_type_resize_accepts_model_or_sample() {
    // RESIZE accepts both Model and Sample via the Grid requirement.
    let code_model = bytes(&[
        Instruction::Push1 { val: [4] },
        Instruction::Bqmx { reg: Register(0) },
        Instruction::Push1 { val: [8] },
        Instruction::Push1 { val: [8] },
        Instruction::Resize { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code_model)).is_ok());

    let code_sample = bytes(&[
        Instruction::Push1 { val: [4] },
        Instruction::Bsmx { reg: Register(0) },
        Instruction::Push1 { val: [8] },
        Instruction::Push1 { val: [8] },
        Instruction::Resize { reg: Register(0) },
        Instruction::Halt {},
    ]);
    assert!(RegisterTypePhase.run(&Program::new(code_sample)).is_ok());
}

// --- Verifier composition ---

#[test]
fn default_verifier_passes_valid_program() {
    let mut b = InstructionBuilder::new();
    let _ = b.emit_push(10).emit_push(32).emit_add().emit_halt();
    assert!(verify(&b.build().unwrap()).is_ok());
}

#[test]
fn custom_verifier_only_jump_phase() {
    // An unmatched RANGE is not caught if LoopNestingPhase is not included.
    let code = bytes(&[Instruction::Range {}, Instruction::Halt {}]);
    let result = Verifier::new()
        .with_phase(JumpTargetPhase)
        .run(&Program::new(code));
    assert!(
        result.is_ok(),
        "jump-only verifier should not catch loop errors"
    );
}

#[test]
fn custom_verifier_structural_then_loop() {
    // A bad opcode is caught by StructuralPhase before LoopNestingPhase runs.
    let prog = Program::new(vec![0x0D]);
    let err = Verifier::new()
        .with_phase(StructuralPhase)
        .with_phase(LoopNestingPhase)
        .run(&prog)
        .unwrap_err();
    assert_eq!(err.variant_name(), "BadOpcode");
}

// --- StackDepthPhase ---

#[test]
fn stack_depth_mismatch_at_conditional_join() {
    // PUSH1(1); JUMPI1(label=0); PUSH1(2); TARGET(label=0); HALT
    // Taken (JUMPI1 fires, depth 0) vs fall-through (depth 1) at TARGET.
    let mut b = InstructionBuilder::new();
    let label = b.label();
    let _ = b
        .emit_push(1)
        .emit_jump_if(label) // taken: depth 0
        .emit_push(2) // fall-through only: depth 1
        .place(label)
        .unwrap()
        .emit_halt();
    let err = StackDepthPhase.run(&b.build().unwrap()).unwrap_err();
    assert_eq!(err.variant_name(), "StackDepthMismatch");
}

#[test]
fn stack_effect_underflow_on_pop_empty() {
    // POP with nothing on the stack.
    let code = bytes(&[Instruction::Pop {}, Instruction::Halt {}]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "StackUnderflow");
}

#[test]
fn stack_effect_underflow_on_binary_op() {
    // ADD on an empty stack: delta = -1, depth = 0 → depth + delta < 0 → underflow.
    // Note: the conservative scan uses net delta, so ADD with depth=1 (one item) would
    // not be caught here -- that is a documented limitation of the linear scan.
    let code = bytes(&[Instruction::Add {}, Instruction::Halt {}]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "StackUnderflow");
}

#[test]
fn stack_effect_valid_push_pop() {
    let code = bytes(&[
        Instruction::Push1 { val: [42] },
        Instruction::Pop {},
        Instruction::Halt {},
    ]);
    assert!(StackDepthPhase.run(&Program::new(code)).is_ok());
}

#[test]
fn stack_effect_sclr_resets_depth() {
    // PUSH, PUSH, SCLR, then POP would underflow — SCLR drops both items.
    let code = bytes(&[
        Instruction::Push1 { val: [1] },
        Instruction::Push1 { val: [2] },
        Instruction::Sclr {},
        Instruction::Pop {},
        Instruction::Halt {},
    ]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "StackUnderflow");
}

#[test]
fn stack_effect_sclr_leaves_clean_stack() {
    // PUSH, PUSH, SCLR -- depth is 0 afterwards; HALT is fine.
    let code = bytes(&[
        Instruction::Push1 { val: [1] },
        Instruction::Push1 { val: [2] },
        Instruction::Sclr {},
        Instruction::Halt {},
    ]);
    assert!(StackDepthPhase.run(&Program::new(code)).is_ok());
}

// SCLR inside a loop resets the depth counter to 0 unconditionally. If the
// depth at loop body entry was N > 0, the exit depth will be 0 != N and
// LoopStackImbalance is raised. The error message says "loop has non-zero
// stack effect", which is technically correct but the root cause is a global
// stack reset mid-iteration rather than an unmatched push or pop.
#[test]
fn sclr_inside_loop_body_causes_imbalance() {
    let code = bytes(&[
        Instruction::Push1 { val: [1] }, // extra item -- entry depth before RANGE = 3
        Instruction::Push1 { val: [0] }, // start
        Instruction::Push1 { val: [3] }, // count
        Instruction::Range {},           // pops 2; entry depth recorded = 1
        Instruction::Sclr {},            // resets depth to 0; exit depth = 0 != 1
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "LoopStackImbalance");
}

#[test]
fn loop_body_neutral_passes() {
    // PUSH start, PUSH count, RANGE, NEXT, HALT -- body is empty, net effect = 0.
    let code = bytes(&[
        Instruction::Push1 { val: [0] },
        Instruction::Push1 { val: [3] },
        Instruction::Range {},
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    assert!(StackDepthPhase.run(&Program::new(code)).is_ok());
}

#[test]
fn loop_body_push_causes_imbalance() {
    // Loop body does a PUSH but no matching POP: each iteration leaks one item.
    let code = bytes(&[
        Instruction::Push1 { val: [0] },
        Instruction::Push1 { val: [3] },
        Instruction::Range {},
        Instruction::Push1 { val: [99] }, // unmatched push inside loop
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "LoopStackImbalance");
}

#[test]
fn loop_body_pop_causes_imbalance() {
    // Loop body pops the loop's own operands off the stack.
    // Entry depth after RANGE's -2 = 0. POP inside would underflow -- caught as underflow.
    // Instead use a loop that has 1 extra item before RANGE.
    // depth before RANGE = 3 (start=0, count=3, extra=1 → no, RANGE pops 2 → depth=1)
    // body pops 1 → depth=0, NEXT expects depth=1 → LoopStackImbalance
    let code = bytes(&[
        Instruction::Push1 { val: [1] }, // extra item
        Instruction::Push1 { val: [0] }, // start
        Instruction::Push1 { val: [3] }, // count
        Instruction::Range {},           // pops 2, depth = 1
        Instruction::Pop {},             // pops extra, depth = 0
        Instruction::Next {},            // expects depth = 1
        Instruction::Halt {},
    ]);
    let err = StackDepthPhase.run(&Program::new(code)).unwrap_err();
    assert_eq!(err.variant_name(), "LoopStackImbalance");
}

#[test]
fn nested_loops_both_neutral() {
    let code = bytes(&[
        Instruction::Push1 { val: [0] },
        Instruction::Push1 { val: [2] },
        Instruction::Range {},
        Instruction::Push1 { val: [0] },
        Instruction::Push1 { val: [2] },
        Instruction::Range {},
        Instruction::Next {},
        Instruction::Next {},
        Instruction::Halt {},
    ]);
    assert!(StackDepthPhase.run(&Program::new(code)).is_ok());
}

#[test]
fn stack_effect_on_all_variants_does_not_panic() {
    // Smoke test: stack_effect() must not panic for any instruction variant.
    use crate::bytecode::types::Register;
    let instrs: &[Instruction] = &[
        Instruction::Target {},
        Instruction::Jump1 { label: 0 },
        Instruction::JumpI1 { label: 0 },
        Instruction::Nop {},
        Instruction::Halt {},
        Instruction::Sclr {},
        Instruction::Add {},
        Instruction::Energy {
            model: Register(0),
            sample: Register(1),
        },
    ];
    for instr in instrs {
        let _ = instr.stack_effect();
    }
}