brink_format/inkb/

write.rs

//! Encoding (write) half of the `.inkb` binary format.

use alloc::string::String;
use alloc::vec::Vec;

use crate::codec::{
    crc32, write_def_id, write_i32, write_str, write_u8, write_u16, write_u32, write_u64,
    write_varint,
};
use crate::definition::{
    AddressDef, AddressPath, AliasEntry, CallAtom, CapabilityParam, ContainerDef, DebugInfoSection,
    DirectEffects, EffectRowEntry, ExternalFnDef, FrameShapeDef, GlobalVarDef, LineEntry,
    LineVariantGroup, ListDef, ListItemDef, ScopeLineTable, StructShapeDef,
};
use crate::id::DefinitionId;
use crate::line::{LineContent, LinePart, PluralCategory, SelectKey};
use crate::story::StoryData;
use crate::value::{ListValue, MapKey, ProjSegment, Value, ValueType};

use super::{
    CAP_PARAM_ANY, CAT_FEW, CAT_MANY, CAT_ONE, CAT_OTHER, CAT_TWO, CAT_ZERO, HANDLE_PARAM_NONE,
    HEADER_PREAMBLE, KEY_CARDINAL, KEY_EXACT, KEY_KEYWORD, KEY_ORDINAL, LINE_PLAIN, LINE_TEMPLATE,
    MAGIC, PART_LITERAL, PART_SELECT, PART_SLOT, PART_SPAN, PROJ_SEG_INDEX, PROJ_SEG_KEY,
    SECTION_COUNT, SECTION_ENTRY_SIZE, SectionKind, VAL_ARRAY, VAL_BOOL, VAL_CLOSURE,
    VAL_DIVERT_TARGET, VAL_FLOAT, VAL_FN_REF, VAL_FRAGMENT_REF, VAL_HANDLE, VAL_INT, VAL_LIST,
    VAL_MAP, VAL_MAT2, VAL_MAT3, VAL_MAT4, VAL_NULL, VAL_OPTION, VAL_PROJECTION, VAL_QUAT,
    VAL_RANGE, VAL_RECORD, VAL_STRING, VAL_VAR_POINTER, VAL_VEC2, VAL_VEC3, VAL_VEC4, VAL_WEIGHTED,
    VERSION,
};

// ── Tier 1: Full story write ────────────────────────────────────────────────

/// Encode a [`StoryData`] into the `.inkb` binary format with sectioned header.
#[expect(clippy::cast_possible_truncation, clippy::too_many_lines)]
pub fn write_inkb(story: &StoryData, buf: &mut Vec<u8>) {
    let base = buf.len();

    // The `Visibility` section (M-2b, tag `0x0E`) is **optional**: emitted
    // only when the story has `#@private` definitions. All-public stories —
    // the entire pre-modules world — omit it, so their offset table stays
    // at `SECTION_COUNT` entries (which now includes the mandatory M-3
    // `AliasTable` section, always present — possibly empty — from v5
    // onward; see `SectionKind::AliasTable`).
    let has_visibility = !story.private_defs.is_empty();
    // The `FrameShapes` section (FS-3, tag `0x10`) is likewise **optional**:
    // emitted only when the story carries `await` frame shapes. Behind the
    // E052 fence no `await` compiles, so this is always empty today and every
    // existing story omits it (byte-identical, no `VERSION` bump).
    let has_frame_shapes = !story.frame_shapes.is_empty();
    // The `DebugInfo` section (D6, tag `0x11`) is likewise **optional**:
    // emitted only when the story was compiled with the debug flag on
    // (`docs/debugger-spec.md` §1.2 ship policy — dev/studio compiles and
    // an explicit CLI flag opt in; release export never does). Presence
    // tracks *whether debug info was requested*, not whether any entry
    // exists, so this checks `is_some()` rather than emptiness like the
    // sections above.
    let has_debug_info = story.debug_info.is_some();
    // The `LineVariantGroups` section (#3273, tag `0x12`) is likewise
    // **optional**: emitted only when the compiler enumerated at least one
    // variant group. Nothing does until the stage-2 flip (#3274), so every
    // existing story omits it (byte-identical, no `VERSION` bump).
    let has_line_variant_groups = !story.line_variant_groups.is_empty();
    let section_count = SECTION_COUNT as usize
        + usize::from(has_visibility)
        + usize::from(has_frame_shapes)
        + usize::from(has_debug_info)
        + usize::from(has_line_variant_groups);
    let header_size = HEADER_PREAMBLE + section_count * SECTION_ENTRY_SIZE;

    // Write placeholder header (zeros) — we'll patch it after writing sections.
    buf.resize(base + header_size, 0);

    // Track (kind, offset) pairs as we write each section, in canonical
    // tag order. The offset table is self-describing (count + per-entry tag),
    // so a conditionally-omitted section is fully readable.
    let mut sections: Vec<(SectionKind, u32)> = Vec::with_capacity(section_count);

    macro_rules! section {
        ($kind:expr, $write:expr) => {{
            let offset = (buf.len() - base) as u32;
            $write;
            sections.push(($kind, offset));
        }};
    }

    section!(
        SectionKind::NameTable,
        write_section_name_table(&story.name_table, buf)
    );
    section!(
        SectionKind::Variables,
        write_section_variables(&story.variables, buf)
    );
    section!(
        SectionKind::ListDefs,
        write_section_list_defs(&story.list_defs, buf)
    );
    section!(
        SectionKind::ListItems,
        write_section_list_items(&story.list_items, buf)
    );
    section!(
        SectionKind::Externals,
        write_section_externals(&story.externals, buf)
    );
    section!(
        SectionKind::Containers,
        write_section_containers(&story.containers, buf)
    );
    section!(
        SectionKind::LineTables,
        write_section_line_tables(&story.line_tables, buf)
    );
    section!(
        SectionKind::Labels,
        write_section_addresses(&story.addresses, buf)
    );
    section!(
        SectionKind::ListLiterals,
        write_section_list_literals(&story.list_literals, buf)
    );
    section!(
        SectionKind::AddressPaths,
        write_section_address_paths(&story.address_paths, buf)
    );
    section!(
        SectionKind::LiteralPool,
        write_section_literal_pool(&story.literal_pool, buf)
    );
    section!(
        SectionKind::StructShapes,
        write_section_struct_shapes(&story.struct_shapes, buf)
    );
    // EffectRows (T2-3, tag 0x0D) is mandatory — always present (possibly
    // empty), section-locally versioned. Emitted between StructShapes and the
    // optional Visibility section so tags stay in canonical ascending order.
    section!(
        SectionKind::EffectRows,
        write_section_effect_rows(&story.effect_rows, buf)
    );
    if has_visibility {
        section!(
            SectionKind::Visibility,
            write_section_visibility(&story.private_defs, buf)
        );
    }
    // AliasTable (M-3) is mandatory — always present (possibly empty) from
    // v5 onward, unlike the optional `Visibility` section above.
    section!(
        SectionKind::AliasTable,
        write_section_alias_table(&story.alias_table, buf)
    );
    // FrameShapes (FS-3, tag 0x10) is optional — emitted last (highest tag) so
    // the offset table stays in canonical ascending tag order, and omitted
    // entirely when empty so existing stories stay byte-identical.
    if has_frame_shapes {
        section!(
            SectionKind::FrameShapes,
            write_section_frame_shapes(&story.frame_shapes, buf)
        );
    }
    // DebugInfo (D6, tag 0x11) is optional and emitted last (highest tag) —
    // omitted entirely when not requested so every story compiled without
    // the debug flag stays byte-identical to a pre-D6 compile (the
    // oracle-safety guarantee, `docs/debugger-spec.md` §1.2/§6).
    if let Some(debug_info) = &story.debug_info {
        section!(
            SectionKind::DebugInfo,
            write_section_debug_info(debug_info, buf)
        );
    }
    // LineVariantGroups (#3273, tag 0x12) is optional and emitted last
    // (highest tag) — omitted entirely when empty so every story without
    // variant groups stays byte-identical.
    if has_line_variant_groups {
        section!(
            SectionKind::LineVariantGroups,
            write_section_line_variant_groups(&story.line_variant_groups, buf)
        );
    }

    let file_size = (buf.len() - base) as u32;
    let checksum = crc32(&buf[base + header_size..]);

    // Patch header in-place.
    let h = &mut buf[base..];
    h[0..4].copy_from_slice(MAGIC);
    h[4..6].copy_from_slice(&VERSION.to_le_bytes());
    h[6] = section_count as u8;
    h[7] = 0; // reserved
    h[8..12].copy_from_slice(&file_size.to_le_bytes());
    h[12..16].copy_from_slice(&checksum.to_le_bytes());

    for (i, (kind, offset)) in sections.iter().enumerate() {
        let entry_base = HEADER_PREAMBLE + i * SECTION_ENTRY_SIZE;
        h[entry_base] = *kind as u8;
        h[entry_base + 1] = 0; // reserved
        h[entry_base + 2] = 0;
        h[entry_base + 3] = 0;
        h[entry_base + 4..entry_base + 8].copy_from_slice(&offset.to_le_bytes());
    }
}

