Function program_from_bytecode

xqvm_py/program.py:100–160

Decode ``.xqb`` bytecode into an executable ``Program``. Parses and validates the 15-byte XQBC header (magic, version, length, CRC-32), then decodes the instruction stream. No FFI dependency. Header layout:: 0..4 b"XQBC" magic 4 version: u8 format

(bytecode: bytes, name: str = "")

def program_from_bytecode(bytecode: bytes, name: str = "") -> Program:
    """Decode ``.xqb`` bytecode into an executable ``Program``.

    Parses and validates the 15-byte XQBC header (magic, version, length,
    CRC-32), then decodes the instruction stream.  No FFI dependency.

    Header layout::

        0..4   b"XQBC"          magic
        4      version: u8      format version (currently 1)
        5      input_slots: u8  count of INPUT instructions
        6      output_slots: u8 count of OUTPUT instructions
        7..11  code_len: u32 BE byte length of instruction stream
        11..15 crc32: u32 BE    CRC-32/ISO-HDLC of instruction stream
        15+    instruction stream

    Raises:
        ValueError: if the header is missing, malformed, or the checksum
            does not match.
    """
    import struct
    import zlib

    if len(bytecode) < _XQBC_HEADER_SIZE:
        raise ValueError(f"not an XQBC file: too short ({len(bytecode)} bytes, need {_XQBC_HEADER_SIZE})")

    magic = bytecode[:4]
    if magic != _XQBC_MAGIC:
        raise ValueError(f"not an XQBC file: wrong magic {magic!r}")

    version = bytecode[4]
    if version != _XQBC_VERSION:
        raise ValueError(f"unsupported XQBC version {version} (expected {_XQBC_VERSION})")

    (code_len,) = struct.unpack_from(">I", bytecode, 7)
    (expected_crc,) = struct.unpack_from(">I", bytecode, 11)

    code = bytecode[_XQBC_HEADER_SIZE:]
    if len(code) != code_len:
        raise ValueError(f"XQBC length mismatch: header says {code_len} bytes, got {len(code)}")

    actual_crc = zlib.crc32(code) & 0xFFFF_FFFF
    if actual_crc != expected_crc:
        raise ValueError(f"XQBC CRC-32 mismatch: expected 0x{expected_crc:08X}, computed 0x{actual_crc:08X}")

    instructions: list[Instruction] = []
    pos = 0
    while pos < len(code):
        opcode_byte = code[pos]
        opcode = Opcode.from_code(opcode_byte)
        if opcode is None:
            raise ValueError(f"unknown opcode 0x{opcode_byte:02X} at byte offset {pos}")
        n = opcode.meta.operand_count
        if pos + 1 + n > len(code):
            raise ValueError(
                f"truncated operands for {opcode.name} at byte offset {pos}: need {n} bytes, have {len(code) - pos - 1}"
            )
        operands = tuple(code[pos + 1 : pos + 1 + n])