//! Versioned, pointer-free binary serialization of the shared RIL model.

//!

//! Wire integers are little-endian. The header is "RIL0", version u32=1,

//! reserved flags u32=0, symbol count, length-prefixed symbol byte strings,

//! entry symbol index (0xffffffff for none), data count and function count.

//! Data records precede functions. Every list and byte string has a u32 count.

//! Instruction, value and data tags are explicit and independent of ABI layout.

//! Decoding checks structural consistency, not pointer provenance or type safety.

mod instructions;

mod records;

mod structure;

/// Binary input-boundary checks.

@test mod tests;

use std::mem;

use std::collections::dict;

use std::lang::alloc;

use std::lang::strings;

use std::lang::il;

/// A compilation unit and its optional declared entry function.

export record Image: Copy {

    /// Existing RIL representation consumed by lowering and code generation.

    program: il::Program,

    /// Entry function name, or nil for a library without an entry point.

    entry: ?*[u8],

}

/// A malformed input, unsupported structure, or exhausted caller buffer.

export record Error: Copy {

    /// Byte offset in the binary input or output where the error was detected.

    offset: u32,

    /// Static diagnostic message.

    message: *[u8],

}

/// One deduplicated wire symbol and its declaration/reference metadata.

export record Symbol: Copy {

    /// Interned or caller-owned symbol bytes.

    name: *[u8],

    /// Declaration kind: 0 undeclared, 1 data, 2 function.

    kind: u8,

    /// Required reference kinds, using the same data/function bit values.

    uses: u8,

    /// Offset identifying this symbol in the binary stream.

    offset: u32,

}

/// Internal bounded writer, shared with the instruction and record codecs.

export record Writer: Copy {

    /// Caller-provided destination, disjoint from the scratch arena.

    output: *mut [u8],

    /// Next output byte.

    offset: u32,

    /// Declaration-indexed wire symbols.

    symbols: *[Symbol],

    /// Name-to-wire-index dictionary with checked capacity.

    symbolMap: dict::Dict,

}

/// Internal bounded reader, shared with the instruction and record codecs.

export record Reader: Copy {

    /// Immutable binary source; returned strings may borrow it.

    input: *[u8],

    /// Next input byte.

    offset: u32,

    /// Caller storage for all returned records and mutable slices.

    arena: *mut alloc::Arena,

    /// Shared identifier pool, whose lifetime must cover the decoded image.

    pool: *mut strings::Pool,

    /// Deduplicated symbol table and deferred reference checks.

    symbols: *mut [Symbol],

}

/// Create a diagnostic at a known binary offset.

export fn error(offset: u32, message: *[u8]) -> Error {

    return Error { offset, message };

}

/// Allocate without overflowing the shared arena's u32 size arithmetic.

export fn storage(arena: *mut alloc::Arena, size: u32, alignment: u32, count: u32, offset: u32) -> *mut [opaque] throws (Error) {

    if count == 0 { return &mut []; }

    let bytes = size as u64 * count as u64;

    let padding = (alignment - (arena.offset % alignment)) % alignment;

    if arena.offset > arena.data.len or bytes + padding as u64 > (arena.data.len - arena.offset) as u64 {

        throw error(offset, "RIL arena exhausted");

    }

    return try alloc::allocSlice(arena, size, alignment, count) catch {

        throw error(offset, "RIL arena exhausted");

    };

}

/// Build an empty dictionary with enough space for `count` unique entries.

export fn dictionary(arena: *mut alloc::Arena, count: u32, offset: u32) -> dict::Dict throws (Error) {

    if count > 0x20000000 { throw error(offset, "RIL symbol count is too large"); }

    let mut capacity: u32 = 2;

    while capacity / 2 < count { set capacity *= 2; }

    let entries = try storage(arena, @sizeOf(dict::Entry), @alignOf(dict::Entry), capacity, offset) as *mut [dict::Entry];

    return dict::init(entries);

}

/// Write bytes after checking the caller's complete remaining capacity.

export fn putBytes(w: *mut Writer, bytes: *[u8]) throws (Error) {

    if bytes.len > w.output.len - w.offset { throw error(w.offset, "RIL output buffer exhausted"); }

    try mem::copy(&mut w.output[w.offset..w.offset + bytes.len], bytes) catch {

        throw error(w.offset, "RIL output buffer exhausted");

    };

    set w.offset += bytes.len;

}

/// Write a single wire byte.

export fn put8(w: *mut Writer, value: u8) throws (Error) {

    if w.offset == w.output.len { throw error(w.offset, "RIL output buffer exhausted"); }

    set w.output[w.offset] = value;

    set w.offset += 1;

}

/// Write an explicitly little-endian u32.

export fn put32(w: *mut Writer, value: u32) throws (Error) {

    if w.output.len - w.offset < 4 { throw error(w.offset, "RIL output buffer exhausted"); }

    for i in 0..4 { set w.output[w.offset + i] = (value >> (i * 8)) as u8; }

    set w.offset += 4;

}

/// Write an explicitly little-endian u64, preserving signed literal bits.