// ── Assembly ────────────────────────────────────────────────────────────────

/// Assemble a complete `.inkb` file from pre-encoded section buffers.
///
/// Sections should be provided in the canonical order matching [`SectionKind`]
/// tags. The header (with offsets and checksum) is computed automatically.
#[expect(clippy::cast_possible_truncation)]
pub fn assemble_inkb(sections: &[(SectionKind, &[u8])], out: &mut Vec<u8>) {
    let base = out.len();
    let section_count = sections.len() as u8;
    let header_size = HEADER_PREAMBLE + sections.len() * SECTION_ENTRY_SIZE;

    // Placeholder header.
    out.resize(base + header_size, 0);

    // Append section data and record offsets.
    let mut entries: Vec<(SectionKind, u32)> = Vec::with_capacity(sections.len());
    for (kind, data) in sections {
        let offset = (out.len() - base) as u32;
        entries.push((*kind, offset));
        out.extend_from_slice(data);
    }

    let file_size = (out.len() - base) as u32;
    let checksum = crc32(&out[base + header_size..]);

    // Patch header.
    let h = &mut out[base..];
    h[0..4].copy_from_slice(MAGIC);
    h[4..6].copy_from_slice(&VERSION.to_le_bytes());
    h[6] = section_count;
    h[7] = 0;
    h[8..12].copy_from_slice(&file_size.to_le_bytes());
    h[12..16].copy_from_slice(&checksum.to_le_bytes());

    for (i, (kind, offset)) in entries.iter().enumerate() {
        let entry_base = HEADER_PREAMBLE + i * SECTION_ENTRY_SIZE;
        h[entry_base] = *kind as u8;
        h[entry_base + 1] = 0;
        h[entry_base + 2] = 0;
        h[entry_base + 3] = 0;
        h[entry_base + 4..entry_base + 8].copy_from_slice(&offset.to_le_bytes());
    }
}

// ── Section writers ─────────────────────────────────────────────────────────

/// Write the name table section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_name_table(names: &[String], buf: &mut Vec<u8>) {
    write_u32(buf, names.len() as u32);
    for name in names {
        write_str(buf, name);
    }
}

/// Write the variables section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_variables(variables: &[GlobalVarDef], buf: &mut Vec<u8>) {
    write_u32(buf, variables.len() as u32);
    for var in variables {
        encode_global_var(var, buf);
    }
}

