Skip to main content

sheetkit_core/
raw_transfer_write.rs

1//! Write-direction buffer serialization and deserialization for raw FFI transfer.
2//!
3//! Provides [`cells_to_raw_buffer`] to encode structured cell data into a
4//! compact binary buffer, and [`raw_buffer_to_cells`] to decode a buffer
5//! back into cell values. These are used for the JS-to-Rust write path
6//! (e.g., `setSheetData`) and for round-trip testing.
7//!
8//! The binary format matches the specification in `raw_transfer.rs` so that
9//! buffers produced by either module can be consumed by the other.
10
11use std::collections::hash_map::DefaultHasher;
12use std::collections::HashMap;
13use std::hash::Hasher;
14
15use crate::cell::CellValue;
16use crate::error::{Error, Result};
17use crate::formula::FormulaBudget;
18use crate::resource::ResourceDimension;
19use crate::traversal::{check_limit, checked_output_add, checked_output_mul, TraversalLimits};
20use crate::utils::constants::{MAX_COLUMNS, MAX_ROWS};
21
22const MAGIC: u32 = 0x534B5244;
23const VERSION: u16 = 1;
24const MAGIC_V2: u32 = crate::raw_transfer_v2::MAGIC_V2;
25const VERSION_V2: u16 = crate::raw_transfer_v2::VERSION_V2;
26const HEADER_SIZE: usize = 16;
27const ROW_INDEX_ENTRY_SIZE: usize = 8;
28const CELL_STRIDE: usize = 9;
29const SPARSE_ENTRY_SIZE: usize = 11;
30const EMPTY_ROW_SENTINEL: u32 = 0xFFFF_FFFF;
31const FLAG_SPARSE: u32 = 1;
32const DENSITY_THRESHOLD: f64 = 0.3;
33
34const TYPE_EMPTY: u8 = 0x00;
35const TYPE_NUMBER: u8 = 0x01;
36const TYPE_STRING: u8 = 0x02;
37const TYPE_BOOL: u8 = 0x03;
38const TYPE_DATE: u8 = 0x04;
39const TYPE_ERROR: u8 = 0x05;
40const TYPE_FORMULA: u8 = 0x06;
41const TYPE_RICH_STRING: u8 = 0x07;
42
43/// A row of cell data: (1-based row number, cells in that row).
44type CellRow = (u32, Vec<(u32, CellValue)>);
45
46/// Opaque raw-transfer values admitted under one decode/mutation budget.
47pub struct ValidatedCellTransfer {
48    pub(crate) entries: Vec<(String, CellValue)>,
49}
50
51/// Validate a workbook target before decoding a raw transfer.
52pub fn validate_cell_transfer_target(
53    workbook: &crate::workbook::Workbook,
54    sheet: &str,
55) -> Result<()> {
56    let sheet_idx = workbook.sheet_index(sheet)?;
57    workbook.reject_streamed_mutation(sheet_idx)
58}
59
60/// Intermediate encoded cell: (0-based column index, type tag, 8-byte payload).
61type EncodedCell = (u16, u8, [u8; 8]);
62
63/// Intermediate encoded row: (1-based row number, encoded cells).
64type EncodedRow = (u32, Vec<EncodedCell>);
65
66struct BufferHeader {
67    _version: u16,
68    row_count: u32,
69    col_count: u16,
70    flags: u32,
71}
72
73fn read_header(buf: &[u8]) -> Result<BufferHeader> {
74    if buf.len() < HEADER_SIZE {
75        return Err(Error::Internal(format!(
76            "buffer too short for header: {} bytes (need {})",
77            buf.len(),
78            HEADER_SIZE
79        )));
80    }
81    let magic = read_u32(buf, 0, "header")?;
82    if magic != MAGIC {
83        return Err(Error::Internal(format!(
84            "invalid buffer magic: expected 0x{MAGIC:08X}, got 0x{magic:08X}"
85        )));
86    }
87    let version = read_u16(buf, 4, "header")?;
88    if version != VERSION {
89        return Err(Error::Internal(format!(
90            "unsupported buffer version: {version}"
91        )));
92    }
93    let row_count = read_u32(buf, 6, "header")?;
94    let col_count = read_u16(buf, 10, "header")?;
95    let flags = read_u32(buf, 12, "header")?;
96    if flags & 0x0000_FFFE != 0 {
97        return Err(Error::Internal("invalid v1 buffer flags".to_string()));
98    }
99    Ok(BufferHeader {
100        _version: version,
101        row_count,
102        col_count,
103        flags,
104    })
105}
106
107fn checked_end(start: usize, len: usize, context: &str) -> Result<usize> {
108    start
109        .checked_add(len)
110        .ok_or_else(|| Error::Internal(format!("{context} exceeds addressable buffer size")))
111}
112
113fn read_u16(buf: &[u8], offset: usize, context: &str) -> Result<u16> {
114    let end = checked_end(offset, 2, context)?;
115    let bytes = buf
116        .get(offset..end)
117        .ok_or_else(|| Error::Internal(format!("buffer too short for {context}")))?;
118    Ok(u16::from_le_bytes(
119        bytes.try_into().expect("fixed-size slice"),
120    ))
121}
122
123fn read_u32(buf: &[u8], offset: usize, context: &str) -> Result<u32> {
124    let end = checked_end(offset, 4, context)?;
125    let bytes = buf
126        .get(offset..end)
127        .ok_or_else(|| Error::Internal(format!("buffer too short for {context}")))?;
128    Ok(u32::from_le_bytes(
129        bytes.try_into().expect("fixed-size slice"),
130    ))
131}
132
133fn read_f64(buf: &[u8], offset: usize, context: &str) -> Result<f64> {
134    let end = checked_end(offset, 8, context)?;
135    let bytes = buf
136        .get(offset..end)
137        .ok_or_else(|| Error::Internal(format!("buffer too short for {context}")))?;
138    Ok(f64::from_le_bytes(
139        bytes.try_into().expect("fixed-size slice"),
140    ))
141}
142
143fn validate_coordinate(row: u32, col: u32) -> Result<()> {
144    if !(1..=MAX_ROWS).contains(&row) {
145        return Err(Error::Internal("row number is out of range".to_string()));
146    }
147    if !(1..=MAX_COLUMNS).contains(&col) {
148        return Err(Error::Internal("cell column is out of range".to_string()));
149    }
150    Ok(())
151}
152
153fn validate_decode_layout(
154    row_count: u32,
155    col_count: u16,
156    flags: u32,
157    is_sparse: bool,
158    limits: TraversalLimits,
159) -> Result<u32> {
160    check_limit(
161        ResourceDimension::RowCount,
162        limits.max_rows(),
163        u64::from(row_count),
164    )?;
165    check_limit(
166        ResourceDimension::ColumnCount,
167        limits.max_columns(),
168        u64::from(col_count),
169    )?;
170    if (row_count == 0) != (col_count == 0) {
171        return Err(Error::Internal(
172            "row and column counts must both be zero or nonzero".to_string(),
173        ));
174    }
175    if row_count == 0 {
176        if flags != 0 {
177            return Err(Error::Internal(
178                "empty raw transfer flags must be zero".to_string(),
179            ));
180        }
181        return Ok(1);
182    }
183    let min_col = (flags >> 16).max(1);
184    let max_col = min_col
185        .checked_add(u32::from(col_count) - 1)
186        .ok_or_else(|| Error::Internal("cell column span overflows".to_string()))?;
187    if max_col > MAX_COLUMNS {
188        return Err(Error::Internal(
189            "cell column span is out of range".to_string(),
190        ));
191    }
192    if !is_sparse {
193        let cell_count = u64::from(row_count)
194            .checked_mul(u64::from(col_count))
195            .ok_or_else(|| Error::Internal("dense cell count overflow".to_string()))?;
196        check_limit(ResourceDimension::CellCount, limits.max_cells(), cell_count)?;
197    }
198    Ok(min_col)
199}
200
201fn read_row_index(
202    buf: &[u8],
203    row_count: u32,
204    budget: &mut DecodeBudget,
205) -> Result<Vec<(u32, u32)>> {
206    let start = HEADER_SIZE;
207    let size = (row_count as usize)
208        .checked_mul(ROW_INDEX_ENTRY_SIZE)
209        .ok_or_else(|| Error::Internal("row index exceeds addressable buffer size".to_string()))?;
210    let end = checked_end(start, size, "row index")?;
211    if buf.len() < end {
212        return Err(Error::Internal(format!(
213            "buffer too short for row index: {} bytes (need {})",
214            buf.len(),
215            end
216        )));
217    }
218    let mut entries = Vec::new();
219    budget.charge_array::<(u32, u32)>(row_count as usize)?;
220    entries
221        .try_reserve_exact(row_count as usize)
222        .map_err(|_| Error::Internal("row index allocation failed".to_string()))?;
223    let mut previous_row = 0u32;
224    for i in 0..row_count as usize {
225        let offset = checked_end(
226            start,
227            i.checked_mul(ROW_INDEX_ENTRY_SIZE).ok_or_else(|| {
228                Error::Internal("row index exceeds addressable buffer size".to_string())
229            })?,
230            "row index",
231        )?;
232        let row_num = read_u32(buf, offset, "row index entry")?;
233        if !(1..=MAX_ROWS).contains(&row_num) {
234            return Err(Error::Internal("row number is out of range".to_string()));
235        }
236        if row_num <= previous_row {
237            return Err(Error::Internal(
238                "row numbers must be strictly increasing".to_string(),
239            ));
240        }
241        previous_row = row_num;
242        let row_off = read_u32(
243            buf,
244            checked_end(offset, 4, "row index entry")?,
245            "row index entry",
246        )?;
247        entries.push((row_num, row_off));
248    }
249    Ok(entries)
250}
251
252fn validate_string_table_layout(buf: &[u8], offset: usize) -> Result<usize> {
253    let header_end = offset.checked_add(8).ok_or_else(|| {
254        Error::Internal("string table header offset overflows buffer bounds".to_string())
255    })?;
256    if buf.len() < header_end {
257        return Err(Error::Internal(
258            "buffer too short for string table header".to_string(),
259        ));
260    }
261    let count = read_u32(buf, offset, "string table header")? as usize;
262    let blob_size = read_u32(
263        buf,
264        checked_end(offset, 4, "string table header")?,
265        "string table header",
266    )? as usize;
267    if count == 0 && blob_size != 0 {
268        return Err(Error::Internal(
269            "empty string table must have an empty blob".to_string(),
270        ));
271    }
272
273    let offsets_start = header_end;
274    let offsets_end = offsets_start
275        .checked_add(count.checked_mul(4).ok_or_else(|| {
276            Error::Internal("string table offsets exceed addressable buffer size".to_string())
277        })?)
278        .ok_or_else(|| {
279            Error::Internal("string table offsets exceed addressable buffer size".to_string())
280        })?;
281    let blob_start = offsets_end;
282    let blob_end = blob_start.checked_add(blob_size).ok_or_else(|| {
283        Error::Internal("string table blob exceeds addressable buffer size".to_string())
284    })?;
285
286    if buf.len() < blob_end {
287        return Err(Error::Internal(format!(
288            "buffer too short for string table: {} bytes (need {})",
289            buf.len(),
290            blob_end
291        )));
292    }
293
294    let mut previous_offset = 0;
295    for i in 0..count {
296        let pos = checked_end(
297            offsets_start,
298            i.checked_mul(4).ok_or_else(|| {
299                Error::Internal("string table offsets exceed addressable buffer size".to_string())
300            })?,
301            "string table offsets",
302        )?;
303        let current = read_u32(buf, pos, "string table offset")? as usize;
304        if i == 0 && current != 0 {
305            return Err(Error::Internal(
306                "first string table offset must be zero".to_string(),
307            ));
308        }
309        let next = if i + 1 < count {
310            read_u32(
311                buf,
312                checked_end(pos, 4, "string table offsets")?,
313                "string table offset",
314            )? as usize
315        } else {
316            blob_size
317        };
318        if current > blob_size || current < previous_offset || next > blob_size || next < current {
319            return Err(Error::Internal(
320                "string table offsets must be monotonic and within the blob".to_string(),
321            ));
322        }
323        let start = checked_end(blob_start, current, "string table blob")?;
324        let end = checked_end(blob_start, next, "string table blob")?;
325        std::str::from_utf8(&buf[start..end])
326            .map_err(|e| Error::Internal(format!("invalid UTF-8 in string table: {e}")))?;
327        previous_offset = current;
328    }
329    Ok(blob_end)
330}
331
332/// Read the string table. Returns (strings, byte position after string table).
333fn read_string_table<'a>(
334    buf: &'a [u8],
335    offset: usize,
336    budget: &mut DecodeBudget,
337) -> Result<(Vec<&'a str>, usize)> {
338    let blob_end = validate_string_table_layout(buf, offset)?;
339    let header_end = checked_end(offset, 8, "string table header")?;
340    let count = read_u32(buf, offset, "string table header")? as usize;
341    let blob_size = read_u32(
342        buf,
343        checked_end(offset, 4, "string table header")?,
344        "string table header",
345    )? as usize;
346    let offsets_start = header_end;
347    let offsets_end = checked_end(
348        offsets_start,
349        count.checked_mul(4).ok_or_else(|| {
350            Error::Internal("string table offsets exceed addressable buffer size".to_string())
351        })?,
352        "string table offsets",
353    )?;
354    let blob_start = offsets_end;
355
356    let mut string_offsets = Vec::new();
357    budget.charge_array::<usize>(count)?;
358    string_offsets
359        .try_reserve_exact(count)
360        .map_err(|_| Error::Internal("string table offset allocation failed".to_string()))?;
361    for i in 0..count {
362        let pos = checked_end(
363            offsets_start,
364            i.checked_mul(4).ok_or_else(|| {
365                Error::Internal("string table offsets exceed addressable buffer size".to_string())
366            })?,
367            "string table offsets",
368        )?;
369        let off = read_u32(buf, pos, "string table offset")? as usize;
370        if i == 0 && off != 0 {
371            return Err(Error::Internal(
372                "first string table offset must be zero".to_string(),
373            ));
374        }
375        string_offsets.push(off);
376    }
377
378    let mut strings = Vec::new();
379    budget.charge_array::<&str>(count)?;
380    strings
381        .try_reserve_exact(count)
382        .map_err(|_| Error::Internal("string table allocation failed".to_string()))?;
383    let mut previous_offset = 0;
384    for i in 0..count {
385        let offset = string_offsets[i];
386        if offset > blob_size || offset < previous_offset {
387            return Err(Error::Internal(
388                "string table offsets must be monotonic and within the blob".to_string(),
389            ));
390        }
391        let next_offset = string_offsets.get(i + 1).copied().unwrap_or(blob_size);
392        if next_offset > blob_size || next_offset < offset {
393            return Err(Error::Internal(
394                "string table offsets must be monotonic and within the blob".to_string(),
395            ));
396        }
397        let start = checked_end(blob_start, offset, "string table blob")?;
398        let end = checked_end(blob_start, next_offset, "string table blob")?;
399        let s = std::str::from_utf8(&buf[start..end])
400            .map_err(|e| Error::Internal(format!("invalid UTF-8 in string table: {e}")))?;
401        strings.push(s);
402        previous_offset = offset;
403    }
404
405    Ok((strings, blob_end))
406}
407
408fn preflight_sparse_cell_count(
409    buf: &[u8],
410    cell_data_start: usize,
411    row_index: &[(u32, u32)],
412    limits: TraversalLimits,
413) -> Result<u64> {
414    let mut expected_offset = 0usize;
415    let mut total_cells = 0u64;
416    for &(_, offset) in row_index {
417        let pos = checked_end(cell_data_start, expected_offset, "sparse row data")?;
418        let cell_count = read_u16(buf, pos, "sparse row cell count")? as usize;
419        if offset == EMPTY_ROW_SENTINEL && cell_count != 0 {
420            return Err(Error::Internal(
421                "sparse empty row must have zero cells".to_string(),
422            ));
423        }
424        if offset != EMPTY_ROW_SENTINEL && offset as usize != expected_offset {
425            return Err(Error::Internal(
426                "sparse row offsets are inconsistent".to_string(),
427            ));
428        }
429        let entries_len = cell_count.checked_mul(SPARSE_ENTRY_SIZE).ok_or_else(|| {
430            Error::Internal("sparse row entries exceed addressable buffer size".to_string())
431        })?;
432        let row_size = 2usize.checked_add(entries_len).ok_or_else(|| {
433            Error::Internal("sparse row entries exceed addressable buffer size".to_string())
434        })?;
435        let row_end = checked_end(pos, row_size, "sparse row entries")?;
436        if row_end > buf.len() {
437            return Err(Error::Internal(
438                "buffer too short for sparse row entries".to_string(),
439            ));
440        }
441        total_cells = total_cells
442            .checked_add(cell_count as u64)
443            .ok_or_else(|| Error::Internal("decoded cell count overflow".to_string()))?;
444        check_limit(
445            ResourceDimension::CellCount,
446            limits.max_cells(),
447            total_cells,
448        )?;
449        expected_offset = checked_end(expected_offset, row_size, "sparse row data")?;
450    }
451    Ok(total_cells)
452}
453
454struct DecodeBudget {
455    output_bytes: u64,
456    cells: u64,
457    limits: TraversalLimits,
458    formula: FormulaBudget,
459}
460
461impl DecodeBudget {
462    fn new(limits: TraversalLimits) -> Self {
463        Self {
464            output_bytes: 0,
465            cells: 0,
466            limits,
467            formula: FormulaBudget::secure_mutation(),
468        }
469    }
470
471    fn charge_output(&mut self, bytes: u64) -> Result<()> {
472        self.output_bytes = checked_output_add(self.output_bytes, bytes, self.limits)?;
473        Ok(())
474    }
475
476    fn charge_array<T>(&mut self, count: usize) -> Result<()> {
477        let count = u64::try_from(count).map_err(|_| {
478            Error::Internal("decoded collection count is not addressable".to_string())
479        })?;
480        let element_size = u64::try_from(std::mem::size_of::<T>())
481            .map_err(|_| Error::Internal("decoded element size is not addressable".to_string()))?;
482        let bytes = checked_output_mul(count, element_size, self.limits)?;
483        self.charge_output(bytes)
484    }
485
486    fn copy(&mut self, value: &str) -> Result<String> {
487        let bytes = u64::try_from(value.len())
488            .map_err(|_| Error::Internal("raw transfer string is not addressable".to_string()))?;
489        let next = checked_output_add(self.output_bytes, bytes, self.limits)?;
490        let copy = fallible_string_copy(value)?;
491        self.output_bytes = next;
492        Ok(copy)
493    }
494
495    fn charge_cells(&mut self, count: usize) -> Result<()> {
496        let next = self
497            .cells
498            .checked_add(count as u64)
499            .ok_or_else(|| Error::Internal("decoded cell count overflow".to_string()))?;
500        check_limit(ResourceDimension::CellCount, self.limits.max_cells(), next)?;
501        self.cells = next;
502        Ok(())
503    }
504
505    fn charge_formula(&self, bytes: usize) -> Result<()> {
506        let bytes = u64::try_from(bytes)
507            .map_err(|_| Error::Internal("raw transfer formula is not addressable".to_string()))?;
508        self.formula.charge_mutation_cells(1)?;
509        self.formula.charge_mutation_formula(bytes, bytes)
510    }
511}
512
513fn decode_cell_payload(
514    type_tag: u8,
515    payload: &[u8],
516    strings: &[&str],
517    budget: &mut DecodeBudget,
518) -> Result<CellValue> {
519    match type_tag {
520        TYPE_EMPTY => Ok(CellValue::Empty),
521        TYPE_NUMBER => {
522            let n = read_f64(payload, 0, "cell payload")?;
523            Ok(CellValue::Number(n))
524        }
525        TYPE_STRING => {
526            let idx = read_u32(payload, 0, "cell payload")? as usize;
527            let s = strings
528                .get(idx)
529                .ok_or_else(|| Error::Internal(format!("string index {idx} out of range")))?;
530            let s = budget.copy(s)?;
531            Ok(CellValue::String(s))
532        }
533        TYPE_BOOL => Ok(CellValue::Bool(
534            *payload
535                .first()
536                .ok_or_else(|| Error::Internal("buffer too short for cell payload".to_string()))?
537                != 0,
538        )),
539        TYPE_DATE => {
540            let n = read_f64(payload, 0, "cell payload")?;
541            Ok(CellValue::Date(n))
542        }
543        TYPE_ERROR => {
544            let idx = read_u32(payload, 0, "cell payload")? as usize;
545            let s = strings
546                .get(idx)
547                .ok_or_else(|| Error::Internal(format!("string index {idx} out of range")))?;
548            let s = budget.copy(s)?;
549            Ok(CellValue::Error(s))
550        }
551        TYPE_FORMULA => {
552            let idx = read_u32(payload, 0, "cell payload")? as usize;
553            let expr = strings
554                .get(idx)
555                .ok_or_else(|| Error::Internal(format!("string index {idx} out of range")))?;
556            budget.charge_formula(expr.len())?;
557            let expr = budget.copy(expr)?;
558            Ok(CellValue::Formula { expr, result: None })
559        }
560        TYPE_RICH_STRING => {
561            let idx = read_u32(payload, 0, "cell payload")? as usize;
562            let s = strings
563                .get(idx)
564                .ok_or_else(|| Error::Internal(format!("string index {idx} out of range")))?;
565            let s = budget.copy(s)?;
566            Ok(CellValue::String(s))
567        }
568        _ => Err(Error::Internal(format!(
569            "unknown cell type tag: {type_tag}"
570        ))),
571    }
572}
573
574fn read_dense_cells(
575    buf: &[u8],
576    cell_data_start: usize,
577    row_index: &[(u32, u32)],
578    col_count: u16,
579    strings: &[&str],
580    min_col: u32,
581    budget: &mut DecodeBudget,
582) -> Result<Vec<CellRow>> {
583    let row_size = (col_count as usize)
584        .checked_mul(CELL_STRIDE)
585        .ok_or_else(|| Error::Internal("dense row exceeds addressable buffer size".to_string()))?;
586    let mut result = Vec::new();
587    budget.charge_array::<CellRow>(row_index.len())?;
588    result
589        .try_reserve_exact(row_index.len())
590        .map_err(|_| Error::Internal("decoded row allocation failed".to_string()))?;
591    for (i, &(row_num, offset)) in row_index.iter().enumerate() {
592        if offset == EMPTY_ROW_SENTINEL {
593            return Err(Error::Internal(
594                "dense row index cannot be empty".to_string(),
595            ));
596        }
597        let expected_offset = i.checked_mul(row_size).ok_or_else(|| {
598            Error::Internal("dense row offset exceeds addressable buffer size".to_string())
599        })?;
600        if offset as usize != expected_offset {
601            return Err(Error::Internal(
602                "dense row offsets are inconsistent".to_string(),
603            ));
604        }
605        let row_start = checked_end(cell_data_start, expected_offset, "dense row data")?;
606        let row_end = checked_end(row_start, row_size, "dense row data")?;
607        if buf.len() < row_end {
608            return Err(Error::Internal(format!(
609                "buffer too short for dense row data at offset {}",
610                row_start
611            )));
612        }
613        let mut cells = Vec::new();
614        budget.charge_array::<(u32, CellValue)>(col_count as usize)?;
615        cells
616            .try_reserve_exact(col_count as usize)
617            .map_err(|_| Error::Internal("dense cell allocation failed".to_string()))?;
618        for c in 0..col_count as usize {
619            let cell_offset = checked_end(
620                row_start,
621                c.checked_mul(CELL_STRIDE).ok_or_else(|| {
622                    Error::Internal("dense cell offset exceeds addressable buffer size".to_string())
623                })?,
624                "dense cell data",
625            )?;
626            let type_tag = buf[cell_offset];
627            if type_tag == TYPE_EMPTY {
628                continue;
629            }
630            let payload = &buf[cell_offset + 1..cell_offset + 9];
631            let value = decode_cell_payload(type_tag, payload, strings, budget)?;
632            let col = min_col
633                .checked_add(c as u32)
634                .ok_or_else(|| Error::Internal("cell column is out of range".to_string()))?;
635            validate_coordinate(row_num, col)?;
636            cells.push((col, value));
637        }
638        if !cells.is_empty() {
639            result.push((row_num, cells));
640        }
641    }
642    Ok(result)
643}
644
645fn read_sparse_cells(
646    buf: &[u8],
647    cell_data_start: usize,
648    row_index: &[(u32, u32)],
649    strings: &[&str],
650    min_col: u32,
651    col_count: u16,
652    budget: &mut DecodeBudget,
653) -> Result<Vec<CellRow>> {
654    let mut result = Vec::new();
655    budget.charge_array::<CellRow>(row_index.len())?;
656    result
657        .try_reserve_exact(row_index.len())
658        .map_err(|_| Error::Internal("decoded row allocation failed".to_string()))?;
659    let mut expected_offset = 0usize;
660    for &(row_num, offset) in row_index {
661        if offset == EMPTY_ROW_SENTINEL {
662            let empty_pos = checked_end(cell_data_start, expected_offset, "sparse row data")?;
663            if read_u16(buf, empty_pos, "sparse empty row cell count")? != 0 {
664                return Err(Error::Internal(
665                    "sparse empty row must have zero cells".to_string(),
666                ));
667            }
668            expected_offset = checked_end(expected_offset, 2, "sparse row data")?;
669            continue;
670        }
671        if offset as usize != expected_offset {
672            return Err(Error::Internal(
673                "sparse row offsets are inconsistent".to_string(),
674            ));
675        }
676        let pos = checked_end(cell_data_start, expected_offset, "sparse row data")?;
677        let cell_count = read_u16(buf, pos, "sparse row cell count")? as usize;
678        let entries_start = checked_end(pos, 2, "sparse row data")?;
679        let entries_len = cell_count.checked_mul(SPARSE_ENTRY_SIZE).ok_or_else(|| {
680            Error::Internal("sparse row entries exceed addressable buffer size".to_string())
681        })?;
682        let entries_end = checked_end(entries_start, entries_len, "sparse row entries")?;
683        if buf.len() < entries_end {
684            return Err(Error::Internal(format!(
685                "buffer too short for sparse row entries at offset {}",
686                entries_start
687            )));
688        }
689        budget.charge_cells(cell_count)?;
690        let mut cells = Vec::new();
691        budget.charge_array::<(u32, CellValue)>(cell_count)?;
692        cells
693            .try_reserve_exact(cell_count)
694            .map_err(|_| Error::Internal("sparse cell allocation failed".to_string()))?;
695        let mut previous_col = None;
696        for i in 0..cell_count {
697            let entry_off = checked_end(
698                entries_start,
699                i.checked_mul(SPARSE_ENTRY_SIZE).ok_or_else(|| {
700                    Error::Internal("sparse row entries exceed addressable buffer size".to_string())
701                })?,
702                "sparse row entry",
703            )?;
704            let col = read_u16(buf, entry_off, "sparse cell column")?;
705            if col >= col_count {
706                return Err(Error::Internal(
707                    "sparse cell column is out of range".to_string(),
708                ));
709            }
710            if previous_col.is_some_and(|previous| col <= previous) {
711                return Err(Error::Internal(
712                    "sparse cell columns must be strictly increasing".to_string(),
713                ));
714            }
715            previous_col = Some(col);
716            let type_tag = *buf
717                .get(checked_end(entry_off, 2, "sparse row entry")?)
718                .ok_or_else(|| {
719                    Error::Internal("buffer too short for sparse cell type".to_string())
720                })?;
721            let payload_start = checked_end(entry_off, 3, "sparse row entry")?;
722            let payload_end = checked_end(entry_off, SPARSE_ENTRY_SIZE, "sparse row entry")?;
723            let payload = &buf[payload_start..payload_end];
724            let value = decode_cell_payload(type_tag, payload, strings, budget)?;
725            let col = min_col
726                .checked_add(col as u32)
727                .ok_or_else(|| Error::Internal("cell column is out of range".to_string()))?;
728            validate_coordinate(row_num, col)?;
729            cells.push((col, value));
730        }
731        expected_offset = checked_end(
732            expected_offset,
733            2usize.checked_add(entries_len).ok_or_else(|| {
734                Error::Internal("sparse row entries exceed addressable buffer size".to_string())
735            })?,
736            "sparse row data",
737        )?;
738        if !cells.is_empty() {
739            result.push((row_num, cells));
740        }
741    }
742    Ok(result)
743}
744
745/// Decode a raw buffer into cell values for applying to a worksheet.
746///
747/// Returns rows as `(row_number, cells)` where each cell is
748/// `(col_number, CellValue)`. Both row and column numbers are 1-based.
749pub fn raw_buffer_to_cells(buf: &[u8]) -> Result<Vec<CellRow>> {
750    raw_buffer_to_cells_with_limits(buf, TraversalLimits::default())
751}
752
753fn preflight_shifted_transfer_bounds(
754    buf: &[u8],
755    start_row: u32,
756    start_col: u32,
757    limits: TraversalLimits,
758) -> Result<()> {
759    crate::utils::cell_ref::compact_cell_ref(start_col, start_row)?;
760    if buf.len() < HEADER_SIZE {
761        return Err(Error::Internal(format!(
762            "buffer too short for header: {} bytes (need {})",
763            buf.len(),
764            HEADER_SIZE
765        )));
766    }
767
768    let magic = read_u32(buf, 0, "header")?;
769    let (row_count, col_count, flags, is_sparse) = if magic == MAGIC_V2 {
770        let version = read_u16(buf, 4, "header")?;
771        if version != VERSION_V2 {
772            return Err(Error::Internal(format!(
773                "unsupported buffer version: {version}"
774            )));
775        }
776        let row_count = read_u32(buf, 6, "header")?;
777        let col_count = read_u16(buf, 10, "header")?;
778        let flags = read_u32(buf, 12, "header")?;
779        if flags & 0x0000_FFFF != 0 {
780            return Err(Error::Internal("invalid v2 buffer flags".to_string()));
781        }
782        (row_count, col_count, flags, true)
783    } else {
784        let header = read_header(buf)?;
785        (
786            header.row_count,
787            header.col_count,
788            header.flags,
789            header.flags & FLAG_SPARSE != 0,
790        )
791    };
792    let min_col = validate_decode_layout(row_count, col_count, flags, is_sparse, limits)?;
793    if row_count == 0 {
794        return Ok(());
795    }
796
797    let row_index_size = (row_count as usize)
798        .checked_mul(ROW_INDEX_ENTRY_SIZE)
799        .ok_or_else(|| Error::Internal("row index exceeds addressable buffer size".to_string()))?;
800    let row_index_end = checked_end(HEADER_SIZE, row_index_size, "row index")?;
801    if buf.len() < row_index_end {
802        return Err(Error::Internal(format!(
803            "buffer too short for row index: {} bytes (need {})",
804            buf.len(),
805            row_index_end
806        )));
807    }
808    let last_row_offset = row_index_end - ROW_INDEX_ENTRY_SIZE;
809    let max_row = read_u32(buf, last_row_offset, "row index entry")?;
810    validate_coordinate(max_row, min_col)?;
811    max_row
812        .checked_sub(1)
813        .and_then(|offset| start_row.checked_add(offset))
814        .filter(|row| *row <= MAX_ROWS)
815        .ok_or(Error::InvalidRowNumber(u32::MAX))?;
816
817    let max_col = min_col
818        .checked_add(u32::from(col_count) - 1)
819        .ok_or(Error::InvalidColumnNumber(u32::MAX))?;
820    max_col
821        .checked_sub(1)
822        .and_then(|offset| start_col.checked_add(offset))
823        .filter(|col| *col <= MAX_COLUMNS)
824        .ok_or(Error::InvalidColumnNumber(u32::MAX))?;
825    Ok(())
826}
827
828/// Decode and shift raw-transfer values for one atomic workbook mutation.
829///
830/// Formula limits are consumed during decoding and are not reset when the
831/// opaque result is applied to a workbook.
832pub fn raw_buffer_to_validated_cell_transfer(
833    buf: &[u8],
834    start_row: u32,
835    start_col: u32,
836) -> Result<ValidatedCellTransfer> {
837    raw_buffer_to_validated_cell_transfer_with_limits(
838        buf,
839        start_row,
840        start_col,
841        TraversalLimits::default(),
842    )
843}
844
845fn raw_buffer_to_validated_cell_transfer_with_limits(
846    buf: &[u8],
847    start_row: u32,
848    start_col: u32,
849    limits: TraversalLimits,
850) -> Result<ValidatedCellTransfer> {
851    preflight_shifted_transfer_bounds(buf, start_row, start_col, limits)?;
852    let mut budget = DecodeBudget::new(limits);
853    let rows = raw_buffer_to_cells_with_budget(buf, &mut budget)?;
854    let mut cell_count = 0u64;
855    let mut previous = None;
856
857    for (row, cells) in &rows {
858        let target_row = row
859            .checked_sub(1)
860            .and_then(|offset| start_row.checked_add(offset))
861            .filter(|row| *row <= MAX_ROWS)
862            .ok_or(Error::InvalidRowNumber(u32::MAX))?;
863        for (col, value) in cells {
864            let target_col = col
865                .checked_sub(1)
866                .and_then(|offset| start_col.checked_add(offset))
867                .filter(|col| *col <= MAX_COLUMNS)
868                .ok_or(Error::InvalidColumnNumber(u32::MAX))?;
869            let coordinate = (target_row, target_col);
870            if previous.is_some_and(|previous| coordinate <= previous) {
871                return Err(Error::InvalidArgument(
872                    "raw transfer destination coordinates must be unique and ordered".to_string(),
873                ));
874            }
875            previous = Some(coordinate);
876
877            if let CellValue::String(value) = value {
878                if value.len() > crate::utils::constants::MAX_CELL_CHARS {
879                    return Err(Error::CellValueTooLong {
880                        length: value.len(),
881                        max: crate::utils::constants::MAX_CELL_CHARS,
882                    });
883                }
884            }
885
886            cell_count = cell_count.checked_add(1).ok_or_else(|| {
887                Error::InvalidArgument("raw transfer cell count overflows".to_string())
888            })?;
889            check_limit(ResourceDimension::CellCount, limits.max_cells(), cell_count)?;
890            budget.charge_output(
891                u64::try_from(std::mem::size_of::<(String, CellValue)>()).unwrap_or(u64::MAX),
892            )?;
893            budget.charge_output(
894                u64::from(transfer_column_name_len(target_col))
895                    + u64::from(transfer_decimal_digits(target_row)),
896            )?;
897        }
898    }
899
900    let mut entries = Vec::new();
901    entries
902        .try_reserve_exact(usize::try_from(cell_count).map_err(|_| {
903            Error::InvalidArgument("raw transfer cell count is not addressable".to_string())
904        })?)
905        .map_err(|_| Error::Internal("raw transfer destination allocation failed".to_string()))?;
906    for (row, cells) in rows {
907        let target_row = start_row + row - 1;
908        for (col, value) in cells {
909            let target_col = start_col + col - 1;
910            let cell = crate::utils::cell_ref::coordinates_to_cell_name(target_col, target_row)?;
911            entries.push((cell, value));
912        }
913    }
914    Ok(ValidatedCellTransfer { entries })
915}
916
917const fn transfer_column_name_len(column: u32) -> u32 {
918    if column <= 26 {
919        1
920    } else if column <= 26 * 27 {
921        2
922    } else {
923        3
924    }
925}
926
927const fn transfer_decimal_digits(mut value: u32) -> u32 {
928    let mut digits = 1;
929    while value >= 10 {
930        value /= 10;
931        digits += 1;
932    }
933    digits
934}
935
936fn raw_buffer_to_cells_with_limits(buf: &[u8], limits: TraversalLimits) -> Result<Vec<CellRow>> {
937    let mut budget = DecodeBudget::new(limits);
938    raw_buffer_to_cells_with_budget(buf, &mut budget)
939}
940
941fn raw_buffer_to_cells_with_budget(buf: &[u8], budget: &mut DecodeBudget) -> Result<Vec<CellRow>> {
942    if buf.len() < HEADER_SIZE {
943        return Err(Error::Internal(format!(
944            "buffer too short for header: {} bytes (need {})",
945            buf.len(),
946            HEADER_SIZE
947        )));
948    }
949    if read_u32(buf, 0, "header")? == MAGIC_V2 {
950        return raw_buffer_v2_to_cells(buf, budget);
951    }
952    let limits = budget.limits;
953    let header = read_header(buf)?;
954    if header.row_count == 0
955        && header.col_count == 0
956        && header.flags == 0
957        && buf.len() == HEADER_SIZE
958    {
959        return Ok(Vec::new());
960    }
961    let is_sparse = header.flags & FLAG_SPARSE != 0;
962    let min_col = validate_decode_layout(
963        header.row_count,
964        header.col_count,
965        header.flags,
966        is_sparse,
967        limits,
968    )?;
969    let row_index = read_row_index(buf, header.row_count, budget)?;
970    let row_index_size = (header.row_count as usize)
971        .checked_mul(ROW_INDEX_ENTRY_SIZE)
972        .ok_or_else(|| Error::Internal("row index exceeds addressable buffer size".to_string()))?;
973    let string_table_offset = checked_end(HEADER_SIZE, row_index_size, "row index")?;
974    let cell_data_start = validate_string_table_layout(buf, string_table_offset)?;
975    if is_sparse {
976        preflight_sparse_cell_count(buf, cell_data_start, &row_index, limits)?;
977    }
978    let (strings, materialized_cell_data_start) =
979        read_string_table(buf, string_table_offset, budget)?;
980    debug_assert_eq!(cell_data_start, materialized_cell_data_start);
981    if !is_sparse {
982        let dense_cells = (header.row_count as usize)
983            .checked_mul(header.col_count as usize)
984            .ok_or_else(|| Error::Internal("dense cell count overflow".to_string()))?;
985        budget.charge_cells(dense_cells)?;
986    }
987    let rows = if is_sparse {
988        read_sparse_cells(
989            buf,
990            cell_data_start,
991            &row_index,
992            &strings,
993            min_col,
994            header.col_count,
995            budget,
996        )?
997    } else {
998        read_dense_cells(
999            buf,
1000            cell_data_start,
1001            &row_index,
1002            header.col_count,
1003            &strings,
1004            min_col,
1005            budget,
1006        )?
1007    };
1008    let expected_cell_data_len = if is_sparse {
1009        let mut size = 0usize;
1010        for &(_, offset) in &row_index {
1011            let pos = checked_end(cell_data_start, size, "sparse row data")?;
1012            let cell_count = read_u16(buf, pos, "sparse row cell count")? as usize;
1013            let row_size = 2usize
1014                .checked_add(cell_count.checked_mul(SPARSE_ENTRY_SIZE).ok_or_else(|| {
1015                    Error::Internal("sparse row entries exceed addressable buffer size".to_string())
1016                })?)
1017                .ok_or_else(|| {
1018                    Error::Internal("sparse row entries exceed addressable buffer size".to_string())
1019                })?;
1020            if offset != EMPTY_ROW_SENTINEL && offset as usize != size {
1021                return Err(Error::Internal(
1022                    "sparse row offsets are inconsistent".to_string(),
1023                ));
1024            }
1025            size = checked_end(size, row_size, "sparse row data")?;
1026        }
1027        size
1028    } else {
1029        (header.row_count as usize)
1030            .checked_mul(header.col_count as usize)
1031            .and_then(|n| n.checked_mul(CELL_STRIDE))
1032            .ok_or_else(|| {
1033                Error::Internal("dense cell data exceeds addressable buffer size".to_string())
1034            })?
1035    };
1036    let expected_end = checked_end(cell_data_start, expected_cell_data_len, "cell data")?;
1037    if expected_end != buf.len() {
1038        return Err(Error::Internal(
1039            "buffer has trailing data or inconsistent cell section".to_string(),
1040        ));
1041    }
1042    Ok(rows)
1043}
1044
1045fn raw_buffer_v2_to_cells(buf: &[u8], budget: &mut DecodeBudget) -> Result<Vec<CellRow>> {
1046    let limits = budget.limits;
1047    let version = read_u16(buf, 4, "header")?;
1048    if version != VERSION_V2 {
1049        return Err(Error::Internal(format!(
1050            "unsupported buffer version: {version}"
1051        )));
1052    }
1053    let row_count = read_u32(buf, 6, "header")?;
1054    let col_count = read_u16(buf, 10, "header")?;
1055    let flags = read_u32(buf, 12, "header")?;
1056    if flags & 0x0000_FFFF != 0 {
1057        return Err(Error::Internal("invalid v2 buffer flags".to_string()));
1058    }
1059    if row_count == 0 && col_count == 0 && flags == 0 && buf.len() == HEADER_SIZE {
1060        return Ok(Vec::new());
1061    }
1062    let min_col = validate_decode_layout(row_count, col_count, flags, true, limits)?;
1063    let row_index = read_row_index(buf, row_count, budget)?;
1064    let row_index_size = (row_count as usize)
1065        .checked_mul(ROW_INDEX_ENTRY_SIZE)
1066        .ok_or_else(|| Error::Internal("row index exceeds addressable buffer size".to_string()))?;
1067    let cell_data_start = checked_end(HEADER_SIZE, row_index_size, "row index")?;
1068    let mut expected_offset = 0usize;
1069    let mut result = Vec::new();
1070    budget.charge_array::<CellRow>(row_index.len())?;
1071    result
1072        .try_reserve_exact(row_index.len())
1073        .map_err(|_| Error::Internal("decoded row allocation failed".to_string()))?;
1074
1075    for &(row_num, offset) in &row_index {
1076        let pos = checked_end(cell_data_start, expected_offset, "v2 row data")?;
1077        let cell_count = read_u16(buf, pos, "v2 row cell count")? as usize;
1078        if offset == EMPTY_ROW_SENTINEL {
1079            if cell_count != 0 {
1080                return Err(Error::Internal(
1081                    "v2 empty row must have zero cells".to_string(),
1082                ));
1083            }
1084            expected_offset = checked_end(expected_offset, 2, "v2 row data")?;
1085            continue;
1086        }
1087        if offset as usize != expected_offset {
1088            return Err(Error::Internal(
1089                "v2 row offsets are inconsistent".to_string(),
1090            ));
1091        }
1092        if cell_count > usize::from(col_count) {
1093            return Err(Error::Internal(
1094                "v2 cell count exceeds the column span".to_string(),
1095            ));
1096        }
1097        let mut cursor = checked_end(pos, 2, "v2 row data")?;
1098        let minimum_cell_bytes = cell_count.checked_mul(3).ok_or_else(|| {
1099            Error::Internal("declared v2 cell count exceeds addressable size".to_string())
1100        })?;
1101        let minimum_end = checked_end(cursor, minimum_cell_bytes, "v2 cell headers")?;
1102        if minimum_end > buf.len() {
1103            return Err(Error::Internal(
1104                "declared v2 cell count exceeds remaining payload".to_string(),
1105            ));
1106        }
1107        budget.charge_cells(cell_count)?;
1108        let mut cells = Vec::new();
1109        budget.charge_array::<(u32, CellValue)>(cell_count)?;
1110        cells
1111            .try_reserve_exact(cell_count)
1112            .map_err(|_| Error::Internal("v2 cell result allocation failed".to_string()))?;
1113        let mut previous_col = None;
1114        for _ in 0..cell_count {
1115            let col = read_u16(buf, cursor, "v2 cell column")?;
1116            if col >= col_count {
1117                return Err(Error::Internal(
1118                    "v2 cell column is out of range".to_string(),
1119                ));
1120            }
1121            if previous_col.is_some_and(|previous| col <= previous) {
1122                return Err(Error::Internal(
1123                    "v2 cell columns must be strictly increasing".to_string(),
1124                ));
1125            }
1126            previous_col = Some(col);
1127            let type_tag = *buf
1128                .get(checked_end(cursor, 2, "v2 cell")?)
1129                .ok_or_else(|| Error::Internal("buffer too short for v2 cell type".to_string()))?;
1130            let payload_start = checked_end(cursor, 3, "v2 cell")?;
1131            let (value, payload_size) = match type_tag {
1132                TYPE_EMPTY => (CellValue::Empty, 0),
1133                TYPE_NUMBER => (
1134                    CellValue::Number(read_f64(buf, payload_start, "v2 number payload")?),
1135                    8,
1136                ),
1137                TYPE_DATE => (
1138                    CellValue::Date(read_f64(buf, payload_start, "v2 date payload")?),
1139                    8,
1140                ),
1141                TYPE_BOOL => (
1142                    CellValue::Bool(
1143                        *buf.get(payload_start).ok_or_else(|| {
1144                            Error::Internal("buffer too short for v2 bool payload".to_string())
1145                        })? != 0,
1146                    ),
1147                    1,
1148                ),
1149                TYPE_STRING | TYPE_ERROR | TYPE_FORMULA | TYPE_RICH_STRING => {
1150                    let byte_len = read_u32(buf, payload_start, "v2 string length")? as usize;
1151                    let text_start = checked_end(payload_start, 4, "v2 string payload")?;
1152                    let text_end = checked_end(text_start, byte_len, "v2 string payload")?;
1153                    if type_tag == TYPE_FORMULA {
1154                        budget.charge_formula(byte_len)?;
1155                    }
1156                    let text =
1157                        std::str::from_utf8(buf.get(text_start..text_end).ok_or_else(|| {
1158                            Error::Internal("buffer too short for v2 string payload".to_string())
1159                        })?)
1160                        .map_err(|e| {
1161                            Error::Internal(format!("invalid UTF-8 in v2 string payload: {e}"))
1162                        })?;
1163                    let text = budget.copy(text)?;
1164                    let value = match type_tag {
1165                        TYPE_STRING | TYPE_RICH_STRING => CellValue::String(text),
1166                        TYPE_ERROR => CellValue::Error(text),
1167                        TYPE_FORMULA => CellValue::Formula {
1168                            expr: text,
1169                            result: None,
1170                        },
1171                        _ => unreachable!(),
1172                    };
1173                    (
1174                        value,
1175                        4usize.checked_add(byte_len).ok_or_else(|| {
1176                            Error::Internal(
1177                                "v2 string payload exceeds addressable buffer size".to_string(),
1178                            )
1179                        })?,
1180                    )
1181                }
1182                _ => {
1183                    return Err(Error::Internal(format!(
1184                        "unknown cell type tag: {type_tag}"
1185                    )))
1186                }
1187            };
1188            let cell_size = 3usize.checked_add(payload_size).ok_or_else(|| {
1189                Error::Internal("v2 cell exceeds addressable buffer size".to_string())
1190            })?;
1191            cursor = checked_end(cursor, cell_size, "v2 cell")?;
1192            if !matches!(value, CellValue::Empty) {
1193                let col = min_col
1194                    .checked_add(col as u32)
1195                    .ok_or_else(|| Error::Internal("cell column is out of range".to_string()))?;
1196                validate_coordinate(row_num, col)?;
1197                cells.push((col, value));
1198            }
1199        }
1200        expected_offset = cursor
1201            .checked_sub(cell_data_start)
1202            .ok_or_else(|| Error::Internal("v2 cell offset precedes data section".to_string()))?;
1203        if !cells.is_empty() {
1204            result.push((row_num, cells));
1205        }
1206    }
1207    let expected_end = checked_end(cell_data_start, expected_offset, "v2 cell data")?;
1208    if expected_end != buf.len() {
1209        return Err(Error::Internal(
1210            "buffer has trailing data or inconsistent cell section".to_string(),
1211        ));
1212    }
1213    Ok(result)
1214}
1215
1216struct StringTable {
1217    strings: Vec<String>,
1218    index_map: HashMap<String, u32>,
1219    hash_index: HashMap<(u64, usize), Vec<u32>>,
1220    base_output_size: u64,
1221    encoded_size: u64,
1222    limits: TraversalLimits,
1223}
1224
1225impl StringTable {
1226    fn new(base_output_size: u64, limits: TraversalLimits) -> Result<Self> {
1227        checked_output_add(base_output_size, 8, limits)?;
1228        Ok(Self {
1229            strings: Vec::new(),
1230            index_map: HashMap::new(),
1231            hash_index: HashMap::new(),
1232            base_output_size,
1233            encoded_size: 8,
1234            limits,
1235        })
1236    }
1237
1238    fn ensure_candidate_fits(&self, len: u64) -> Result<u64> {
1239        let entry_size = checked_output_add(4, len, self.limits)?;
1240        let encoded_size = checked_output_add(self.encoded_size, entry_size, self.limits)?;
1241        checked_output_add(self.base_output_size, encoded_size, self.limits)?;
1242        Ok(encoded_size)
1243    }
1244
1245    fn intern(&mut self, s: &str) -> Result<u32> {
1246        if let Some(&idx) = self.index_map.get(s) {
1247            return Ok(idx);
1248        }
1249        let encoded_size = self.ensure_candidate_fits(s.len() as u64)?;
1250        let idx = u32::try_from(self.strings.len())
1251            .map_err(|_| Error::Internal("string table count exceeds format".to_string()))?;
1252        self.strings
1253            .try_reserve(1)
1254            .map_err(|_| Error::Internal("string table allocation failed".to_string()))?;
1255        self.index_map
1256            .try_reserve(1)
1257            .map_err(|_| Error::Internal("string index allocation failed".to_string()))?;
1258        let hash_key = (hash_chunks([s.as_bytes()]), s.len());
1259        let new_hash_candidates = if let Some(candidates) = self.hash_index.get_mut(&hash_key) {
1260            candidates
1261                .try_reserve(1)
1262                .map_err(|_| Error::Internal("string hash index allocation failed".to_string()))?;
1263            None
1264        } else {
1265            self.hash_index
1266                .try_reserve(1)
1267                .map_err(|_| Error::Internal("string hash index allocation failed".to_string()))?;
1268            let mut candidates = Vec::new();
1269            candidates
1270                .try_reserve_exact(1)
1271                .map_err(|_| Error::Internal("string hash index allocation failed".to_string()))?;
1272            Some(candidates)
1273        };
1274        let stored = fallible_string_copy(s)?;
1275        let key = fallible_string_copy(s)?;
1276        self.strings.push(stored);
1277        self.index_map.insert(key, idx);
1278        if let Some(mut candidates) = new_hash_candidates {
1279            candidates.push(idx);
1280            self.hash_index.insert(hash_key, candidates);
1281        } else {
1282            self.hash_index
1283                .get_mut(&hash_key)
1284                .expect("existing hash candidate list")
1285                .push(idx);
1286        }
1287        self.encoded_size = encoded_size;
1288        Ok(idx)
1289    }
1290}
1291
1292fn hash_chunks<'a>(chunks: impl IntoIterator<Item = &'a [u8]>) -> u64 {
1293    let mut hasher = DefaultHasher::new();
1294    for chunk in chunks {
1295        hasher.write(chunk);
1296    }
1297    hasher.finish()
1298}
1299
1300fn fallible_string_copy(value: &str) -> Result<String> {
1301    let mut copy = String::new();
1302    copy.try_reserve_exact(value.len())
1303        .map_err(|_| Error::Internal("raw transfer string allocation failed".to_string()))?;
1304    copy.push_str(value);
1305    Ok(copy)
1306}
1307
1308fn cell_type_tag(value: &CellValue) -> u8 {
1309    match value {
1310        CellValue::Empty => TYPE_EMPTY,
1311        CellValue::Number(_) => TYPE_NUMBER,
1312        CellValue::String(_) => TYPE_STRING,
1313        CellValue::Bool(_) => TYPE_BOOL,
1314        CellValue::Date(_) => TYPE_DATE,
1315        CellValue::Error(_) => TYPE_ERROR,
1316        CellValue::Formula { .. } => TYPE_FORMULA,
1317        CellValue::RichString(_) => TYPE_RICH_STRING,
1318    }
1319}
1320
1321fn encode_cell_payload(value: &CellValue, st: &mut StringTable) -> Result<[u8; 8]> {
1322    let mut payload = [0u8; 8];
1323    match value {
1324        CellValue::Empty => {}
1325        CellValue::Number(n) => {
1326            payload[0..8].copy_from_slice(&n.to_le_bytes());
1327        }
1328        CellValue::String(s) => {
1329            let idx = st.intern(s)?;
1330            payload[0..4].copy_from_slice(&idx.to_le_bytes());
1331        }
1332        CellValue::Bool(b) => {
1333            payload[0] = u8::from(*b);
1334        }
1335        CellValue::Date(n) => {
1336            payload[0..8].copy_from_slice(&n.to_le_bytes());
1337        }
1338        CellValue::Error(s) => {
1339            let idx = st.intern(s)?;
1340            payload[0..4].copy_from_slice(&idx.to_le_bytes());
1341        }
1342        CellValue::Formula { expr, .. } => {
1343            let idx = st.intern(expr)?;
1344            payload[0..4].copy_from_slice(&idx.to_le_bytes());
1345        }
1346        CellValue::RichString(runs) => {
1347            let plain_len = runs.iter().try_fold(0usize, |total, run| {
1348                total
1349                    .checked_add(run.text.len())
1350                    .ok_or_else(|| Error::Internal("rich text size overflow".to_string()))
1351            })?;
1352            let hash_key = (
1353                hash_chunks(runs.iter().map(|run| run.text.as_bytes())),
1354                plain_len,
1355            );
1356            let existing = st.hash_index.get(&hash_key).and_then(|candidates| {
1357                candidates.iter().copied().find(|&index| {
1358                    st.strings[index as usize]
1359                        .as_bytes()
1360                        .iter()
1361                        .copied()
1362                        .eq(runs
1363                            .iter()
1364                            .flat_map(|run| run.text.as_bytes().iter().copied()))
1365                })
1366            });
1367            let idx = if let Some(index) = existing {
1368                index
1369            } else {
1370                st.ensure_candidate_fits(plain_len as u64)?;
1371                let mut plain = String::new();
1372                plain
1373                    .try_reserve_exact(plain_len)
1374                    .map_err(|_| Error::Internal("rich text allocation failed".to_string()))?;
1375                for run in runs {
1376                    plain.push_str(&run.text);
1377                }
1378                st.intern(&plain)?
1379            };
1380            payload[0..4].copy_from_slice(&idx.to_le_bytes());
1381        }
1382    }
1383    Ok(payload)
1384}
1385
1386/// Encode cell values into a raw buffer for transfer.
1387///
1388/// Takes rows as `(row_number, cells)` where each cell is
1389/// `(col_number, CellValue)`. Both row and column numbers are 1-based.
1390/// Returns the encoded binary buffer.
1391pub fn cells_to_raw_buffer(rows: &[(u32, Vec<(u32, CellValue)>)]) -> Result<Vec<u8>> {
1392    if rows.is_empty() {
1393        return write_empty_buffer();
1394    }
1395
1396    let limits = TraversalLimits::default();
1397    let row_count = u32::try_from(rows.len())
1398        .map_err(|_| Error::Internal("row count exceeds transfer format".to_string()))?;
1399    check_limit(
1400        ResourceDimension::RowCount,
1401        limits.max_rows(),
1402        u64::from(row_count),
1403    )?;
1404
1405    let mut max_col = 0u32;
1406    let mut total_cells = 0u64;
1407    let mut previous_row = 0u32;
1408    for (row_num, cells) in rows {
1409        validate_coordinate(*row_num, 1)?;
1410        if *row_num <= previous_row {
1411            return Err(Error::Internal(
1412                "row numbers must be strictly increasing".to_string(),
1413            ));
1414        }
1415        previous_row = *row_num;
1416        let mut previous_col = 0u32;
1417        for (col, _) in cells {
1418            let col = *col;
1419            validate_coordinate(*row_num, col)?;
1420            if col <= previous_col {
1421                return Err(Error::Internal(
1422                    "cell columns must be strictly increasing".to_string(),
1423                ));
1424            }
1425            previous_col = col;
1426            max_col = max_col.max(col);
1427        }
1428        total_cells = total_cells
1429            .checked_add(cells.len() as u64)
1430            .ok_or_else(|| Error::Internal("cell count exceeds addressable size".to_string()))?;
1431    }
1432    check_limit(
1433        ResourceDimension::CellCount,
1434        limits.max_cells(),
1435        total_cells,
1436    )?;
1437    if total_cells == 0 {
1438        return write_empty_buffer();
1439    }
1440
1441    let col_count = u16::try_from(max_col)
1442        .map_err(|_| Error::Internal("cell column is out of range".to_string()))?;
1443    check_limit(
1444        ResourceDimension::ColumnCount,
1445        limits.max_columns(),
1446        u64::from(col_count),
1447    )?;
1448
1449    let grid_size = u64::from(row_count)
1450        .checked_mul(u64::from(col_count))
1451        .ok_or_else(|| Error::Internal("transfer grid size overflow".to_string()))?;
1452    let density = if grid_size > 0 {
1453        total_cells as f64 / grid_size as f64
1454    } else {
1455        0.0
1456    };
1457    let is_sparse = density < DENSITY_THRESHOLD;
1458
1459    let row_index_size =
1460        checked_output_mul(u64::from(row_count), ROW_INDEX_ENTRY_SIZE as u64, limits)?;
1461    let cell_data_size = if is_sparse {
1462        compute_sparse_input_size(rows, limits)?
1463    } else {
1464        compute_dense_size(row_count, col_count, limits)?
1465    };
1466    let mut base_output_size = checked_output_add(HEADER_SIZE as u64, row_index_size, limits)?;
1467    base_output_size = checked_output_add(base_output_size, cell_data_size, limits)?;
1468
1469    let mut st = StringTable::new(base_output_size, limits)?;
1470    let mut row_payloads: Vec<EncodedRow> = Vec::new();
1471    row_payloads
1472        .try_reserve_exact(rows.len())
1473        .map_err(|_| Error::Internal("row payload allocation failed".to_string()))?;
1474    for &(row_num, ref cells) in rows {
1475        let mut encoded_cells = Vec::new();
1476        encoded_cells
1477            .try_reserve_exact(cells.len())
1478            .map_err(|_| Error::Internal("cell payload allocation failed".to_string()))?;
1479        for &(col, ref value) in cells {
1480            let tag = cell_type_tag(value);
1481            let payload = encode_cell_payload(value, &mut st)?;
1482            let zero_based_col = col
1483                .checked_sub(1)
1484                .and_then(|value| u16::try_from(value).ok())
1485                .ok_or_else(|| Error::Internal("cell column is out of range".to_string()))?;
1486            encoded_cells.push((zero_based_col, tag, payload));
1487        }
1488        row_payloads.push((row_num, encoded_cells));
1489    }
1490
1491    let string_table_size = compute_string_table_size(&st, limits)?;
1492    let exact_cell_data_size = if is_sparse {
1493        compute_sparse_size(&row_payloads, limits)?
1494    } else {
1495        cell_data_size
1496    };
1497
1498    let mut total_size = checked_output_add(HEADER_SIZE as u64, row_index_size, limits)?;
1499    total_size = checked_output_add(total_size, string_table_size, limits)?;
1500    total_size = checked_output_add(total_size, exact_cell_data_size, limits)?;
1501    let total_size = usize::try_from(total_size)
1502        .map_err(|_| Error::Internal("raw transfer output is not addressable".to_string()))?;
1503    let row_index_size = usize::try_from(row_index_size)
1504        .map_err(|_| Error::Internal("row index is not addressable".to_string()))?;
1505    let string_table_size = usize::try_from(string_table_size)
1506        .map_err(|_| Error::Internal("string table is not addressable".to_string()))?;
1507    let mut buf = Vec::new();
1508    buf.try_reserve_exact(total_size)
1509        .map_err(|_| Error::Internal("raw transfer output allocation failed".to_string()))?;
1510    buf.resize(total_size, 0);
1511
1512    write_header(
1513        &mut buf,
1514        row_count,
1515        col_count,
1516        if is_sparse { FLAG_SPARSE } else { 0 },
1517    );
1518
1519    let string_table_start = checked_end(HEADER_SIZE, row_index_size, "raw transfer output")?;
1520    let cell_data_start =
1521        checked_end(string_table_start, string_table_size, "raw transfer output")?;
1522
1523    if is_sparse {
1524        write_sparse_data(&mut buf, &row_payloads, cell_data_start)?;
1525    } else {
1526        write_dense_data(&mut buf, &row_payloads, col_count, cell_data_start)?;
1527    }
1528
1529    write_row_index(&mut buf, &row_payloads, is_sparse, col_count)?;
1530    write_string_table(&mut buf, string_table_start, &st)?;
1531
1532    Ok(buf)
1533}
1534
1535fn write_empty_buffer() -> Result<Vec<u8>> {
1536    let st_size = 8; // count(4) + blob_size(4), both zero
1537    let total = HEADER_SIZE + st_size;
1538    let mut buf = vec![0u8; total];
1539    write_header(&mut buf, 0, 0, 0);
1540    // String table: count=0, blob_size=0
1541    buf[HEADER_SIZE..HEADER_SIZE + 4].copy_from_slice(&0u32.to_le_bytes());
1542    buf[HEADER_SIZE + 4..HEADER_SIZE + 8].copy_from_slice(&0u32.to_le_bytes());
1543    Ok(buf)
1544}
1545
1546fn write_header(buf: &mut [u8], row_count: u32, col_count: u16, flags: u32) {
1547    buf[0..4].copy_from_slice(&MAGIC.to_le_bytes());
1548    buf[4..6].copy_from_slice(&VERSION.to_le_bytes());
1549    buf[6..10].copy_from_slice(&row_count.to_le_bytes());
1550    buf[10..12].copy_from_slice(&col_count.to_le_bytes());
1551    buf[12..16].copy_from_slice(&flags.to_le_bytes());
1552}
1553
1554fn compute_string_table_size(st: &StringTable, limits: TraversalLimits) -> Result<u64> {
1555    let blob_size = st.strings.iter().try_fold(0u64, |total, string| {
1556        total
1557            .checked_add(string.len() as u64)
1558            .ok_or_else(|| Error::Internal("string table size overflow".to_string()))
1559    })?;
1560    let offsets_size = checked_output_mul(st.strings.len() as u64, 4, limits)?;
1561    let size = checked_output_add(8, offsets_size, limits)?;
1562    checked_output_add(size, blob_size, limits)
1563}
1564
1565fn write_string_table(buf: &mut [u8], offset: usize, st: &StringTable) -> Result<()> {
1566    let count = u32::try_from(st.strings.len())
1567        .map_err(|_| Error::Internal("string table count exceeds format".to_string()))?;
1568    let blob_size = st.strings.iter().try_fold(0usize, |total, string| {
1569        total
1570            .checked_add(string.len())
1571            .ok_or_else(|| Error::Internal("string table size overflow".to_string()))
1572    })?;
1573    let blob_size_u32 = u32::try_from(blob_size)
1574        .map_err(|_| Error::Internal("string table blob exceeds format".to_string()))?;
1575
1576    buf[offset..offset + 4].copy_from_slice(&count.to_le_bytes());
1577    buf[offset + 4..offset + 8].copy_from_slice(&blob_size_u32.to_le_bytes());
1578
1579    let offsets_start = checked_end(offset, 8, "string table")?;
1580    let offsets_size = st
1581        .strings
1582        .len()
1583        .checked_mul(4)
1584        .ok_or_else(|| Error::Internal("string table offsets overflow".to_string()))?;
1585    let blob_start = checked_end(offsets_start, offsets_size, "string table")?;
1586
1587    let mut blob_offset: u32 = 0;
1588    for (i, s) in st.strings.iter().enumerate() {
1589        let pos = checked_end(
1590            offsets_start,
1591            i.checked_mul(4)
1592                .ok_or_else(|| Error::Internal("string table offsets overflow".to_string()))?,
1593            "string table offsets",
1594        )?;
1595        buf[pos..pos + 4].copy_from_slice(&blob_offset.to_le_bytes());
1596        let dst = checked_end(blob_start, blob_offset as usize, "string table blob")?;
1597        buf[dst..dst + s.len()].copy_from_slice(s.as_bytes());
1598        blob_offset =
1599            blob_offset
1600                .checked_add(u32::try_from(s.len()).map_err(|_| {
1601                    Error::Internal("string table entry exceeds format".to_string())
1602                })?)
1603                .ok_or_else(|| Error::Internal("string table blob exceeds format".to_string()))?;
1604    }
1605    Ok(())
1606}
1607
1608fn compute_dense_size(row_count: u32, col_count: u16, limits: TraversalLimits) -> Result<u64> {
1609    let cells = u64::from(row_count)
1610        .checked_mul(u64::from(col_count))
1611        .ok_or_else(|| Error::Internal("dense transfer grid size overflow".to_string()))?;
1612    checked_output_mul(cells, CELL_STRIDE as u64, limits)
1613}
1614
1615fn compute_sparse_size(row_payloads: &[EncodedRow], limits: TraversalLimits) -> Result<u64> {
1616    let mut size = 0u64;
1617    for (_, cells) in row_payloads {
1618        let entries = checked_output_mul(cells.len() as u64, SPARSE_ENTRY_SIZE as u64, limits)?;
1619        size = checked_output_add(size, 2, limits)?;
1620        size = checked_output_add(size, entries, limits)?;
1621    }
1622    Ok(size)
1623}
1624
1625fn compute_sparse_input_size(
1626    rows: &[(u32, Vec<(u32, CellValue)>)],
1627    limits: TraversalLimits,
1628) -> Result<u64> {
1629    let mut size = 0u64;
1630    for (_, cells) in rows {
1631        let entries = checked_output_mul(cells.len() as u64, SPARSE_ENTRY_SIZE as u64, limits)?;
1632        size = checked_output_add(size, 2, limits)?;
1633        size = checked_output_add(size, entries, limits)?;
1634    }
1635    Ok(size)
1636}
1637
1638fn write_row_index(
1639    buf: &mut [u8],
1640    row_payloads: &[EncodedRow],
1641    is_sparse: bool,
1642    col_count: u16,
1643) -> Result<()> {
1644    let base = HEADER_SIZE;
1645    if is_sparse {
1646        let mut data_offset = 0u32;
1647        for (i, (row_num, cells)) in row_payloads.iter().enumerate() {
1648            let pos = checked_end(
1649                base,
1650                i.checked_mul(ROW_INDEX_ENTRY_SIZE)
1651                    .ok_or_else(|| Error::Internal("row index offset overflow".to_string()))?,
1652                "row index",
1653            )?;
1654            buf[pos..pos + 4].copy_from_slice(&row_num.to_le_bytes());
1655            if cells.is_empty() {
1656                buf[pos + 4..pos + 8].copy_from_slice(&EMPTY_ROW_SENTINEL.to_le_bytes());
1657            } else {
1658                buf[pos + 4..pos + 8].copy_from_slice(&data_offset.to_le_bytes());
1659            }
1660            let row_size = cells
1661                .len()
1662                .checked_mul(SPARSE_ENTRY_SIZE)
1663                .and_then(|size| size.checked_add(2))
1664                .ok_or_else(|| Error::Internal("sparse row size overflow".to_string()))?;
1665            data_offset =
1666                data_offset
1667                    .checked_add(u32::try_from(row_size).map_err(|_| {
1668                        Error::Internal("sparse row size exceeds format".to_string())
1669                    })?)
1670                    .ok_or_else(|| Error::Internal("sparse offsets exceed format".to_string()))?;
1671        }
1672    } else {
1673        for (i, (row_num, _)) in row_payloads.iter().enumerate() {
1674            let pos = checked_end(
1675                base,
1676                i.checked_mul(ROW_INDEX_ENTRY_SIZE)
1677                    .ok_or_else(|| Error::Internal("row index offset overflow".to_string()))?,
1678                "row index",
1679            )?;
1680            buf[pos..pos + 4].copy_from_slice(&row_num.to_le_bytes());
1681            let offset = (i as u64)
1682                .checked_mul(u64::from(col_count))
1683                .and_then(|value| value.checked_mul(CELL_STRIDE as u64))
1684                .and_then(|value| u32::try_from(value).ok())
1685                .ok_or_else(|| Error::Internal("dense row offset exceeds format".to_string()))?;
1686            buf[pos + 4..pos + 8].copy_from_slice(&offset.to_le_bytes());
1687        }
1688    }
1689    Ok(())
1690}
1691
1692fn write_dense_data(
1693    buf: &mut [u8],
1694    row_payloads: &[EncodedRow],
1695    col_count: u16,
1696    cell_data_start: usize,
1697) -> Result<()> {
1698    for (i, (_, cells)) in row_payloads.iter().enumerate() {
1699        let row_offset = i
1700            .checked_mul(col_count as usize)
1701            .and_then(|value| value.checked_mul(CELL_STRIDE))
1702            .ok_or_else(|| Error::Internal("dense row offset overflow".to_string()))?;
1703        let row_start = checked_end(cell_data_start, row_offset, "dense row data")?;
1704        for &(col_idx, tag, ref payload) in cells {
1705            let cell_offset = (col_idx as usize)
1706                .checked_mul(CELL_STRIDE)
1707                .ok_or_else(|| Error::Internal("dense cell offset overflow".to_string()))?;
1708            let cell_off = checked_end(row_start, cell_offset, "dense cell data")?;
1709            buf[cell_off] = tag;
1710            buf[cell_off + 1..cell_off + 9].copy_from_slice(payload);
1711        }
1712    }
1713    Ok(())
1714}
1715
1716fn write_sparse_data(
1717    buf: &mut [u8],
1718    row_payloads: &[EncodedRow],
1719    cell_data_start: usize,
1720) -> Result<()> {
1721    let mut offset = cell_data_start;
1722    for (_, cells) in row_payloads {
1723        let cell_count = u16::try_from(cells.len())
1724            .map_err(|_| Error::Internal("sparse row cell count exceeds format".to_string()))?;
1725        buf[offset..offset + 2].copy_from_slice(&cell_count.to_le_bytes());
1726        offset = checked_end(offset, 2, "sparse row data")?;
1727        for &(col_idx, tag, ref payload) in cells {
1728            buf[offset..offset + 2].copy_from_slice(&col_idx.to_le_bytes());
1729            buf[offset + 2] = tag;
1730            buf[offset + 3..offset + 11].copy_from_slice(payload);
1731            offset = checked_end(offset, SPARSE_ENTRY_SIZE, "sparse cell data")?;
1732        }
1733    }
1734    Ok(())
1735}
1736
1737#[cfg(test)]
1738#[allow(clippy::needless_range_loop)]
1739mod tests {
1740    use super::*;
1741    use crate::rich_text::RichTextRun;
1742
1743    fn v2_formula_buffer(formula: &str) -> Vec<u8> {
1744        v2_formula_row(&[formula.to_string()])
1745    }
1746
1747    fn v2_formula_row(formulas: &[String]) -> Vec<u8> {
1748        let mut buffer = Vec::new();
1749        buffer.extend_from_slice(&MAGIC_V2.to_le_bytes());
1750        buffer.extend_from_slice(&VERSION_V2.to_le_bytes());
1751        buffer.extend_from_slice(&1u32.to_le_bytes());
1752        buffer.extend_from_slice(&(formulas.len() as u16).to_le_bytes());
1753        buffer.extend_from_slice(&0u32.to_le_bytes());
1754        buffer.extend_from_slice(&1u32.to_le_bytes());
1755        buffer.extend_from_slice(&0u32.to_le_bytes());
1756        buffer.extend_from_slice(&(formulas.len() as u16).to_le_bytes());
1757        for (col, formula) in formulas.iter().enumerate() {
1758            buffer.extend_from_slice(&(col as u16).to_le_bytes());
1759            buffer.push(TYPE_FORMULA);
1760            buffer.extend_from_slice(&(formula.len() as u32).to_le_bytes());
1761            buffer.extend_from_slice(formula.as_bytes());
1762        }
1763        buffer
1764    }
1765
1766    fn assert_formula_input_limit(error: Error, observed: u64) {
1767        let Error::ResourceLimitExceeded(metadata) = error else {
1768            panic!("expected a structured formula mutation limit error");
1769        };
1770        assert_eq!(metadata.operation_code(), "formula_mutate");
1771        assert_eq!(metadata.category_code(), "formula");
1772        assert_eq!(metadata.dimension_code(), "input_bytes");
1773        assert_eq!(metadata.limit(), 32_768);
1774        assert_eq!(metadata.observed(), observed);
1775        assert_eq!(metadata.stage_code(), Some("validate"));
1776    }
1777
1778    #[test]
1779    fn test_decode_empty_buffer() {
1780        let buf = cells_to_raw_buffer(&[]).unwrap();
1781        let result = raw_buffer_to_cells(&buf).unwrap();
1782        assert!(result.is_empty());
1783    }
1784
1785    #[test]
1786    fn test_decode_header_only_empty_buffers() {
1787        let mut v1 = vec![0u8; HEADER_SIZE];
1788        v1[0..4].copy_from_slice(&MAGIC.to_le_bytes());
1789        v1[4..6].copy_from_slice(&VERSION.to_le_bytes());
1790        assert!(raw_buffer_to_cells(&v1).unwrap().is_empty());
1791
1792        let mut v2 = vec![0u8; HEADER_SIZE];
1793        v2[0..4].copy_from_slice(&MAGIC_V2.to_le_bytes());
1794        v2[4..6].copy_from_slice(&VERSION_V2.to_le_bytes());
1795        assert!(raw_buffer_to_cells(&v2).unwrap().is_empty());
1796    }
1797
1798    #[test]
1799    fn test_decode_single_number() {
1800        let rows = vec![(1, vec![(1, CellValue::Number(42.5))])];
1801        let buf = cells_to_raw_buffer(&rows).unwrap();
1802        let result = raw_buffer_to_cells(&buf).unwrap();
1803        assert_eq!(result.len(), 1);
1804        assert_eq!(result[0].0, 1);
1805        assert_eq!(result[0].1.len(), 1);
1806        assert_eq!(result[0].1[0].0, 1);
1807        assert_eq!(result[0].1[0].1, CellValue::Number(42.5));
1808    }
1809
1810    #[test]
1811    fn test_decode_string_with_table() {
1812        let rows = vec![(1, vec![(1, CellValue::String("hello world".to_string()))])];
1813        let buf = cells_to_raw_buffer(&rows).unwrap();
1814        let result = raw_buffer_to_cells(&buf).unwrap();
1815        assert_eq!(result.len(), 1);
1816        assert_eq!(
1817            result[0].1[0].1,
1818            CellValue::String("hello world".to_string())
1819        );
1820    }
1821
1822    #[test]
1823    fn test_rejects_non_monotonic_string_offsets() {
1824        let rows = vec![(
1825            (1),
1826            vec![
1827                (1, CellValue::String("first".to_string())),
1828                (2, CellValue::String("second".to_string())),
1829            ],
1830        )];
1831        let mut buf = cells_to_raw_buffer(&rows).unwrap();
1832        let string_table = HEADER_SIZE + ROW_INDEX_ENTRY_SIZE;
1833        let offsets = string_table + 8;
1834        buf[offsets..offsets + 4].copy_from_slice(&4u32.to_le_bytes());
1835        buf[offsets + 4..offsets + 8].copy_from_slice(&0u32.to_le_bytes());
1836
1837        assert!(raw_buffer_to_cells(&buf).is_err());
1838    }
1839
1840    #[test]
1841    fn test_rejects_string_offset_past_blob() {
1842        let rows = vec![(1, vec![(1, CellValue::String("value".to_string()))])];
1843        let mut buf = cells_to_raw_buffer(&rows).unwrap();
1844        let string_table = HEADER_SIZE + ROW_INDEX_ENTRY_SIZE;
1845        let offsets = string_table + 8;
1846        buf[offsets..offsets + 4].copy_from_slice(&u32::MAX.to_le_bytes());
1847
1848        assert!(raw_buffer_to_cells(&buf).is_err());
1849    }
1850
1851    #[test]
1852    fn test_decode_bool_true_false() {
1853        let rows = vec![(
1854            1,
1855            vec![(1, CellValue::Bool(true)), (2, CellValue::Bool(false))],
1856        )];
1857        let buf = cells_to_raw_buffer(&rows).unwrap();
1858        let result = raw_buffer_to_cells(&buf).unwrap();
1859        assert_eq!(result[0].1[0].1, CellValue::Bool(true));
1860        assert_eq!(result[0].1[1].1, CellValue::Bool(false));
1861    }
1862
1863    #[test]
1864    fn test_decode_error() {
1865        let rows = vec![(1, vec![(1, CellValue::Error("#DIV/0!".to_string()))])];
1866        let buf = cells_to_raw_buffer(&rows).unwrap();
1867        let result = raw_buffer_to_cells(&buf).unwrap();
1868        assert_eq!(result[0].1[0].1, CellValue::Error("#DIV/0!".to_string()));
1869    }
1870
1871    #[test]
1872    fn test_decode_formula() {
1873        let rows = vec![(
1874            1,
1875            vec![(
1876                1,
1877                CellValue::Formula {
1878                    expr: "SUM(A1:A10)".to_string(),
1879                    result: None,
1880                },
1881            )],
1882        )];
1883        let buf = cells_to_raw_buffer(&rows).unwrap();
1884        let result = raw_buffer_to_cells(&buf).unwrap();
1885        assert_eq!(
1886            result[0].1[0].1,
1887            CellValue::Formula {
1888                expr: "SUM(A1:A10)".to_string(),
1889                result: None,
1890            }
1891        );
1892    }
1893
1894    #[test]
1895    fn formula_decode_limit_is_exact_for_v1_and_v2() {
1896        let exact = "x".repeat(32_768);
1897        let oversized = "x".repeat(32_769);
1898
1899        for buffer in [
1900            cells_to_raw_buffer(&[(
1901                1,
1902                vec![(
1903                    1,
1904                    CellValue::Formula {
1905                        expr: exact.clone(),
1906                        result: None,
1907                    },
1908                )],
1909            )])
1910            .unwrap(),
1911            v2_formula_buffer(&exact),
1912        ] {
1913            let decoded = raw_buffer_to_cells(&buffer).unwrap();
1914            assert_eq!(
1915                decoded[0].1[0].1,
1916                CellValue::Formula {
1917                    expr: exact.clone(),
1918                    result: None,
1919                }
1920            );
1921        }
1922
1923        for buffer in [
1924            cells_to_raw_buffer(&[(
1925                1,
1926                vec![(
1927                    1,
1928                    CellValue::Formula {
1929                        expr: oversized.clone(),
1930                        result: None,
1931                    },
1932                )],
1933            )])
1934            .unwrap(),
1935            v2_formula_buffer(&oversized),
1936        ] {
1937            assert_formula_input_limit(raw_buffer_to_cells(&buffer).unwrap_err(), 32_769);
1938        }
1939    }
1940
1941    #[test]
1942    fn formula_decode_cumulative_input_limit_is_exact_for_v1_and_v2() {
1943        let formula = "x".repeat(32_768);
1944        let exact_formulas = vec![formula.clone(); 128];
1945        let mut plus_one_formulas = exact_formulas.clone();
1946        plus_one_formulas.push("x".to_string());
1947        let v1_rows = |formulas: &[String]| {
1948            vec![(
1949                1,
1950                formulas
1951                    .iter()
1952                    .enumerate()
1953                    .map(|(col, formula)| {
1954                        (
1955                            col as u32 + 1,
1956                            CellValue::Formula {
1957                                expr: formula.clone(),
1958                                result: None,
1959                            },
1960                        )
1961                    })
1962                    .collect(),
1963            )]
1964        };
1965
1966        for buffer in [
1967            cells_to_raw_buffer(&v1_rows(&exact_formulas)).unwrap(),
1968            v2_formula_row(&exact_formulas),
1969        ] {
1970            let decoded = raw_buffer_to_cells(&buffer).unwrap();
1971            assert_eq!(decoded[0].1.len(), 128);
1972        }
1973
1974        for buffer in [
1975            cells_to_raw_buffer(&v1_rows(&plus_one_formulas)).unwrap(),
1976            v2_formula_row(&plus_one_formulas),
1977        ] {
1978            let Error::ResourceLimitExceeded(metadata) = raw_buffer_to_cells(&buffer).unwrap_err()
1979            else {
1980                panic!("expected a structured cumulative formula limit error");
1981            };
1982            assert_eq!(metadata.operation_code(), "formula_mutate");
1983            assert_eq!(metadata.dimension_code(), "input_bytes");
1984            assert_eq!(metadata.limit(), 4 * 1024 * 1024);
1985            assert_eq!(metadata.observed(), 4 * 1024 * 1024 + 1);
1986        }
1987    }
1988
1989    #[test]
1990    fn test_decode_date() {
1991        let serial = 44927.0; // 2023-01-01
1992        let rows = vec![(1, vec![(1, CellValue::Date(serial))])];
1993        let buf = cells_to_raw_buffer(&rows).unwrap();
1994        let result = raw_buffer_to_cells(&buf).unwrap();
1995        assert_eq!(result[0].1[0].1, CellValue::Date(serial));
1996    }
1997
1998    #[test]
1999    fn test_decode_mixed_row() {
2000        let rows = vec![(
2001            3,
2002            vec![
2003                (1, CellValue::Number(1.0)),
2004                (2, CellValue::String("text".to_string())),
2005                (3, CellValue::Bool(true)),
2006                (4, CellValue::Date(44927.0)),
2007                (5, CellValue::Error("#N/A".to_string())),
2008                (
2009                    6,
2010                    CellValue::Formula {
2011                        expr: "A3+B3".to_string(),
2012                        result: None,
2013                    },
2014                ),
2015            ],
2016        )];
2017        let buf = cells_to_raw_buffer(&rows).unwrap();
2018        let result = raw_buffer_to_cells(&buf).unwrap();
2019
2020        assert_eq!(result.len(), 1);
2021        assert_eq!(result[0].0, 3);
2022        let cells = &result[0].1;
2023        assert_eq!(cells.len(), 6);
2024        assert_eq!(cells[0], (1, CellValue::Number(1.0)));
2025        assert_eq!(cells[1], (2, CellValue::String("text".to_string())));
2026        assert_eq!(cells[2], (3, CellValue::Bool(true)));
2027        assert_eq!(cells[3], (4, CellValue::Date(44927.0)));
2028        assert_eq!(cells[4], (5, CellValue::Error("#N/A".to_string())));
2029        assert_eq!(
2030            cells[5],
2031            (
2032                6,
2033                CellValue::Formula {
2034                    expr: "A3+B3".to_string(),
2035                    result: None,
2036                }
2037            )
2038        );
2039    }
2040
2041    #[test]
2042    fn test_round_trip_cells_to_buffer() {
2043        let rows = vec![
2044            (
2045                1,
2046                vec![
2047                    (1, CellValue::String("Name".to_string())),
2048                    (2, CellValue::String("Age".to_string())),
2049                    (3, CellValue::String("Active".to_string())),
2050                ],
2051            ),
2052            (
2053                2,
2054                vec![
2055                    (1, CellValue::String("Alice".to_string())),
2056                    (2, CellValue::Number(30.0)),
2057                    (3, CellValue::Bool(true)),
2058                ],
2059            ),
2060            (
2061                3,
2062                vec![
2063                    (1, CellValue::String("Bob".to_string())),
2064                    (2, CellValue::Number(25.0)),
2065                    (3, CellValue::Bool(false)),
2066                ],
2067            ),
2068        ];
2069        let buf = cells_to_raw_buffer(&rows).unwrap();
2070        let result = raw_buffer_to_cells(&buf).unwrap();
2071        assert_eq!(result, rows);
2072    }
2073
2074    #[test]
2075    fn test_invalid_magic() {
2076        let mut buf = vec![0u8; 24];
2077        buf[0..4].copy_from_slice(&0xDEADBEEFu32.to_le_bytes());
2078        let err = raw_buffer_to_cells(&buf).unwrap_err();
2079        assert!(err.to_string().contains("invalid buffer magic"));
2080    }
2081
2082    #[test]
2083    fn rejects_unknown_versions_and_trailing_data() {
2084        let rows = vec![(1, vec![(1, CellValue::Number(1.0))])];
2085        let mut unknown_version = cells_to_raw_buffer(&rows).unwrap();
2086        unknown_version[4..6].copy_from_slice(&99u16.to_le_bytes());
2087        assert!(raw_buffer_to_cells(&unknown_version)
2088            .unwrap_err()
2089            .to_string()
2090            .contains("unsupported buffer version"));
2091
2092        let mut trailing = cells_to_raw_buffer(&rows).unwrap();
2093        trailing.push(0);
2094        assert!(raw_buffer_to_cells(&trailing)
2095            .unwrap_err()
2096            .to_string()
2097            .contains("trailing data"));
2098    }
2099
2100    #[test]
2101    fn rejects_truncated_and_inconsistent_sections() {
2102        let rows = vec![(1, vec![(1, CellValue::String("value".to_string()))])];
2103        let buf = cells_to_raw_buffer(&rows).unwrap();
2104        for length in 0..buf.len() {
2105            assert!(
2106                raw_buffer_to_cells(&buf[..length]).is_err(),
2107                "length {length}"
2108            );
2109        }
2110
2111        let mut descending_offsets = buf.clone();
2112        let string_table = HEADER_SIZE + ROW_INDEX_ENTRY_SIZE;
2113        descending_offsets[string_table..string_table + 4].copy_from_slice(&2u32.to_le_bytes());
2114        descending_offsets[string_table + 8..string_table + 12]
2115            .copy_from_slice(&4u32.to_le_bytes());
2116        descending_offsets[string_table + 12..string_table + 16]
2117            .copy_from_slice(&3u32.to_le_bytes());
2118        assert!(raw_buffer_to_cells(&descending_offsets).is_err());
2119
2120        let mut oversized_count = buf.clone();
2121        oversized_count[6..10].copy_from_slice(&u32::MAX.to_le_bytes());
2122        assert!(raw_buffer_to_cells(&oversized_count).is_err());
2123    }
2124
2125    #[test]
2126    fn v2_impossible_cell_count_is_rejected_before_reserve() {
2127        let mut buffer = Vec::new();
2128        buffer.extend_from_slice(&MAGIC_V2.to_le_bytes());
2129        buffer.extend_from_slice(&VERSION_V2.to_le_bytes());
2130        buffer.extend_from_slice(&1u32.to_le_bytes());
2131        buffer.extend_from_slice(&1u16.to_le_bytes());
2132        buffer.extend_from_slice(&0u32.to_le_bytes());
2133        buffer.extend_from_slice(&1u32.to_le_bytes());
2134        buffer.extend_from_slice(&0u32.to_le_bytes());
2135        buffer.extend_from_slice(&u16::MAX.to_le_bytes());
2136
2137        let error = raw_buffer_to_cells(&buffer).unwrap_err();
2138        assert!(error
2139            .to_string()
2140            .contains("v2 cell count exceeds the column span"));
2141    }
2142
2143    #[test]
2144    fn encoder_rejects_noncanonical_and_out_of_grid_coordinates() {
2145        for rows in [
2146            vec![(0, vec![(1, CellValue::Number(1.0))])],
2147            vec![(MAX_ROWS + 1, vec![(1, CellValue::Number(1.0))])],
2148            vec![(1, vec![(0, CellValue::Number(1.0))])],
2149            vec![(1, vec![(MAX_COLUMNS + 1, CellValue::Number(1.0))])],
2150            vec![(1, vec![(u32::MAX, CellValue::Number(1.0))])],
2151            vec![
2152                (2, vec![(1, CellValue::Number(1.0))]),
2153                (1, vec![(1, CellValue::Number(2.0))]),
2154            ],
2155            vec![
2156                (1, vec![(1, CellValue::Number(1.0))]),
2157                (1, vec![(2, CellValue::Number(2.0))]),
2158            ],
2159            vec![(
2160                1,
2161                vec![(2, CellValue::Number(1.0)), (1, CellValue::Number(2.0))],
2162            )],
2163            vec![(
2164                1,
2165                vec![(1, CellValue::Number(1.0)), (1, CellValue::Number(2.0))],
2166            )],
2167        ] {
2168            assert!(cells_to_raw_buffer(&rows).is_err());
2169        }
2170
2171        let boundary = vec![(MAX_ROWS, vec![(MAX_COLUMNS, CellValue::Number(1.0))])];
2172        assert_eq!(
2173            raw_buffer_to_cells(&cells_to_raw_buffer(&boundary).unwrap()).unwrap(),
2174            boundary
2175        );
2176    }
2177
2178    #[test]
2179    fn encoder_preserves_canonical_v1_wire_bytes() {
2180        let rows = vec![(1, vec![(1, CellValue::Number(42.0))])];
2181        let encoded = cells_to_raw_buffer(&rows).unwrap();
2182
2183        let mut expected = Vec::new();
2184        expected.extend_from_slice(&MAGIC.to_le_bytes());
2185        expected.extend_from_slice(&VERSION.to_le_bytes());
2186        expected.extend_from_slice(&1u32.to_le_bytes());
2187        expected.extend_from_slice(&1u16.to_le_bytes());
2188        expected.extend_from_slice(&0u32.to_le_bytes());
2189        expected.extend_from_slice(&1u32.to_le_bytes());
2190        expected.extend_from_slice(&0u32.to_le_bytes());
2191        expected.extend_from_slice(&0u32.to_le_bytes());
2192        expected.extend_from_slice(&0u32.to_le_bytes());
2193        expected.push(TYPE_NUMBER);
2194        expected.extend_from_slice(&42.0f64.to_le_bytes());
2195
2196        assert_eq!(encoded, expected);
2197    }
2198
2199    #[test]
2200    fn encoder_size_preflight_rejects_huge_dense_output() {
2201        let error = compute_dense_size(
2202            MAX_ROWS,
2203            u16::try_from(MAX_COLUMNS).unwrap(),
2204            TraversalLimits::default(),
2205        )
2206        .unwrap_err();
2207        let Error::ResourceLimitExceeded(metadata) = error else {
2208            panic!("expected a structured output limit error");
2209        };
2210        assert_eq!(metadata.dimension_code(), "output_bytes");
2211    }
2212
2213    #[test]
2214    fn decoder_rejects_noncanonical_row_and_column_order() {
2215        let rows = vec![
2216            (
2217                1,
2218                vec![(1, CellValue::Number(1.0)), (100, CellValue::Number(2.0))],
2219            ),
2220            (2, vec![(1, CellValue::Number(3.0))]),
2221        ];
2222        let v1 = cells_to_raw_buffer(&rows).unwrap();
2223
2224        let mut duplicate_row = v1.clone();
2225        duplicate_row[HEADER_SIZE + ROW_INDEX_ENTRY_SIZE..HEADER_SIZE + ROW_INDEX_ENTRY_SIZE + 4]
2226            .copy_from_slice(&1u32.to_le_bytes());
2227        assert!(raw_buffer_to_cells(&duplicate_row)
2228            .unwrap_err()
2229            .to_string()
2230            .contains("row numbers must be strictly increasing"));
2231
2232        let mut duplicate_v1_column = v1;
2233        let cell_data = HEADER_SIZE + 2 * ROW_INDEX_ENTRY_SIZE + 8;
2234        let first_col = duplicate_v1_column[cell_data + 2..cell_data + 4].to_vec();
2235        duplicate_v1_column[cell_data + 2 + SPARSE_ENTRY_SIZE..cell_data + 4 + SPARSE_ENTRY_SIZE]
2236            .copy_from_slice(&first_col);
2237        assert!(raw_buffer_to_cells(&duplicate_v1_column)
2238            .unwrap_err()
2239            .to_string()
2240            .contains("sparse cell columns must be strictly increasing"));
2241
2242        let mut duplicate_v2_column = Vec::new();
2243        duplicate_v2_column.extend_from_slice(&MAGIC_V2.to_le_bytes());
2244        duplicate_v2_column.extend_from_slice(&VERSION_V2.to_le_bytes());
2245        duplicate_v2_column.extend_from_slice(&1u32.to_le_bytes());
2246        duplicate_v2_column.extend_from_slice(&2u16.to_le_bytes());
2247        duplicate_v2_column.extend_from_slice(&0u32.to_le_bytes());
2248        duplicate_v2_column.extend_from_slice(&1u32.to_le_bytes());
2249        duplicate_v2_column.extend_from_slice(&0u32.to_le_bytes());
2250        duplicate_v2_column.extend_from_slice(&2u16.to_le_bytes());
2251        duplicate_v2_column.extend_from_slice(&0u16.to_le_bytes());
2252        duplicate_v2_column.push(TYPE_EMPTY);
2253        duplicate_v2_column.extend_from_slice(&0u16.to_le_bytes());
2254        duplicate_v2_column.push(TYPE_EMPTY);
2255        assert!(raw_buffer_to_cells(&duplicate_v2_column)
2256            .unwrap_err()
2257            .to_string()
2258            .contains("v2 cell columns must be strictly increasing"));
2259    }
2260
2261    #[test]
2262    fn decodes_v1_min_col_and_v2_coordinates() {
2263        let rows = vec![(1, vec![(1, CellValue::String("v1".to_string()))])];
2264        let mut v1 = cells_to_raw_buffer(&rows).unwrap();
2265        let flags =
2266            (3u32 << 16) | (u32::from_le_bytes(v1[12..16].try_into().unwrap()) & FLAG_SPARSE);
2267        v1[12..16].copy_from_slice(&flags.to_le_bytes());
2268        assert_eq!(
2269            raw_buffer_to_cells(&v1).unwrap(),
2270            vec![(1, vec![(3, CellValue::String("v1".to_string()))])]
2271        );
2272
2273        let mut v2 = Vec::new();
2274        v2.extend_from_slice(&crate::raw_transfer_v2::MAGIC_V2.to_le_bytes());
2275        v2.extend_from_slice(&crate::raw_transfer_v2::VERSION_V2.to_le_bytes());
2276        v2.extend_from_slice(&1u32.to_le_bytes());
2277        v2.extend_from_slice(&1u16.to_le_bytes());
2278        v2.extend_from_slice(&(3u32 << 16).to_le_bytes());
2279        v2.extend_from_slice(&1u32.to_le_bytes());
2280        v2.extend_from_slice(&0u32.to_le_bytes());
2281        v2.extend_from_slice(&1u16.to_le_bytes());
2282        v2.extend_from_slice(&0u16.to_le_bytes());
2283        v2.push(TYPE_NUMBER);
2284        v2.extend_from_slice(&42.0f64.to_le_bytes());
2285        assert_eq!(
2286            raw_buffer_to_cells(&v2).unwrap(),
2287            vec![(1, vec![(3, CellValue::Number(42.0))])],
2288        );
2289    }
2290
2291    #[test]
2292    fn test_buffer_too_short() {
2293        let buf = vec![0u8; 4];
2294        let err = raw_buffer_to_cells(&buf).unwrap_err();
2295        assert!(err.to_string().contains("buffer too short"));
2296    }
2297
2298    #[test]
2299    fn test_rich_string_degrades_to_string() {
2300        let runs = vec![
2301            RichTextRun {
2302                text: "bold ".to_string(),
2303                font: None,
2304                size: None,
2305                bold: true,
2306                italic: false,
2307                color: None,
2308            },
2309            RichTextRun {
2310                text: "text".to_string(),
2311                font: None,
2312                size: None,
2313                bold: false,
2314                italic: false,
2315                color: None,
2316            },
2317        ];
2318        let rows = vec![(1, vec![(1, CellValue::RichString(runs))])];
2319        let buf = cells_to_raw_buffer(&rows).unwrap();
2320        let result = raw_buffer_to_cells(&buf).unwrap();
2321        assert_eq!(result[0].1[0].1, CellValue::String("bold text".to_string()));
2322    }
2323
2324    #[test]
2325    fn test_multiple_rows_and_columns() {
2326        let rows = vec![
2327            (
2328                1,
2329                vec![(1, CellValue::Number(1.0)), (5, CellValue::Number(5.0))],
2330            ),
2331            (10, vec![(3, CellValue::String("mid".to_string()))]),
2332            (
2333                100,
2334                vec![(1, CellValue::Bool(true)), (5, CellValue::Date(45000.0))],
2335            ),
2336        ];
2337        let buf = cells_to_raw_buffer(&rows).unwrap();
2338        let result = raw_buffer_to_cells(&buf).unwrap();
2339        assert_eq!(result.len(), 3);
2340        assert_eq!(result[0].0, 1);
2341        assert_eq!(result[1].0, 10);
2342        assert_eq!(result[2].0, 100);
2343        assert_eq!(result[0].1.len(), 2);
2344        assert_eq!(result[0].1[0], (1, CellValue::Number(1.0)));
2345        assert_eq!(result[0].1[1], (5, CellValue::Number(5.0)));
2346        assert_eq!(result[1].1[0], (3, CellValue::String("mid".to_string())));
2347        assert_eq!(result[2].1[0], (1, CellValue::Bool(true)));
2348        assert_eq!(result[2].1[1], (5, CellValue::Date(45000.0)));
2349    }
2350
2351    #[test]
2352    fn test_sparse_format_selected_for_sparse_data() {
2353        // 10 rows with 1 cell each, but col ranges up to 100 -> density = 10/(10*100) = 1%
2354        let mut rows = Vec::new();
2355        for i in 1..=10 {
2356            rows.push((i, vec![(100, CellValue::Number(i as f64))]));
2357        }
2358        let buf = cells_to_raw_buffer(&rows).unwrap();
2359        let header = read_header(&buf).unwrap();
2360        assert_ne!(header.flags & FLAG_SPARSE, 0, "sparse flag should be set");
2361
2362        let result = raw_buffer_to_cells(&buf).unwrap();
2363        assert_eq!(result.len(), 10);
2364        for (i, (row_num, cells)) in result.iter().enumerate() {
2365            assert_eq!(*row_num, i as u32 + 1);
2366            assert_eq!(cells[0], (100, CellValue::Number((i + 1) as f64)));
2367        }
2368    }
2369
2370    #[test]
2371    fn test_dense_format_selected_for_dense_data() {
2372        let mut rows = Vec::new();
2373        for r in 1..=5 {
2374            let cells: Vec<(u32, CellValue)> = (1..=5)
2375                .map(|c| (c, CellValue::Number((r * 10 + c) as f64)))
2376                .collect();
2377            rows.push((r, cells));
2378        }
2379        let buf = cells_to_raw_buffer(&rows).unwrap();
2380        let header = read_header(&buf).unwrap();
2381        assert_eq!(
2382            header.flags & FLAG_SPARSE,
2383            0,
2384            "sparse flag should not be set"
2385        );
2386
2387        let result = raw_buffer_to_cells(&buf).unwrap();
2388        assert_eq!(result.len(), 5);
2389        for r in 0..5 {
2390            assert_eq!(result[r].0, (r + 1) as u32);
2391            assert_eq!(result[r].1.len(), 5);
2392            for c in 0..5 {
2393                let expected = ((r + 1) * 10 + (c + 1)) as f64;
2394                assert_eq!(
2395                    result[r].1[c],
2396                    ((c + 1) as u32, CellValue::Number(expected))
2397                );
2398            }
2399        }
2400    }
2401
2402    #[test]
2403    fn test_string_deduplication() {
2404        let rows = vec![(
2405            1,
2406            vec![
2407                (1, CellValue::String("repeated".to_string())),
2408                (2, CellValue::String("repeated".to_string())),
2409                (3, CellValue::String("unique".to_string())),
2410            ],
2411        )];
2412        let buf = cells_to_raw_buffer(&rows).unwrap();
2413        let header = read_header(&buf).unwrap();
2414        let st_offset = HEADER_SIZE + header.row_count as usize * ROW_INDEX_ENTRY_SIZE;
2415        let count = u32::from_le_bytes(buf[st_offset..st_offset + 4].try_into().unwrap());
2416        assert_eq!(count, 2, "string table should have 2 unique strings, not 3");
2417
2418        let result = raw_buffer_to_cells(&buf).unwrap();
2419        assert_eq!(result[0].1[0].1, CellValue::String("repeated".to_string()));
2420        assert_eq!(result[0].1[1].1, CellValue::String("repeated".to_string()));
2421        assert_eq!(result[0].1[2].1, CellValue::String("unique".to_string()));
2422    }
2423
2424    #[test]
2425    fn string_table_budget_accounts_for_unique_strings_only() {
2426        let limits = TraversalLimits::new(1, 1, 1, 34).unwrap();
2427        let mut table = StringTable::new(16, limits).unwrap();
2428
2429        let first = table.intern("repeat").unwrap();
2430        for _ in 0..100 {
2431            assert_eq!(table.intern("repeat").unwrap(), first);
2432        }
2433        let error = table.intern("unique").unwrap_err();
2434        let Error::ResourceLimitExceeded(metadata) = error else {
2435            panic!("expected a structured output limit error");
2436        };
2437        assert_eq!(metadata.dimension_code(), "output_bytes");
2438    }
2439
2440    #[test]
2441    fn decoded_string_copies_obey_a_cumulative_budget() {
2442        let limits = TraversalLimits::new(1, 1, 1, 5).unwrap();
2443        let mut budget = DecodeBudget::new(limits);
2444
2445        assert_eq!(budget.copy("abc").unwrap(), "abc");
2446        let error = budget.copy("def").unwrap_err();
2447        let Error::ResourceLimitExceeded(metadata) = error else {
2448            panic!("expected a structured output limit error");
2449        };
2450        assert_eq!(metadata.dimension_code(), "output_bytes");
2451        assert_eq!(budget.output_bytes, 3);
2452    }
2453
2454    #[test]
2455    fn decoder_accounts_for_all_collections_and_string_copies_cumulatively() {
2456        let encoded =
2457            cells_to_raw_buffer(&[(1, vec![(1, CellValue::String("abc".to_string()))])]).unwrap();
2458        let exact_output_bytes = u64::try_from(
2459            std::mem::size_of::<(u32, u32)>()
2460                + std::mem::size_of::<usize>()
2461                + std::mem::size_of::<&str>()
2462                + std::mem::size_of::<CellRow>()
2463                + std::mem::size_of::<(u32, CellValue)>()
2464                + "abc".len(),
2465        )
2466        .unwrap();
2467
2468        let exact_limits = TraversalLimits::new(1, 1, 1, exact_output_bytes).unwrap();
2469        assert_eq!(
2470            raw_buffer_to_cells_with_limits(&encoded, exact_limits).unwrap(),
2471            vec![(1, vec![(1, CellValue::String("abc".to_string()))])]
2472        );
2473
2474        let plus_one_limits = TraversalLimits::new(1, 1, 1, exact_output_bytes - 1).unwrap();
2475        let Error::ResourceLimitExceeded(metadata) =
2476            raw_buffer_to_cells_with_limits(&encoded, plus_one_limits).unwrap_err()
2477        else {
2478            panic!("expected a structured cumulative output limit error");
2479        };
2480        assert_eq!(metadata.dimension_code(), "output_bytes");
2481        assert_eq!(metadata.observed(), exact_output_bytes);
2482    }
2483
2484    #[test]
2485    fn validated_transfer_shares_decode_and_destination_output_budget() {
2486        let encoded =
2487            cells_to_raw_buffer(&[(1, vec![(1, CellValue::String("abc".to_string()))])]).unwrap();
2488        let exact_output_bytes = u64::try_from(
2489            std::mem::size_of::<(u32, u32)>()
2490                + std::mem::size_of::<usize>()
2491                + std::mem::size_of::<&str>()
2492                + std::mem::size_of::<CellRow>()
2493                + std::mem::size_of::<(u32, CellValue)>()
2494                + "abc".len()
2495                + std::mem::size_of::<(String, CellValue)>()
2496                + 2,
2497        )
2498        .unwrap();
2499
2500        let exact_limits = TraversalLimits::new(1, 1, 1, exact_output_bytes).unwrap();
2501        let transfer =
2502            raw_buffer_to_validated_cell_transfer_with_limits(&encoded, 1, 1, exact_limits)
2503                .unwrap();
2504        assert_eq!(
2505            transfer.entries,
2506            vec![("A1".to_string(), CellValue::String("abc".to_string()))]
2507        );
2508
2509        let plus_one_limits = TraversalLimits::new(1, 1, 1, exact_output_bytes - 1).unwrap();
2510        let error = match raw_buffer_to_validated_cell_transfer_with_limits(
2511            &encoded,
2512            1,
2513            1,
2514            plus_one_limits,
2515        ) {
2516            Ok(_) => panic!("expected a structured cumulative output limit error"),
2517            Err(error) => error,
2518        };
2519        let Error::ResourceLimitExceeded(metadata) = error else {
2520            panic!("expected a structured cumulative output limit error");
2521        };
2522        assert_eq!(metadata.dimension_code(), "output_bytes");
2523        assert_eq!(metadata.observed(), exact_output_bytes);
2524    }
2525
2526    #[test]
2527    fn decoded_cells_obey_a_cumulative_budget() {
2528        let limits = TraversalLimits::new(1, 1, 2, 1).unwrap();
2529        let mut budget = DecodeBudget::new(limits);
2530
2531        budget.charge_cells(2).unwrap();
2532        let error = budget.charge_cells(1).unwrap_err();
2533        let Error::ResourceLimitExceeded(metadata) = error else {
2534            panic!("expected a structured cell limit error");
2535        };
2536        assert_eq!(metadata.dimension_code(), "cell_count");
2537        assert_eq!(budget.cells, 2);
2538    }
2539
2540    #[test]
2541    fn decoder_rejects_invalid_column_spans_before_sections() {
2542        for magic in [MAGIC, MAGIC_V2] {
2543            let mut buffer = vec![0u8; HEADER_SIZE];
2544            buffer[0..4].copy_from_slice(&magic.to_le_bytes());
2545            buffer[4..6].copy_from_slice(
2546                &(if magic == MAGIC { VERSION } else { VERSION_V2 }).to_le_bytes(),
2547            );
2548            buffer[6..10].copy_from_slice(&1u32.to_le_bytes());
2549            buffer[10..12].copy_from_slice(&2u16.to_le_bytes());
2550            buffer[12..16].copy_from_slice(&(MAX_COLUMNS << 16).to_le_bytes());
2551
2552            assert!(raw_buffer_to_cells(&buffer)
2553                .unwrap_err()
2554                .to_string()
2555                .contains("cell column span is out of range"));
2556        }
2557    }
2558
2559    #[test]
2560    fn decoder_preflights_dense_and_sparse_cell_counts_before_materialization() {
2561        let mut dense = vec![0u8; HEADER_SIZE];
2562        dense[0..4].copy_from_slice(&MAGIC.to_le_bytes());
2563        dense[4..6].copy_from_slice(&VERSION.to_le_bytes());
2564        dense[6..10].copy_from_slice(&611u32.to_le_bytes());
2565        dense[10..12].copy_from_slice(&(MAX_COLUMNS as u16).to_le_bytes());
2566        let Error::ResourceLimitExceeded(metadata) = raw_buffer_to_cells(&dense).unwrap_err()
2567        else {
2568            panic!("expected a structured dense cell limit error");
2569        };
2570        assert_eq!(metadata.dimension_code(), "cell_count");
2571
2572        let mut sparse = vec![0u8; 2 + 3 * SPARSE_ENTRY_SIZE];
2573        sparse[0..2].copy_from_slice(&3u16.to_le_bytes());
2574        let limits = TraversalLimits::new(1, 3, 2, 1).unwrap();
2575        let error = preflight_sparse_cell_count(&sparse, 0, &[(1, 0)], limits).unwrap_err();
2576        let Error::ResourceLimitExceeded(metadata) = error else {
2577            panic!("expected a structured sparse cell limit error");
2578        };
2579        assert_eq!(metadata.dimension_code(), "cell_count");
2580    }
2581
2582    #[test]
2583    fn v2_sparse_layout_is_not_charged_as_a_dense_grid() {
2584        let row_count = 611u32;
2585        let mut buffer = Vec::new();
2586        buffer.extend_from_slice(&MAGIC_V2.to_le_bytes());
2587        buffer.extend_from_slice(&VERSION_V2.to_le_bytes());
2588        buffer.extend_from_slice(&row_count.to_le_bytes());
2589        buffer.extend_from_slice(&(MAX_COLUMNS as u16).to_le_bytes());
2590        buffer.extend_from_slice(&0u32.to_le_bytes());
2591        for row in 1..=row_count {
2592            buffer.extend_from_slice(&row.to_le_bytes());
2593            buffer.extend_from_slice(&((row - 1) * 13).to_le_bytes());
2594        }
2595        for _ in 0..row_count {
2596            buffer.extend_from_slice(&1u16.to_le_bytes());
2597            buffer.extend_from_slice(&0u16.to_le_bytes());
2598            buffer.push(TYPE_NUMBER);
2599            buffer.extend_from_slice(&1.0f64.to_le_bytes());
2600        }
2601
2602        let rows = raw_buffer_to_cells(&buffer).unwrap();
2603        assert_eq!(rows.len(), row_count as usize);
2604        assert_eq!(rows.last().unwrap().0, row_count);
2605    }
2606
2607    #[test]
2608    fn rich_text_admission_preserves_deduplication() {
2609        let limits = TraversalLimits::new(1, 1, 1, 34).unwrap();
2610        let mut table = StringTable::new(16, limits).unwrap();
2611        let expected = table.intern("repeat").unwrap();
2612        let runs = vec![
2613            RichTextRun {
2614                text: "re".to_string(),
2615                font: None,
2616                size: None,
2617                bold: false,
2618                italic: false,
2619                color: None,
2620            },
2621            RichTextRun {
2622                text: "peat".to_string(),
2623                font: None,
2624                size: None,
2625                bold: true,
2626                italic: false,
2627                color: None,
2628            },
2629        ];
2630
2631        let payload = encode_cell_payload(&CellValue::RichString(runs), &mut table).unwrap();
2632        assert_eq!(
2633            u32::from_le_bytes(payload[0..4].try_into().unwrap()),
2634            expected
2635        );
2636        assert_eq!(table.strings.len(), 1);
2637    }
2638
2639    #[test]
2640    fn test_header_fields() {
2641        let rows = vec![
2642            (
2643                1,
2644                vec![(1, CellValue::Number(1.0)), (3, CellValue::Number(3.0))],
2645            ),
2646            (2, vec![(2, CellValue::Number(2.0))]),
2647        ];
2648        let buf = cells_to_raw_buffer(&rows).unwrap();
2649        let header = read_header(&buf).unwrap();
2650        assert_eq!(header._version, VERSION);
2651        assert_eq!(header.row_count, 2);
2652        assert_eq!(header.col_count, 3);
2653    }
2654
2655    #[test]
2656    fn test_formula_result_not_preserved() {
2657        let rows = vec![(
2658            1,
2659            vec![(
2660                1,
2661                CellValue::Formula {
2662                    expr: "1+1".to_string(),
2663                    result: Some(Box::new(CellValue::Number(2.0))),
2664                },
2665            )],
2666        )];
2667        let buf = cells_to_raw_buffer(&rows).unwrap();
2668        let result = raw_buffer_to_cells(&buf).unwrap();
2669        assert_eq!(
2670            result[0].1[0].1,
2671            CellValue::Formula {
2672                expr: "1+1".to_string(),
2673                result: None,
2674            }
2675        );
2676    }
2677
2678    #[test]
2679    fn test_hand_constructed_dense_buffer() {
2680        // Manually construct a buffer with 1 row, 2 cols, dense, 1 number + 1 bool
2681        let row_count: u32 = 1;
2682        let col_count: u16 = 2;
2683
2684        let st_size = 8; // count(4) + blob_size(4) + 0 offsets + 0 blob
2685        let cell_data_size = 2 * CELL_STRIDE; // 2 cols * 9 bytes
2686        let total = HEADER_SIZE + ROW_INDEX_ENTRY_SIZE + st_size + cell_data_size;
2687
2688        let mut buf = vec![0u8; total];
2689        // Header
2690        buf[0..4].copy_from_slice(&MAGIC.to_le_bytes());
2691        buf[4..6].copy_from_slice(&1u16.to_le_bytes()); // version
2692        buf[6..10].copy_from_slice(&row_count.to_le_bytes());
2693        buf[10..12].copy_from_slice(&col_count.to_le_bytes());
2694        buf[12..16].copy_from_slice(&0u32.to_le_bytes()); // flags (dense)
2695
2696        // Row index: row 1 at offset 0
2697        let ri_start = HEADER_SIZE;
2698        buf[ri_start..ri_start + 4].copy_from_slice(&1u32.to_le_bytes());
2699        buf[ri_start + 4..ri_start + 8].copy_from_slice(&0u32.to_le_bytes());
2700
2701        // String table: count=0, blob_size=0
2702        let st_start = ri_start + ROW_INDEX_ENTRY_SIZE;
2703        buf[st_start..st_start + 4].copy_from_slice(&0u32.to_le_bytes());
2704        buf[st_start + 4..st_start + 8].copy_from_slice(&0u32.to_le_bytes());
2705
2706        // Cell data
2707        let cd_start = st_start + st_size;
2708        // Col 0: Number 99.0
2709        buf[cd_start] = TYPE_NUMBER;
2710        buf[cd_start + 1..cd_start + 9].copy_from_slice(&99.0f64.to_le_bytes());
2711        // Col 1: Bool true
2712        buf[cd_start + CELL_STRIDE] = TYPE_BOOL;
2713        buf[cd_start + CELL_STRIDE + 1] = 1;
2714
2715        let result = raw_buffer_to_cells(&buf).unwrap();
2716        assert_eq!(result.len(), 1);
2717        assert_eq!(result[0].0, 1);
2718        assert_eq!(result[0].1[0], (1, CellValue::Number(99.0)));
2719        assert_eq!(result[0].1[1], (2, CellValue::Bool(true)));
2720    }
2721
2722    #[test]
2723    fn test_hand_constructed_sparse_buffer() {
2724        // Manually construct a sparse buffer: 1 row, col_count=100, 1 cell at col 50
2725        let row_count: u32 = 1;
2726        let col_count: u16 = 100;
2727
2728        let st_size = 8; // count=0, blob_size=0
2729        let cell_data_size = 2 + SPARSE_ENTRY_SIZE; // cell_count(2) + 1 entry(11)
2730        let total = HEADER_SIZE + ROW_INDEX_ENTRY_SIZE + st_size + cell_data_size;
2731
2732        let mut buf = vec![0u8; total];
2733        // Header
2734        buf[0..4].copy_from_slice(&MAGIC.to_le_bytes());
2735        buf[4..6].copy_from_slice(&1u16.to_le_bytes());
2736        buf[6..10].copy_from_slice(&row_count.to_le_bytes());
2737        buf[10..12].copy_from_slice(&col_count.to_le_bytes());
2738        buf[12..16].copy_from_slice(&FLAG_SPARSE.to_le_bytes());
2739
2740        // Row index
2741        let ri_start = HEADER_SIZE;
2742        buf[ri_start..ri_start + 4].copy_from_slice(&5u32.to_le_bytes()); // row 5
2743        buf[ri_start + 4..ri_start + 8].copy_from_slice(&0u32.to_le_bytes()); // offset 0
2744
2745        // String table
2746        let st_start = ri_start + ROW_INDEX_ENTRY_SIZE;
2747        buf[st_start..st_start + 4].copy_from_slice(&0u32.to_le_bytes());
2748        buf[st_start + 4..st_start + 8].copy_from_slice(&0u32.to_le_bytes());
2749
2750        // Sparse cell data
2751        let cd_start = st_start + st_size;
2752        buf[cd_start..cd_start + 2].copy_from_slice(&1u16.to_le_bytes()); // 1 cell
2753        let entry = cd_start + 2;
2754        buf[entry..entry + 2].copy_from_slice(&49u16.to_le_bytes()); // col index 49 (0-based)
2755        buf[entry + 2] = TYPE_NUMBER;
2756        buf[entry + 3..entry + 11].copy_from_slice(&7.77f64.to_le_bytes());
2757
2758        let result = raw_buffer_to_cells(&buf).unwrap();
2759        assert_eq!(result.len(), 1);
2760        assert_eq!(result[0].0, 5);
2761        assert_eq!(result[0].1[0], (50, CellValue::Number(7.77))); // 1-based col 50
2762    }
2763}