export fn put64(w: *mut Writer, value: u64) throws (Error) {

    if w.output.len - w.offset < 8 { throw error(w.offset, "RIL output buffer exhausted"); }

    for i in 0..8 { set w.output[w.offset + i] = (value >> (i as u64 * 8)) as u8; }

    set w.offset += 8;

}

/// Write a length-prefixed byte string, including embedded zero bytes.

export fn putString(w: *mut Writer, value: *[u8]) throws (Error) {

    try put32(w, value.len);

    try putBytes(w, value);

}

/// Read a source-backed byte slice after a subtraction-based bounds check.

export fn getBytes(r: *mut Reader, count: u32) -> *[u8] throws (Error) {

    if count > r.input.len - r.offset { throw error(r.offset, "truncated binary RIL"); }

    let bytes = &r.input[r.offset..r.offset + count];

    set r.offset += count;

    return bytes;

}

/// Read one wire byte.

export fn get8(r: *mut Reader) -> u8 throws (Error) {

    let bytes = try getBytes(r, 1);

    return bytes[0];

}

/// Read an explicitly little-endian u32 without alignment assumptions.

export fn get32(r: *mut Reader) -> u32 throws (Error) {

    let bytes = try getBytes(r, 4);

    let mut value: u32 = 0;

    for i in 0..4 { set value |= (bytes[i] as u32) << (i * 8); }

    return value;

}

/// Read an explicitly little-endian u64 without host pointer reinterpretation.

export fn get64(r: *mut Reader) -> u64 throws (Error) {

    let bytes = try getBytes(r, 8);

    let mut value: u64 = 0;

    for i in 0..8 { set value |= (bytes[i] as u64) << (i as u64 * 8); }

    return value;

}

/// Read a canonical wire boolean; other bytes are malformed, not truthy.

export fn getBool(r: *mut Reader) -> bool throws (Error) {

    let offset = r.offset;

    let value = try get8(r);

    if value > 1 { throw error(offset, "invalid RIL boolean"); }

    return value == 1;

}

/// Read a count bounded by the smallest possible wire representation per item.

export fn count(r: *mut Reader, minimumBytes: u32) -> u32 throws (Error) {

    let offset = r.offset;

    let value = try get32(r);

    if value > (r.input.len - r.offset) / minimumBytes {

        throw error(offset, "RIL list count exceeds remaining input");

    }

    return value;

}

/// Read a byte string without copying its payload.

export fn getString(r: *mut Reader) -> *[u8] throws (Error) {

    let len = try get32(r);

    return try getBytes(r, len);

}

/// Intern a nonempty symbol, checking the fixed shared pool before insertion.

export fn intern(r: *mut Reader, name: *[u8], offset: u32) -> *[u8] throws (Error) {

    if name.len == 0 { throw error(offset, "empty RIL symbol name"); }

    if let existing = strings::find(r.pool, name) { return existing; }

    if r.pool.count >= r.pool.table.len / 2 { throw error(offset, "RIL string pool exhausted"); }

    return strings::intern(r.pool, name);

}

/// Write a symbol reference, rejecting undeclared or wrong-kind names.

export fn putSymbol(w: *mut Writer, name: *[u8], kind: u8) throws (Error) {

    let index = dict::get(&w.symbolMap, name) else {

        throw error(w.offset, "undefined RIL symbol");

    };

    if w.symbols[index as u32].kind <> kind { throw error(w.offset, "RIL symbol kind mismatch"); }

    try put32(w, index as u32);

}

/// Read a reference by table index and defer declaration-kind checks until EOF.

export fn getSymbol(r: *mut Reader, kind: u8) -> *[u8] throws (Error) {

    let offset = r.offset;

    let index = try get32(r);

    if index >= r.symbols.len { throw error(offset, "RIL symbol index out of range"); }

    set r.symbols[index].uses |= kind;

    return r.symbols[index].name;

}

/// Read and register a unique data or function declaration.

export fn declaration(r: *mut Reader, kind: u8) -> *[u8] throws (Error) {

    let offset = r.offset;

    let index = try get32(r);

    if index >= r.symbols.len { throw error(offset, "RIL declaration index out of range"); }

    let symbol = &mut r.symbols[index];

    if symbol.kind <> 0 { throw error(offset, "duplicate RIL declaration"); }

    set symbol.kind = kind;

    return symbol.name;

}

/// Encode into disjoint caller output, restoring all arena scratch on success or error.

/// Returned bytes contain no addresses from the source program or host ABI.

export fn encode(image: *Image, arena: *mut alloc::Arena, output: *mut [u8]) -> u32 throws (Error) {

    let saved = alloc::save(arena);

    let result = try encodeImage(image, arena, output) catch err {

        alloc::restore(arena, saved);

        throw err;

    };

    alloc::restore(arena, saved);

    return result;

}

/// Build the declaration-only symbol table and serialize the image.