/// Write the list definitions section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_list_defs(list_defs: &[ListDef], buf: &mut Vec<u8>) {
    write_u32(buf, list_defs.len() as u32);
    for ld in list_defs {
        encode_list_def(ld, buf);
    }
}

/// Write the list items section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_list_items(list_items: &[ListItemDef], buf: &mut Vec<u8>) {
    write_u32(buf, list_items.len() as u32);
    for li in list_items {
        encode_list_item(li, buf);
    }
}

/// Write the externals section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_externals(externals: &[ExternalFnDef], buf: &mut Vec<u8>) {
    write_u32(buf, externals.len() as u32);
    for ext in externals {
        encode_external(ext, buf);
    }
}

/// Write the containers section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_containers(containers: &[ContainerDef], buf: &mut Vec<u8>) {
    write_u32(buf, containers.len() as u32);
    for c in containers {
        encode_container(c, buf);
    }
}

/// Write the addresses section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_addresses(addresses: &[AddressDef], buf: &mut Vec<u8>) {
    write_u32(buf, addresses.len() as u32);
    for addr in addresses {
        write_def_id(buf, addr.id);
        write_def_id(buf, addr.container_id);
        write_u32(buf, addr.byte_offset);
    }
}

/// Write the address-paths section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_address_paths(address_paths: &[AddressPath], buf: &mut Vec<u8>) {
    write_u32(buf, address_paths.len() as u32);
    for ap in address_paths {
        write_u16(buf, ap.path.0);
        write_def_id(buf, ap.target);
    }
}

/// Write the visibility section (no header framing): a count followed by the
/// `DefinitionId` of every `#@private` definition (M-2b). Callers only emit
/// this section when `private_defs` is non-empty.
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_visibility(private_defs: &[DefinitionId], buf: &mut Vec<u8>) {
    write_u32(buf, private_defs.len() as u32);
    for id in private_defs {
        write_def_id(buf, *id);
    }
}

// ── Encode helpers (private) ────────────────────────────────────────────────

fn encode_global_var(v: &GlobalVarDef, buf: &mut Vec<u8>) {
    write_def_id(buf, v.id);
    write_u16(buf, v.name.0);
    encode_value_type(v.value_type, buf);
    encode_value(&v.default_value, buf);
    write_u8(buf, u8::from(v.mutable));
    write_u8(buf, u8::from(v.local));
}

fn encode_value_type(vt: ValueType, buf: &mut Vec<u8>) {
    let tag = match vt {
        ValueType::Int => VAL_INT,
        ValueType::Float => VAL_FLOAT,
        ValueType::Bool => VAL_BOOL,
        ValueType::String => VAL_STRING,
        ValueType::List => VAL_LIST,
        ValueType::DivertTarget => VAL_DIVERT_TARGET,
        ValueType::VariablePointer => VAL_VAR_POINTER,
        // TempPointer is runtime-only and should never appear in .inkb files.
        ValueType::FragmentRef => VAL_FRAGMENT_REF,
        ValueType::TempPointer | ValueType::Null => VAL_NULL,
        // Collection value types (v4, `docs/format-v4-rfc.md` §1).
        ValueType::Array => VAL_ARRAY,
        ValueType::Map => VAL_MAP,
        // TM-4 record value type (v4, reserved tag graduated this PR).
        ValueType::Record => VAL_RECORD,
        // T1c function value types (v4, materialized in #700).
        ValueType::FnRef => VAL_FN_REF,
        ValueType::Closure => VAL_CLOSURE,
        // T1d handle value type (v4, reserved tag graduated this PR).
        ValueType::Handle => VAL_HANDLE,
        // T1e projection value type (v4, reserved tag graduated this PR).
        ValueType::Projection => VAL_PROJECTION,
        // NS-A1 Option value type.
        ValueType::Option => VAL_OPTION,
        // NS-A5 range value type (F7).
        ValueType::Range => VAL_RANGE,
        // NS-A8 numeric tower value types.
        ValueType::Vec2 => VAL_VEC2,
        ValueType::Vec3 => VAL_VEC3,
        ValueType::Vec4 => VAL_VEC4,
        ValueType::Quat => VAL_QUAT,
        ValueType::Mat2 => VAL_MAT2,
        ValueType::Mat3 => VAL_MAT3,
        ValueType::Mat4 => VAL_MAT4,
        // NS-A7 weighted table value type.
        ValueType::Weighted => VAL_WEIGHTED,
    };
    write_u8(buf, tag);
}

/// NS-A8 (`docs/tower-mini-spec.md` T5): write tower lanes as explicit
/// little-endian f32s, one by one — the hand-serialized wire form. The
/// caller supplies the lanes in the pinned order (vec/quat `x, y(, z, w)`;
/// matrices column-major via `to_cols_array`), always from glam's explicit
/// array conversions — never from glam's memory representation.
fn write_f32_lanes(buf: &mut Vec<u8>, lanes: &[f32]) {
    for lane in lanes {
        buf.extend_from_slice(&lane.to_le_bytes());
    }
}

#[expect(clippy::cast_possible_truncation)]
#[expect(
    clippy::too_many_lines,
    reason = "one match arm per value variant — the NS-A1 Option arm pushed this past 100"
)]
fn encode_value(v: &Value, buf: &mut Vec<u8>) {
    match v {
        Value::Int(n) => {
            write_u8(buf, VAL_INT);
            write_i32(buf, *n);
        }
        Value::Float(n) => {
            write_u8(buf, VAL_FLOAT);
            buf.extend_from_slice(&n.to_le_bytes());
        }
        Value::Bool(b) => {
            write_u8(buf, VAL_BOOL);
            write_u8(buf, u8::from(*b));
        }
        Value::String(s) => {
            write_u8(buf, VAL_STRING);
            write_str(buf, s);
        }
        Value::List(lv) => {
            write_u8(buf, VAL_LIST);
            write_u32(buf, lv.items.len() as u32);
            for item in &lv.items {
                write_def_id(buf, *item);
            }
            write_u32(buf, lv.origins.len() as u32);
            for origin in &lv.origins {
                write_def_id(buf, *origin);
            }
        }
        Value::DivertTarget(id) => {
            write_u8(buf, VAL_DIVERT_TARGET);
            write_def_id(buf, *id);
        }
        Value::VariablePointer(id) => {
            write_u8(buf, VAL_VAR_POINTER);
            write_def_id(buf, *id);
        }
        Value::FragmentRef(idx) => {
            write_u8(buf, VAL_FRAGMENT_REF);
            write_u32(buf, *idx);
        }
        // TempPointer is runtime-only and should never appear in .inkb files.
        Value::TempPointer { .. } | Value::Null => {
            write_u8(buf, VAL_NULL);
        }
        // Collections encode as trees (v4, `docs/format-v4-rfc.md` §1): a length
        // prefix then the recursively-encoded elements / key-value pairs. Arc
        // sharing is deliberately not preserved on the wire (value-model-spec §5).
        Value::Array(items) => {
            write_u8(buf, VAL_ARRAY);
            write_u32(buf, items.len() as u32);
            for item in items.iter() {
                encode_value(item, buf);
            }
        }
        Value::Map(map) => {
            write_u8(buf, VAL_MAP);
            write_u32(buf, map.len() as u32);
            // Insertion order is semantic (keys restricted to int/string/bool).
            for (key, val) in map.iter() {
                encode_map_key(key, buf);
                encode_value(val, buf);
            }
        }
        // TM-4 (`docs/format-v4-rfc.md` §1): `ShapeId` then field values in
        // shape order — no field names on the wire (they live once, in the
        // `StructShapes` section entry the shape id references).
        Value::Record { shape, fields } => {
            write_u8(buf, VAL_RECORD);
            write_u32(buf, shape.0);
            write_u32(buf, fields.len() as u32);
            for field in fields.iter() {
                encode_value(field, buf);
            }
        }
        // Function values (T1c, `docs/format-v4-rfc.md` §1). `FnRef` is just
        // the fn token; `Closure` adds a u16-counted env of `{NameId, kind u8,
        // value}` entries — the named/moded env is the redundancy rehydration
        // validation reads (spec §6).
        Value::FnRef(target) => {
            write_u8(buf, VAL_FN_REF);
            write_def_id(buf, *target);
        }
        Value::Closure(c) => {
            write_u8(buf, VAL_CLOSURE);
            write_def_id(buf, c.target);
            write_u16(buf, c.env.len() as u16);
            for entry in &c.env {
                write_u16(buf, entry.name.0);
                write_u8(buf, u8::from(entry.is_ref));
                encode_value(&entry.payload, buf);
            }
        }
        // Handle values (T1d, `docs/format-v4-rfc.md` §1: `kind NameId, u64
        // id`). First emission of this reserved tag — the wire form is frozen
        // by the RFC, materialized here. No opcode ever pushes one; a handle
        // reaches this encoder only as a binding-produced global default or a
        // literal-pool entry supplied by a future manifest-aware pipeline.
        Value::Handle { kind, id } => {
            write_u8(buf, VAL_HANDLE);
            write_u16(buf, kind.0);
            write_u64(buf, *id);
        }
        // Projection values (T1e, `docs/format-v4-rfc.md` §1: "cell
        // reference, u8 segment count, then segments"). First emission of
        // this reserved tag. Segment kind `2=range` is RESERVED and never
        // written — `ProjSegment` has no variant to produce it.
        Value::Projection(p) => {
            write_u8(buf, VAL_PROJECTION);
            write_def_id(buf, p.cell);
            write_u8(buf, p.segments.len() as u8);
            for seg in &p.segments {
                encode_proj_segment(seg, buf);
            }
        }
        // Option values (NS-A1, `docs/stdlib-spec.md` §1.4): flag byte
        // (0 = none, 1 = some) then the inner value when some. No opcode
        // literal ever produces one at compile time today (`none`/`some(x)`
        // lower to `PushNone`/`MakeSome`, and a bare-`none` declaration
        // default is the E107 compile error), so like `VAL_HANDLE` above
        // this encoder leg exists for wire completeness — saves/transcripts
        // are the live consumers.
        Value::OptionVal(inner) => {
            write_u8(buf, VAL_OPTION);
            match inner {
                None => write_u8(buf, 0),
                Some(v) => {
                    write_u8(buf, 1);
                    encode_value(v, buf);
                }
            }
        }
        // Range values (NS-A5, F7): start i32, end i32, inclusive flag —
        // the *written* form is preserved on the wire (1..=6 and 1..7 are
        // content-equal but round-trip their own spelling). Flat: no
        // recursion, no depth accounting.
        Value::Range {
            start,
            end,
            inclusive,
        } => {
            write_u8(buf, VAL_RANGE);
            write_i32(buf, *start);
            write_i32(buf, *end);
            write_u8(buf, u8::from(*inclusive));
        }
        // Tower values (NS-A8, `docs/tower-mini-spec.md` T5): explicit
        // little-endian f32 lanes in the pinned order — vectors and the
        // quat `x, y(, z, w)`, matrices column-major column-by-column via
        // glam's `to_cols_array` (an explicit conversion, never a memory
        // cast). Fixed sizes, no counts, no recursion. Like `VAL_HANDLE`
        // above, no opcode literal produces one at compile time today
        // (construction is the runtime `Tower` opcode) — saves, transcripts
        // and future const-folding are the wire consumers.
        Value::Vec2(v) => {
            write_u8(buf, VAL_VEC2);
            write_f32_lanes(buf, &v.to_array());
        }
        Value::Vec3(v) => {
            write_u8(buf, VAL_VEC3);
            write_f32_lanes(buf, &v.to_array());
        }
        Value::Vec4(v) => {
            write_u8(buf, VAL_VEC4);
            write_f32_lanes(buf, &v.to_array());
        }
        Value::Quat(q) => {
            write_u8(buf, VAL_QUAT);
            write_f32_lanes(buf, &q.to_array());
        }
        Value::Mat2(m) => {
            write_u8(buf, VAL_MAT2);
            write_f32_lanes(buf, &m.to_cols_array());
        }
        Value::Mat3(m) => {
            write_u8(buf, VAL_MAT3);
            write_f32_lanes(buf, &m.to_cols_array());
        }
        Value::Mat4(m) => {
            write_u8(buf, VAL_MAT4);
            write_f32_lanes(buf, &m.to_cols_array());
        }
        // Weighted tables (NS-A7, `docs/stdlib-spec.md` §8): u32 entry
        // count, then per entry an i32 weight and the recursively-encoded
        // value, in construction order (order is semantic for display and
        // the roll walk). Like `VAL_HANDLE` above, no opcode literal
        // produces one at compile time today (construction is the runtime
        // `Collect(WeightedNew)` op) — saves and transcripts are the wire
        // consumers.
        Value::Weighted(w) => {
            write_u8(buf, VAL_WEIGHTED);
            write_u32(buf, w.entries.len() as u32);
            for (weight, value) in &w.entries {
                write_i32(buf, *weight);
                encode_value(value, buf);
            }
        }
    }
}