fn encodeImage(image: *Image, arena: *mut alloc::Arena, output: *mut [u8]) -> u32 throws (Error) {

    let total = image.program.data.len as u64 + image.program.fns.len as u64;

    if total > 0x7FFFFFFF { throw error(0, "too many RIL declarations"); }

    let symbols = try storage(arena, @sizeOf(Symbol), @alignOf(Symbol), total as u32, 0) as *mut [Symbol];

    let mut map = try dictionary(arena, total as u32, 0);

    for d, i in image.program.data {

        set symbols[i] = { name: d.name, kind: 1, uses: 0, offset: 0 };

    }

    for f, i in image.program.fns {

        set symbols[image.program.data.len + i] = { name: f.name, kind: 2, uses: 0, offset: 0 };

    }

    for symbol, i in symbols {

        if symbol.name.len == 0 { throw error(0, "empty RIL declaration name"); }

        if dict::get(&map, symbol.name) <> nil { throw error(0, "duplicate RIL declaration"); }

        dict::insert(&mut map, symbol.name, i as i32);

    }

    let mut w = Writer { output, offset: 0, symbols, symbolMap: map };

    try putBytes(&mut w, "RIL0");

    try put32(&mut w, 1);

    try put32(&mut w, 0);

    try put32(&mut w, symbols.len);

    for symbol in symbols { try putString(&mut w, symbol.name); }

    if let entry = image.entry { try putSymbol(&mut w, entry, 2); }

    else { try put32(&mut w, 0xFFFFFFFF); }

    try put32(&mut w, image.program.data.len);

    try put32(&mut w, image.program.fns.len);

    for data in image.program.data { try records::putData(&mut w, &data); }

    for func in image.program.fns { try records::putFn(&mut w, func); }

    return w.offset;

}

/// Decode bounded binary RIL into the existing shared IL records.

/// Input, arena, and pool must outlive the image. Failed decoding may consume

/// arena space and intern input strings; callers reclaim them as one load unit.

/// This is structural decoding of trusted input, not a safety verifier.

export fn decode(input: *[u8], arena: *mut alloc::Arena, pool: *mut strings::Pool) -> Image throws (Error) {

    let mut r = Reader { input, offset: 0, arena, pool, symbols: &mut [] };

    if not mem::eq(try getBytes(&mut r, 4), "RIL0") { throw error(0, "invalid binary RIL magic"); }

    if try get32(&mut r) <> 1 { throw error(4, "unsupported binary RIL version"); }

    if try get32(&mut r) <> 0 { throw error(8, "unsupported binary RIL flags"); }

    let symbolCount = try count(&mut r, 4);

    set r.symbols = try storage(arena, @sizeOf(Symbol), @alignOf(Symbol), symbolCount, r.offset) as *mut [Symbol];

    let mut map = try dictionary(arena, symbolCount, r.offset);

    for i in 0..symbolCount {

        let offset = r.offset;

        let bytes = try getString(&mut r);

        let name = try intern(&mut r, bytes, offset);

        if dict::get(&map, name) <> nil { throw error(offset, "duplicate RIL symbol table entry"); }

        dict::insert(&mut map, name, i as i32);

        set r.symbols[i] = { name, kind: 0, uses: 0, offset };

    }

    let entryOffset = r.offset;

    let entryIndex = try get32(&mut r);

    let mut entry: ?*[u8] = nil;

    if entryIndex <> 0xFFFFFFFF {

        if entryIndex >= symbolCount { throw error(entryOffset, "RIL entry symbol index out of range"); }

        set entry = r.symbols[entryIndex].name;

        set r.symbols[entryIndex].uses |= 2;

    }

    let dataCount = try count(&mut r, 17);

    let fnCount = try count(&mut r, 14);

    if dataCount as u64 + fnCount as u64 <> symbolCount as u64 {

        throw error(r.offset, "RIL declaration count differs from symbol count");

    }

    let data = try storage(arena, @sizeOf(il::Data), @alignOf(il::Data), dataCount, r.offset) as *mut [il::Data];

    let fns = try storage(arena, @sizeOf(*il::Fn), @alignOf(*il::Fn), fnCount, r.offset) as *mut [*il::Fn];

    for i in 0..dataCount { set data[i] = try records::getData(&mut r); }

    for i in 0..fnCount {

        let func = try storage(arena, @sizeOf(il::Fn), @alignOf(il::Fn), 1, r.offset) as *mut [il::Fn];

        set func[0] = try records::getFn(&mut r);

        set fns[i] = &func[0];

    }

    if r.offset <> input.len { throw error(r.offset, "trailing bytes after binary RIL"); }

    for symbol in r.symbols {

        if symbol.kind == 0 { throw error(symbol.offset, "undeclared RIL symbol"); }

        if (symbol.uses & symbol.kind) <> symbol.uses { throw error(symbol.offset, "RIL symbol kind mismatch"); }

    }

    if entryIndex <> 0xFFFFFFFF {

        for func in fns {

            if mem::eq(func.name, r.symbols[entryIndex].name) and func.isExtern {

                throw error(entryOffset, "RIL entry function has no body");

            }

        }

    }

    return Image { program: il::Program { data, fns }, entry };

}