/// Encode a single [`ProjSegment`] (`docs/format-v4-rfc.md` §1: `u8 kind (0
/// = index i32, 1 = key value)`).
fn encode_proj_segment(seg: &ProjSegment, buf: &mut Vec<u8>) {
    match seg {
        ProjSegment::Index(n) => {
            write_u8(buf, PROJ_SEG_INDEX);
            write_i32(buf, *n);
        }
        ProjSegment::Key(v) => {
            write_u8(buf, PROJ_SEG_KEY);
            encode_value(v, buf);
        }
    }
}

/// Encode a [`MapKey`] using the scalar `VAL_*` tag surface it maps onto
/// (`int`/`string`/`bool` — the v1 key domain, `docs/value-model-spec.md` §4).
/// Self-describing so the reader can reject a non-scalar key tag.
fn encode_map_key(key: &MapKey, buf: &mut Vec<u8>) {
    match key {
        MapKey::Int(n) => {
            write_u8(buf, VAL_INT);
            write_i32(buf, *n);
        }
        MapKey::Str(s) => {
            write_u8(buf, VAL_STRING);
            write_str(buf, s);
        }
        MapKey::Bool(b) => {
            write_u8(buf, VAL_BOOL);
            write_u8(buf, u8::from(*b));
        }
    }
}

#[expect(clippy::cast_possible_truncation)]
fn encode_list_def(ld: &ListDef, buf: &mut Vec<u8>) {
    write_def_id(buf, ld.id);
    write_u16(buf, ld.name.0);
    write_u32(buf, ld.items.len() as u32);
    for (name_id, ordinal) in &ld.items {
        write_u16(buf, name_id.0);
        write_i32(buf, *ordinal);
    }
}

fn encode_list_item(li: &ListItemDef, buf: &mut Vec<u8>) {
    write_def_id(buf, li.id);
    write_def_id(buf, li.origin);
    write_i32(buf, li.ordinal);
    write_u16(buf, li.name.0);
}

/// Write the list literals section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_list_literals(list_literals: &[ListValue], buf: &mut Vec<u8>) {
    write_u32(buf, list_literals.len() as u32);
    for lv in list_literals {
        write_u32(buf, lv.items.len() as u32);
        for item in &lv.items {
            write_def_id(buf, *item);
        }
        write_u32(buf, lv.origins.len() as u32);
        for origin in &lv.origins {
            write_def_id(buf, *origin);
        }
    }
}

/// Write the T1b literal pool section (no header framing) — a flat list of
/// content-hash-deduplicated constant [`Value`]s referenced by
/// `PushLiteral(idx)` (`docs/format-v4-rfc.md` §2). Each entry uses the
/// existing generic `encode_value` (the same recursive `VAL_ARRAY`/`VAL_MAP`
/// tree encoding as a `GlobalVarDef` default).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_literal_pool(literal_pool: &[Value], buf: &mut Vec<u8>) {
    write_u32(buf, literal_pool.len() as u32);
    for v in literal_pool {
        encode_value(v, buf);
    }
}

/// Write the TM-4 `StructShapes` section (no header framing): one entry per
/// declared `STRUCT` — shape id, name, then its ordered field `NameId`s
/// (`docs/format-v4-rfc.md` §2). Empty (count 0) until a compiler milestone
/// emits struct declarations — see the PR description's scope note.
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_struct_shapes(struct_shapes: &[StructShapeDef], buf: &mut Vec<u8>) {
    write_u32(buf, struct_shapes.len() as u32);
    for shape in struct_shapes {
        write_u32(buf, shape.id.0);
        write_u16(buf, shape.name.0);
        write_u16(buf, shape.fields.len() as u16);
        for field in &shape.fields {
            write_u16(buf, field.0);
        }
    }
}

/// Section-local encoding version for `AliasTable` (`docs/modules-spec.md`
/// §5) — independent of the `.inkb` format `VERSION`, so the row encoding
/// can change without another whole-format bump.
pub(crate) const ALIAS_TABLE_SECTION_VERSION: u8 = 1;

/// Write the M-3 `AliasTable` section (no header framing): a one-byte
/// section-local version, then a flat list of old→new `DefinitionId` pairs
/// (`docs/modules-spec.md` §5). Entries are written in the order given —
/// callers sort by `old` for the runtime's binary-search lookup.
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_alias_table(entries: &[AliasEntry], buf: &mut Vec<u8>) {
    write_u8(buf, ALIAS_TABLE_SECTION_VERSION);
    write_u32(buf, entries.len() as u32);
    for entry in entries {
        write_def_id(buf, entry.old);
        write_def_id(buf, entry.new);
    }
}

/// Section-local encoding version for `FrameShapes` (FS-3,
/// `docs/flow-suspension-spec.md` §4/§11) — independent of the `.inkb` format
/// `VERSION`, so the shape encoding can grow (e.g. per-slot type metadata)
/// without another whole-format bump.
pub(crate) const FRAME_SHAPES_SECTION_VERSION: u8 = 1;

/// Write the FS-3 `FrameShapes` section (no header framing): a one-byte
/// section-local version, then one entry per `await` site
/// (`docs/flow-suspension-spec.md` §4/§11) — the site's stable `DefinitionId`
/// (the synthesized continuation container id) followed by its name-keyed
/// crossing-local slots. Entries are written in the order given; callers sort
/// by `site` for determinism. Callers emit this section only when non-empty.
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_frame_shapes(shapes: &[FrameShapeDef], buf: &mut Vec<u8>) {
    write_u8(buf, FRAME_SHAPES_SECTION_VERSION);
    write_u32(buf, shapes.len() as u32);
    for shape in shapes {
        write_def_id(buf, shape.site);
        write_u32(buf, shape.slots.len() as u32);
        for slot in &shape.slots {
            write_u16(buf, slot.0);
        }
    }
}

/// Section-local encoding version for `DebugInfo` (D6,
/// `docs/debugger-spec.md` §2.2) — independent of the `.inkb` format
/// `VERSION`, so the entry encoding can grow (e.g. the reserved `NodeId`
/// column, §1.3) without another whole-format bump.
pub(crate) const DEBUG_INFO_SECTION_VERSION: u8 = 2;

/// `DebugLocalEntry` row flags (section version 2). Version 1 wrote a bare
/// `has_range` 0/1 byte in this position; version 2 keeps that as bit 0 and
/// adds bit 1 (#3395). Any other bit set is a decode error — a strict
/// reader, so a future bit graduates through a section version, never by
/// being silently tolerated.
pub(crate) const LOCAL_FLAG_HAS_RANGE: u8 = 0b01;
pub(crate) const LOCAL_FLAG_SYNTHETIC: u8 = 0b10;
pub(crate) const LOCAL_FLAGS_KNOWN: u8 = LOCAL_FLAG_HAS_RANGE | LOCAL_FLAG_SYNTHETIC;

/// Section-local version of the `LineVariantGroups` encoding (#3273) —
/// bump to grow the record without a format-wide `VERSION` bump.
pub(crate) const LINE_VARIANT_GROUPS_SECTION_VERSION: u8 = 1;

/// Write the D6 `DebugInfo` section (no header framing): a one-byte
/// section-local version, the section-local file table (§2.3), then one
/// entry table per container in `Containers` order (§2.2). Callers emit
/// this section only when debug info was requested (`story.debug_info` is
/// `Some`).
///
/// Per-container entries use the varint delta/absolute encoding §2.2
/// decides (a deliberate, section-scoped departure from this format's
/// fixed-width house style — see [`write_varint`]'s doc): `bytecode_offset`
/// is delta-from-previous-entry (always ≥ 0, entries are sorted ascending
/// by offset), `range_len` is delta-from-`range_start` (the range's
/// length), everything else in the entry is an absolute varint except the
/// fixed-width `kind_token: u32` and `flags: u8` (§2.2's table explains why
/// those two stay fixed-width).
/// Encode the `LineVariantGroups` section (#3273): version byte, group
/// count, then per group `{scope_id, base, dim-count, dims}`. Dims are u16
/// on the wire exactly as in [`LineVariantGroup`] — a group's variant count
/// is `dims.product()`, capped at recognition time, so no field here needs
/// to carry more range.
#[expect(
    clippy::cast_possible_truncation,
    reason = "counts capped at recognition"
)]
pub fn write_section_line_variant_groups(groups: &[LineVariantGroup], buf: &mut Vec<u8>) {
    write_u8(buf, LINE_VARIANT_GROUPS_SECTION_VERSION);
    write_u32(buf, groups.len() as u32);
    for group in groups {
        write_def_id(buf, group.scope_id);
        write_u32(buf, group.base);
        write_u8(buf, group.dims.len() as u8);
        for dim in &group.dims {
            write_u16(buf, *dim);
        }
    }
}

#[expect(clippy::cast_possible_truncation)]
pub fn write_section_debug_info(section: &DebugInfoSection, buf: &mut Vec<u8>) {
    write_u8(buf, DEBUG_INFO_SECTION_VERSION);

    write_u32(buf, section.files.len() as u32);
    for file in &section.files {
        write_u8(buf, file.surface as u8);
        write_str(buf, &file.path);
        // #3261: the staleness detector, and the line index that lets a
        // reader answer `file:line` without being handed source text.
        write_u64(buf, file.source_hash);
        write_varint(buf, file.line_starts.len() as u64);
        // Delta-encoded: line lengths are small, so each start costs ~1
        // varint byte rather than 4. `line_starts` is contracted ascending
        // with a leading 0, so these are exact deltas; `saturating_sub`
        // keeps a contract-violating caller from wrapping to a huge varint,
        // matching the entry table's own tolerance above.
        let mut prev: u32 = 0;
        for start in &file.line_starts {
            write_varint(buf, u64::from(start.saturating_sub(prev)));
            prev = *start;
        }
    }

    write_u32(buf, section.containers.len() as u32);
    for table in &section.containers {
        write_varint(buf, table.entries.len() as u64);
        let mut prev_offset: u32 = 0;
        for entry in &table.entries {
            // Saturating, not `-`: entries are contracted to arrive sorted
            // ascending (§2.2), so this is normally an exact delta, but a
            // caller that violates that contract must not panic (debug) or
            // silently wrap to a huge varint (release) — clamp to 0 instead,
            // matching the reader's own `wrapping_add` tolerance on the
            // decode side (`read_inkb_index`'s counterpart in `read.rs`).
            write_varint(
                buf,
                u64::from(entry.bytecode_offset.saturating_sub(prev_offset)),
            );
            prev_offset = entry.bytecode_offset;
            write_varint(buf, u64::from(entry.file_idx));
            write_varint(buf, u64::from(entry.range_start));
            write_varint(buf, u64::from(entry.range_len));
            write_u32(buf, entry.kind_token);
            write_u8(buf, entry.flags);
        }

        write_varint(buf, table.locals.len() as u64);
        for local in &table.locals {
            write_u16(buf, local.slot);
            write_str(buf, &local.name);
            // Flags byte (section version 2): bit 0 = a declaring range
            // follows, bit 1 = `synthetic` (#3395). Version 1 wrote a bare
            // `has_range` 0/1 here — the same bit, so the layout is
            // unchanged and only the meaning of bit 1 is new.
            let mut flags = 0u8;
            if local.declaring_range.is_some() {
                flags |= LOCAL_FLAG_HAS_RANGE;
            }
            if local.synthetic {
                flags |= LOCAL_FLAG_SYNTHETIC;
            }
            write_u8(buf, flags);
            if let Some((file_idx, range_start, range_len)) = local.declaring_range {
                write_varint(buf, u64::from(file_idx));
                write_varint(buf, u64::from(range_start));
                write_varint(buf, u64::from(range_len));
            }
        }
    }
}

/// Section-local encoding version for `EffectRows` (T2-3,
/// `docs/effects-spec.md` §11) — independent of the `.inkb` format `VERSION`,
/// so the factored-row encoding can change without another whole-format bump
/// (the reservation this section graduates was made for exactly this).
///
/// Bumped 1 → 2 for #882: each row gains a leading `is_entry` byte (the
/// freeze bit — see [`EffectRowEntry::is_entry`]).
///
/// Bumped 2 → 3 for NS-A2 (issue #1108): each `DirectEffects` block gains a
/// trailing extension-flags byte carrying the emits/tags/faults dimensions
/// (bits 0–2; bits 3–7 reserved, strict-rejected — per-fault-kind
/// granularity is the named future occupant, graduating via the next bump).
pub(crate) const EFFECT_ROWS_SECTION_VERSION: u8 = 3;

/// Write the T2-3 `EffectRows` section (no header framing): a one-byte
/// section-local version, then the `DefinitionId → row` table of factored
/// effect rows (`docs/effects-spec.md` §11). One entry per knot/stitch — the
/// host's resume-scheduling estimate (§12.1). Entries are written in the order
/// given; callers sort by `def` for determinism.
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_effect_rows(rows: &[EffectRowEntry], buf: &mut Vec<u8>) {
    write_u8(buf, EFFECT_ROWS_SECTION_VERSION);
    write_u32(buf, rows.len() as u32);
    for row in rows {
        write_def_id(buf, row.def);
        // #882 freeze bit: whether this row is a legitimate host entry point
        // (see `EffectRowEntry::is_entry`'s doc — `false` only for
        // `#@private` defs, and the row still ships either way).
        write_u8(buf, u8::from(row.is_entry));
        encode_direct_effects(&row.direct, buf);
        // Per-dispatch entries (v1 emits none, but the encoding ships the
        // structure — a flat row forecloses §7 narrowing).
        write_u32(buf, row.dispatches.len() as u32);
        for d in &row.dispatches {
            write_def_id(buf, d.cell);
            write_u8(buf, u8::from(d.narrowable));
            encode_direct_effects(&d.fallback, buf);
        }
    }
}

/// Encode a [`DirectEffects`] block: reads, writes, call atoms, opaque flag.
#[expect(clippy::cast_possible_truncation)]
fn encode_direct_effects(direct: &DirectEffects, buf: &mut Vec<u8>) {
    write_u32(buf, direct.reads.len() as u32);
    for id in &direct.reads {
        write_def_id(buf, *id);
    }
    write_u32(buf, direct.writes.len() as u32);
    for id in &direct.writes {
        write_def_id(buf, *id);
    }
    write_u32(buf, direct.calls.len() as u32);
    for atom in &direct.calls {
        encode_call_atom(atom, buf);
    }
    write_u8(buf, u8::from(direct.opaque));
    // NS-A2 extension-flags byte (section version 3): emits/tags/faults.
    let mut dims = 0u8;
    if direct.emits {
        dims |= super::EFFECT_DIM_EMITS;
    }
    if direct.tags {
        dims |= super::EFFECT_DIM_TAGS;
    }
    if direct.faults {
        dims |= super::EFFECT_DIM_FAULTS;
    }
    write_u8(buf, dims);
}

/// Encode a single [`CallAtom`]: interned name, the capability-parameter slot
/// (`(any)` in v1), then the reserved handle-parameter slot (`None` in v1 —
/// `docs/t1d-spec.md` §7). A bound handle is never emitted in this section
/// version.
fn encode_call_atom(atom: &CallAtom, buf: &mut Vec<u8>) {
    write_u16(buf, atom.name.0);
    let cap_tag = match atom.capability {
        CapabilityParam::Any => CAP_PARAM_ANY,
    };
    write_u8(buf, cap_tag);
    // Reserved handle-parameter slot: v1 is always `None`. A `Some` is
    // structurally representable but never encoded in this section version.
    write_u8(buf, atom.handle_param.unwrap_or(HANDLE_PARAM_NONE));
}

fn encode_external(ext: &ExternalFnDef, buf: &mut Vec<u8>) {
    write_def_id(buf, ext.id);
    write_u16(buf, ext.name.0);
    write_u8(buf, ext.arg_count);
    match ext.fallback {
        Some(fb) => {
            write_u8(buf, 1);
            write_def_id(buf, fb);
        }
        None => {
            write_u8(buf, 0);
        }
    }
}

#[expect(clippy::cast_possible_truncation)]
fn encode_container(c: &ContainerDef, buf: &mut Vec<u8>) {
    write_def_id(buf, c.id);
    write_def_id(buf, c.scope_id);
    match c.name {
        Some(name_id) => {
            write_u8(buf, 1);
            write_u16(buf, name_id.0);
        }
        None => {
            write_u8(buf, 0);
        }
    }
    write_u8(buf, c.counting_flags.bits());
    write_i32(buf, c.path_hash);
    write_u8(buf, c.param_count);
    write_u8(buf, u8::from(c.local));
    // Per-param name/mode metadata (T1c, `docs/t1c-spec.md` §6). Additive
    // trailing field: a `0` count for the common no-param container.
    write_u16(buf, c.params.len() as u16);
    for p in &c.params {
        write_u16(buf, p.name.0);
        write_u8(buf, u8::from(p.is_ref));
        write_u16(buf, p.slot);
    }
    write_u32(buf, c.bytecode.len() as u32);
    buf.extend_from_slice(&c.bytecode);
}

/// Write the line tables section (no header framing).
#[expect(clippy::cast_possible_truncation)]
pub fn write_section_line_tables(line_tables: &[ScopeLineTable], buf: &mut Vec<u8>) {
    write_u32(buf, line_tables.len() as u32);
    for lt in line_tables {
        encode_scope_line_table(lt, buf);
    }
}

#[expect(clippy::cast_possible_truncation)]
fn encode_scope_line_table(lt: &ScopeLineTable, buf: &mut Vec<u8>) {
    write_def_id(buf, lt.scope_id);
    write_u32(buf, lt.lines.len() as u32);
    for entry in &lt.lines {
        encode_line_entry(entry, buf);
    }
}

fn encode_line_entry(entry: &LineEntry, buf: &mut Vec<u8>) {
    encode_line_content(&entry.content, buf);
    write_u64(buf, entry.source_hash);
    match &entry.audio_ref {
        Some(audio) => {
            write_u8(buf, 1);
            write_str(buf, audio);
        }
        None => {
            write_u8(buf, 0);
        }
    }

    // Slot info
    #[expect(clippy::cast_possible_truncation)]
    write_u8(buf, entry.slot_info.len() as u8);
    for slot in &entry.slot_info {
        write_u8(buf, slot.index);
        write_str(buf, &slot.name);
    }

    // Source location
    match &entry.source_location {
        Some(loc) => {
            write_u8(buf, 1);
            write_str(buf, &loc.file);
            write_u32(buf, loc.range_start);
            write_u32(buf, loc.range_end);
        }
        None => {
            write_u8(buf, 0);
        }
    }
}

#[expect(clippy::cast_possible_truncation)]
pub(crate) fn encode_line_content(content: &LineContent, buf: &mut Vec<u8>) {
    match content {
        LineContent::Plain(s) => {
            write_u8(buf, LINE_PLAIN);
            write_str(buf, s);
        }
        LineContent::Template(parts) => {
            write_u8(buf, LINE_TEMPLATE);
            write_u32(buf, parts.len() as u32);
            for part in parts {
                encode_line_part(part, buf);
            }
        }
    }
}

#[expect(clippy::cast_possible_truncation)]
fn encode_line_part(part: &LinePart, buf: &mut Vec<u8>) {
    match part {
        LinePart::Literal(s) => {
            write_u8(buf, PART_LITERAL);
            write_str(buf, s);
        }
        LinePart::Slot(idx) => {
            write_u8(buf, PART_SLOT);
            write_u8(buf, *idx);
        }
        LinePart::Select {
            slot,
            variants,
            default,
        } => {
            write_u8(buf, PART_SELECT);
            write_u8(buf, *slot);
            write_u32(buf, variants.len() as u32);
            for (key, text) in variants {
                encode_select_key(key, buf);
                write_str(buf, text);
            }
            write_str(buf, default);
        }
        LinePart::Span {
            name,
            attrs,
            children,
        } => {
            write_u8(buf, PART_SPAN);
            write_str(buf, name);
            write_u32(buf, attrs.len() as u32);
            for (k, v) in attrs {
                write_str(buf, k);
                write_str(buf, v);
            }
            write_u32(buf, children.len() as u32);
            for child in children {
                encode_line_part(child, buf);
            }
        }
    }
}

fn encode_select_key(key: &SelectKey, buf: &mut Vec<u8>) {
    match key {
        SelectKey::Cardinal(cat) => {
            write_u8(buf, KEY_CARDINAL);
            encode_plural_category(*cat, buf);
        }
        SelectKey::Ordinal(cat) => {
            write_u8(buf, KEY_ORDINAL);
            encode_plural_category(*cat, buf);
        }
        SelectKey::Exact(n) => {
            write_u8(buf, KEY_EXACT);
            write_i32(buf, *n);
        }
        SelectKey::Keyword(k) => {
            write_u8(buf, KEY_KEYWORD);
            write_str(buf, k);
        }
    }
}

fn encode_plural_category(cat: PluralCategory, buf: &mut Vec<u8>) {
    let tag = match cat {
        PluralCategory::Zero => CAT_ZERO,
        PluralCategory::One => CAT_ONE,
        PluralCategory::Two => CAT_TWO,
        PluralCategory::Few => CAT_FEW,
        PluralCategory::Many => CAT_MANY,
        PluralCategory::Other => CAT_OTHER,
    };
    write_u8(buf, tag);
}