Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(storage): make selective V2 decoding cancellable

buger24826b7bcdfe
diff --git a/engine/crates/xerj-storage/src/stored_codec.rs b/engine/crates/xerj-storage/src/stored_codec.rs
index 2a83616bb..ec3b6a331 100644
--- a/engine/crates/xerj-storage/src/stored_codec.rs
+++ b/engine/crates/xerj-storage/src/stored_codec.rs
@@ -59,10 +59,49 @@ use std::io::{Cursor, Write};
mod row_hydration;
pub use row_hydration::{
- decode_stored_v2_rows, StoredV2HydratedRow, StoredV2RowHydrationResult,
- StoredV2RowHydrationStats,
+ decode_stored_v2_rows, decode_stored_v2_rows_controlled, StoredV2HydratedRow,
+ StoredV2RowHydrationResult, StoredV2RowHydrationStats,
};
+pub const STORED_DECODE_CHECK_INTERVAL: usize = 128;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum StoredDecodePhase {
+ BeforeColumn,
+ Rows,
+ AfterColumn,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct StoredDecodeCheckpoint {
+ pub phase: StoredDecodePhase,
+ pub column_index: usize,
+ pub rows_processed: usize,
+}
+
+#[derive(Debug, PartialEq)]
+pub enum StoredDecodeRun<T> {
+ Complete(T),
+ Cancelled,
+}
+
+pub(crate) fn decode_cancelled<F>(
+ checkpoint: &mut F,
+ phase: StoredDecodePhase,
+ column_index: usize,
+ rows_processed: usize,
+) -> bool
+where
+ F: FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()> + ?Sized,
+{
+ checkpoint(StoredDecodeCheckpoint {
+ phase,
+ column_index,
+ rows_processed,
+ })
+ .is_break()
+}
+
// ── V1: flat LZ4 over JSON (legacy) ───────────────────────────────────────
/// Magic prefix for LZ4-compressed stored sections (v1, pre-columnar).
@@ -541,6 +580,756 @@ pub fn decode_stored(bytes: &[u8]) -> Result<Vec<u8>> {
Ok(bytes.to_vec())
}
+/// Values decoded from a requested subset of a ZBS2 stored section.
+///
+/// Column names use their on-disk names: `_id` and `_seq_no` are `__id` and
+/// `__seq_no`; source fields retain their original top-level names.
+#[derive(Debug, PartialEq)]
+pub struct StoredV2Projection {
+ pub num_docs: usize,
+ pub columns: HashMap<String, Vec<serde_json::Value>>,
+}
+
+/// Result of attempting a selective V2 decode.
+#[derive(Debug, PartialEq)]
+pub enum StoredV2ProjectionResult {
+ /// The section is a valid legacy/non-V2 shape. Callers may use the full
+ /// compatibility decoder.
+ NotV2,
+ /// The requested columns were decoded. Requested names absent from the
+ /// segment are absent from `columns`.
+ Projected(StoredV2Projection),
+}
+
+struct V2ColumnRef<'a> {
+ name: &'a str,
+ codec: ColCodec,
+ payload: &'a [u8],
+}
+
+struct V2Directory<'a> {
+ num_docs: usize,
+ columns: Vec<V2ColumnRef<'a>>,
+}
+
+/// Typed columns needed by an exact kNN scan.
+pub type StoredVectorRows = Vec<Option<Vec<f32>>>;
+pub type StoredVectorChunkRows = Vec<Option<Vec<Vec<f32>>>>;
+
+#[derive(Debug, PartialEq)]
+pub struct StoredV2KnnProjection {
+ pub num_docs: usize,
+ /// Invalid or missing identity cells are represented as `None`; the
+ /// engine's version/tombstone rules decide whether to skip those rows.
+ pub ids: Vec<Option<String>>,
+ pub seq_nos: Vec<Option<u64>>,
+ pub vectors: StoredVectorRows,
+ /// `None` means the optional chunks role was not requested or its named
+ /// column is absent. It is not a corruption signal.
+ pub vector_chunks: Option<StoredVectorChunkRows>,
+}
+
+/// Result of attempting the typed kNN projection.
+#[derive(Debug, PartialEq)]
+pub enum StoredV2KnnProjectionResult {
+ /// Legacy LZ4 or headerless JSON. The caller must use the compatibility
+ /// decoder.
+ NotV2,
+ /// A valid V2 section does not contain the requested vector column.
+ MissingVectorColumn,
+ /// The requested column exists but is not a finite numeric vector shape.
+ /// Callers may preserve compatibility by using the generic decoder.
+ UnsupportedVectorShape,
+ Projected(StoredV2KnnProjection),
+}
+
+/// Parse and validate the complete ZBS2 directory without decoding payloads.
+///
+/// Keeping framing validation separate from payload decoding allows callers
+/// to skip large unrelated columns while retaining the full decoder's
+/// truncation, UTF-8 and codec-id checks.
+fn parse_v2_directory(body: &[u8]) -> Result<V2Directory<'_>> {
+ let mut cur = Cursor::new(body);
+ let num_docs = cur
+ .read_u32::<LittleEndian>()
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 num_docs: {e}")))?
+ as usize;
+ let num_cols = cur
+ .read_u32::<LittleEndian>()
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 num_cols: {e}")))?
+ as usize;
+ let mut columns = Vec::with_capacity(num_cols);
+ let mut seen = std::collections::HashSet::with_capacity(num_cols);
+ for _ in 0..num_cols {
+ let name_len = cur
+ .read_u16::<LittleEndian>()
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 name_len: {e}")))?
+ as usize;
+ let name_start = cur.position() as usize;
+ let name_end = name_start
+ .checked_add(name_len)
+ .filter(|end| *end <= body.len())
+ .ok_or_else(|| StorageError::Other(anyhow::anyhow!("v2 truncated name")))?;
+ let name = std::str::from_utf8(&body[name_start..name_end])
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 bad name utf8: {e}")))?;
+ if !seen.insert(name) {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "v2 duplicate column name: {name}"
+ )));
+ }
+ cur.set_position(name_end as u64);
+ let codec_id = cur
+ .read_u8()
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 codec_id: {e}")))?;
+ let codec = ColCodec::from_u8(codec_id)
+ .ok_or_else(|| StorageError::Other(anyhow::anyhow!("v2 unknown codec {codec_id}")))?;
+ let payload_len = cur
+ .read_u32::<LittleEndian>()
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("v2 payload_len: {e}")))?
+ as usize;
+ let payload_start = cur.position() as usize;
+ let payload_end = payload_start
+ .checked_add(payload_len)
+ .filter(|end| *end <= body.len())
+ .ok_or_else(|| StorageError::Other(anyhow::anyhow!("v2 truncated payload")))?;
+ columns.push(V2ColumnRef {
+ name,
+ codec,
+ payload: &body[payload_start..payload_end],
+ });
+ cur.set_position(payload_end as u64);
+ }
+ if cur.position() as usize != body.len() {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "v2 trailing bytes after column payloads"
+ )));
+ }
+ Ok(V2Directory { num_docs, columns })
+}
+
+/// Decode only named columns from a V2 stored section.
+///
+/// This API does not change `decode_stored` or any engine behavior. It is the
+/// storage primitive for consumers that can operate on selected columns
+/// without reconstructing every `_source` object.
+pub fn decode_stored_v2_projection(
+ bytes: &[u8],
+ requested: &[&str],
+) -> Result<StoredV2ProjectionResult> {
+ if bytes.len() < 4 || &bytes[..4] != STORED_V2_MAGIC {
+ return Ok(StoredV2ProjectionResult::NotV2);
+ }
+ let directory = parse_v2_directory(&bytes[4..])?;
+ let requested: std::collections::HashSet<&str> = requested.iter().copied().collect();
+ let mut decoded = vec![None; directory.columns.len()];
+ let mut visiting = vec![false; directory.columns.len()];
+ let mut columns = HashMap::with_capacity(requested.len());
+ for index in 0..directory.columns.len() {
+ let column = &directory.columns[index];
+ if requested.contains(column.name) {
+ let values =
+ decode_projected_column(index, &directory, &mut decoded, &mut visiting, 0)?.clone();
+ columns.insert(column.name.to_string(), values);
+ }
+ }
+ Ok(StoredV2ProjectionResult::Projected(StoredV2Projection {
+ num_docs: directory.num_docs,
+ columns,
+ }))
+}
+
+fn decode_cross_dep_body(payload: &[u8]) -> Result<Vec<u8>> {
+ if payload.is_empty() {
+ return Err(StorageError::Other(anyhow::anyhow!("cross_dep empty")));
+ }
+ let body = if payload[0] == 1 {
+ zstd::decode_all(&payload[1..])
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("cross_dep zstd decode: {e}")))?
+ } else if payload[0] == 0 {
+ payload[1..].to_vec()
+ } else {
+ Err(StorageError::Other(anyhow::anyhow!(
+ "cross_dep invalid compression flag {}",
+ payload[0]
+ )))?
+ };
+ Ok(body)
+}
+
+fn cross_dep_source_index(payload: &[u8]) -> Result<usize> {
+ let body = decode_cross_dep_body(payload)?;
+ Cursor::new(body)
+ .read_u32::<LittleEndian>()
+ .map(|value| value as usize)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("cross_dep src_ix: {e}")))
+}
+
+fn decode_projected_column<'a>(
+ index: usize,
+ directory: &'a V2Directory<'a>,
+ decoded: &'a mut [Option<Vec<serde_json::Value>>],
+ visiting: &mut [bool],
+ depth: usize,
+) -> Result<&'a Vec<serde_json::Value>> {
+ const MAX_CROSS_DEP_DEPTH: usize = 256;
+ if depth > MAX_CROSS_DEP_DEPTH {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "cross_dep dependency depth exceeds {MAX_CROSS_DEP_DEPTH}"
+ )));
+ }
+ if decoded.get(index).and_then(Option::as_ref).is_some() {
+ return Ok(decoded[index].as_ref().unwrap());
+ }
+ if index >= directory.columns.len() || index >= visiting.len() {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "cross_dep source index {index} out of range"
+ )));
+ }
+ if visiting[index] {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "cross_dep dependency cycle at column {index}"
+ )));
+ }
+ visiting[index] = true;
+ let column = &directory.columns[index];
+ let values = match column.codec {
+ ColCodec::RawJson => decode_raw_json(column.payload)?,
+ ColCodec::Lz4Json => decode_lz4_json(column.payload)?,
+ ColCodec::Constant => decode_constant(column.payload, directory.num_docs)?,
+ ColCodec::DictBitpack => decode_dict_bitpack(column.payload, directory.num_docs)?,
+ ColCodec::CrossDep => {
+ let source_index = cross_dep_source_index(column.payload)?;
+ let source =
+ decode_projected_column(source_index, directory, decoded, visiting, depth + 1)?
+ .clone();
+ let mut dependencies = vec![Vec::new(); directory.columns.len()];
+ dependencies[source_index] = source;
+ decode_cross_dep(
+ column.payload,
+ directory.num_docs,
+ &dependencies,
+ &HashMap::new(),
+ )?
+ .ok_or_else(|| {
+ StorageError::Other(anyhow::anyhow!(
+ "cross_dep source column {source_index} was not resolved"
+ ))
+ })?
+ }
+ };
+ visiting[index] = false;
+ if values.len() != directory.num_docs {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "v2 column {} row count {} != header {}",
+ column.name,
+ values.len(),
+ directory.num_docs
+ )));
+ }
+ decoded[index] = Some(values);
+ Ok(decoded[index].as_ref().unwrap())
+}
+
+fn decoded_json_column(column: &V2ColumnRef<'_>) -> Result<Option<Vec<u8>>> {
+ match column.codec {
+ ColCodec::RawJson => zstd::decode_all(column.payload)
+ .map(Some)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("raw zstd decode: {e}"))),
+ ColCodec::Lz4Json => lz4_flex::decompress_size_prepended(column.payload)
+ .map(Some)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("lz4 decode: {e}"))),
+ ColCodec::Constant => Ok(Some(column.payload.to_vec())),
+ ColCodec::DictBitpack | ColCodec::CrossDep => Ok(None),
+ }
+}
+
+fn finite_f32_vector(values: Vec<f64>) -> Option<Vec<f32>> {
+ let mut out = Vec::with_capacity(values.len());
+ for value in values {
+ let value = value as f32;
+ if !value.is_finite() {
+ return None;
+ }
+ out.push(value);
+ }
+ Some(out)
+}
+
+struct TypedVectorRowsVisitor<'a> {
+ expected_rows: usize,
+ column_index: usize,
+ checkpoint: &'a mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+ cancelled: &'a std::cell::Cell<bool>,
+}
+
+impl<'de> serde::de::Visitor<'de> for TypedVectorRowsVisitor<'_> {
+ type Value = Option<StoredVectorRows>;
+
+ fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str("a vector column JSON array")
+ }
+
+ fn visit_seq<A>(self, mut seq: A) -> std::result::Result<Self::Value, A::Error>
+ where
+ A: serde::de::SeqAccess<'de>,
+ {
+ let mut out = Vec::with_capacity(self.expected_rows);
+ let mut supported = true;
+ for row in 0..self.expected_rows {
+ let Some(value) = seq.next_element::<serde_json::Value>()? else {
+ return Err(serde::de::Error::custom("vector column ended early"));
+ };
+ let typed = match value {
+ serde_json::Value::Null => None,
+ serde_json::Value::Array(values) => {
+ let values = values
+ .into_iter()
+ .map(|value| value.as_f64())
+ .collect::<Option<Vec<_>>>()
+ .and_then(finite_f32_vector);
+ let Some(values) = values else {
+ supported = false;
+ out.push(None);
+ continue;
+ };
+ Some(values)
+ }
+ _ => {
+ supported = false;
+ None
+ }
+ };
+ out.push(typed);
+ let processed = row + 1;
+ if processed % STORED_DECODE_CHECK_INTERVAL == 0
+ && (self.checkpoint)(StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index: self.column_index,
+ rows_processed: processed,
+ })
+ .is_break()
+ {
+ self.cancelled.set(true);
+ return Err(serde::de::Error::custom("stored decode cancelled"));
+ }
+ }
+ if seq.next_element::<serde::de::IgnoredAny>()?.is_some() {
+ return Err(serde::de::Error::custom("vector column has extra rows"));
+ }
+ Ok(supported.then_some(out))
+ }
+}
+
+fn decode_typed_vector_rows_controlled(
+ column: &V2ColumnRef<'_>,
+ num_docs: usize,
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Option<StoredVectorRows>, ()>> {
+ if column.codec == ColCodec::Constant {
+ return decode_typed_vector_rows(column, num_docs).map(Ok);
+ }
+ match column.codec {
+ ColCodec::RawJson => {
+ let decoder = zstd::stream::read::Decoder::new(column.payload).map_err(|error| {
+ StorageError::Other(anyhow::anyhow!("raw zstd decode: {error}"))
+ })?;
+ parse_typed_vector_reader(decoder, num_docs, column_index, checkpoint)
+ }
+ ColCodec::Lz4Json => {
+ let raw = lz4_flex::decompress_size_prepended(column.payload)
+ .map_err(|error| StorageError::Other(anyhow::anyhow!("lz4 decode: {error}")))?;
+ parse_typed_vector_reader(raw.as_slice(), num_docs, column_index, checkpoint)
+ }
+ _ => Ok(Ok(None)),
+ }
+}
+
+fn parse_typed_vector_reader<R: std::io::Read>(
+ reader: R,
+ num_docs: usize,
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Option<StoredVectorRows>, ()>> {
+ use serde::de::Deserializer as _;
+ let cancelled = std::cell::Cell::new(false);
+ let mut deserializer = serde_json::Deserializer::from_reader(reader);
+ let value = match deserializer.deserialize_seq(TypedVectorRowsVisitor {
+ expected_rows: num_docs,
+ column_index,
+ checkpoint,
+ cancelled: &cancelled,
+ }) {
+ Ok(value) => value,
+ Err(_) if cancelled.get() => return Ok(Err(())),
+ Err(error) => {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "vector json decode: {error}"
+ )));
+ }
+ };
+ if value.is_some() {
+ deserializer
+ .end()
+ .map_err(|error| StorageError::Other(anyhow::anyhow!("vector json decode: {error}")))?;
+ }
+ Ok(Ok(value))
+}
+
+fn decode_typed_vector_rows(
+ column: &V2ColumnRef<'_>,
+ num_docs: usize,
+) -> Result<Option<StoredVectorRows>> {
+ use serde_json::value::RawValue;
+ let Some(raw) = decoded_json_column(column)? else {
+ return Ok(None);
+ };
+ let rows: Vec<&RawValue> = if column.codec == ColCodec::Constant {
+ let row: &RawValue = serde_json::from_slice(&raw)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("constant decode: {e}")))?;
+ vec![row; num_docs]
+ } else {
+ serde_json::from_slice(&raw)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("vector json decode: {e}")))?
+ };
+ if rows.len() != num_docs {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "v2 vector row count {} != header {num_docs}",
+ rows.len()
+ )));
+ }
+ let mut out = Vec::with_capacity(num_docs);
+ for row in rows {
+ if row.get() == "null" {
+ out.push(None);
+ continue;
+ }
+ let Ok(values) = serde_json::from_str::<Vec<f64>>(row.get()) else {
+ return Ok(None);
+ };
+ let Some(vector) = finite_f32_vector(values) else {
+ return Ok(None);
+ };
+ out.push(Some(vector));
+ }
+ Ok(Some(out))
+}
+
+fn decode_typed_vector_chunk_rows(
+ column: &V2ColumnRef<'_>,
+ num_docs: usize,
+) -> Result<Option<StoredVectorChunkRows>> {
+ use serde_json::value::RawValue;
+ let Some(raw) = decoded_json_column(column)? else {
+ return Ok(None);
+ };
+ let rows: Vec<&RawValue> = if column.codec == ColCodec::Constant {
+ let row: &RawValue = serde_json::from_slice(&raw)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("constant decode: {e}")))?;
+ vec![row; num_docs]
+ } else {
+ serde_json::from_slice(&raw)
+ .map_err(|e| StorageError::Other(anyhow::anyhow!("vector chunks json decode: {e}")))?
+ };
+ if rows.len() != num_docs {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "v2 vector chunks row count {} != header {num_docs}",
+ rows.len()
+ )));
+ }
+ let mut out = Vec::with_capacity(num_docs);
+ for row in rows {
+ if row.get() == "null" {
+ out.push(None);
+ continue;
+ }
+ let Ok(chunks) = serde_json::from_str::<Vec<Vec<f64>>>(row.get()) else {
+ return Ok(None);
+ };
+ let mut typed = Vec::with_capacity(chunks.len());
+ for chunk in chunks {
+ let Some(chunk) = finite_f32_vector(chunk) else {
+ return Ok(None);
+ };
+ typed.push(chunk);
+ }
+ out.push(Some(typed));
+ }
+ Ok(Some(out))
+}
+
+fn decode_typed_vector_chunk_rows_controlled(
+ column: &V2ColumnRef<'_>,
+ num_docs: usize,
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Option<StoredVectorChunkRows>, ()>> {
+ if column.codec == ColCodec::Constant {
+ return decode_typed_vector_chunk_rows(column, num_docs).map(Ok);
+ }
+ match column.codec {
+ ColCodec::RawJson => {
+ let decoder = zstd::stream::read::Decoder::new(column.payload).map_err(|error| {
+ StorageError::Other(anyhow::anyhow!("raw zstd decode: {error}"))
+ })?;
+ parse_typed_chunk_reader(decoder, num_docs, column_index, checkpoint)
+ }
+ ColCodec::Lz4Json => {
+ let raw = lz4_flex::decompress_size_prepended(column.payload)
+ .map_err(|error| StorageError::Other(anyhow::anyhow!("lz4 decode: {error}")))?;
+ parse_typed_chunk_reader(raw.as_slice(), num_docs, column_index, checkpoint)
+ }
+ _ => Ok(Ok(None)),
+ }
+}
+
+fn parse_typed_chunk_reader<R: std::io::Read>(
+ reader: R,
+ num_docs: usize,
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Option<StoredVectorChunkRows>, ()>> {
+ use serde::de::Deserializer as _;
+ struct Visitor<'a> {
+ rows: usize,
+ column: usize,
+ checkpoint: &'a mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+ cancelled: &'a std::cell::Cell<bool>,
+ }
+ impl<'de> serde::de::Visitor<'de> for Visitor<'_> {
+ type Value = Option<StoredVectorChunkRows>;
+ fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ f.write_str("a vector chunks column JSON array")
+ }
+ fn visit_seq<A>(self, mut seq: A) -> std::result::Result<Self::Value, A::Error>
+ where
+ A: serde::de::SeqAccess<'de>,
+ {
+ let mut out = Vec::with_capacity(self.rows);
+ let mut supported = true;
+ for row in 0..self.rows {
+ let Some(value) = seq.next_element::<serde_json::Value>()? else {
+ return Err(serde::de::Error::custom("vector chunks ended early"));
+ };
+ let typed = match value {
+ serde_json::Value::Null => None,
+ serde_json::Value::Array(chunks) => {
+ let mut result = Vec::with_capacity(chunks.len());
+ for chunk in chunks {
+ let serde_json::Value::Array(values) = chunk else {
+ supported = false;
+ continue;
+ };
+ let vector = values
+ .into_iter()
+ .map(|value| value.as_f64())
+ .collect::<Option<Vec<_>>>()
+ .and_then(finite_f32_vector);
+ let Some(vector) = vector else {
+ supported = false;
+ continue;
+ };
+ result.push(vector);
+ }
+ Some(result)
+ }
+ _ => {
+ supported = false;
+ None
+ }
+ };
+ out.push(typed);
+ let processed = row + 1;
+ if processed % STORED_DECODE_CHECK_INTERVAL == 0
+ && (self.checkpoint)(StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index: self.column,
+ rows_processed: processed,
+ })
+ .is_break()
+ {
+ self.cancelled.set(true);
+ return Err(serde::de::Error::custom("stored decode cancelled"));
+ }
+ }
+ if seq.next_element::<serde::de::IgnoredAny>()?.is_some() {
+ return Err(serde::de::Error::custom("vector chunks has extra rows"));
+ }
+ Ok(supported.then_some(out))
+ }
+ }
+ let cancelled = std::cell::Cell::new(false);
+ let mut deserializer = serde_json::Deserializer::from_reader(reader);
+ let value = match deserializer.deserialize_seq(Visitor {
+ rows: num_docs,
+ column: column_index,
+ checkpoint,
+ cancelled: &cancelled,
+ }) {
+ Ok(value) => value,
+ Err(_) if cancelled.get() => return Ok(Err(())),
+ Err(error) => {
+ return Err(StorageError::Other(anyhow::anyhow!(
+ "vector chunks json decode: {error}"
+ )));
+ }
+ };
+ if value.is_some() {
+ deserializer.end().map_err(|error| {
+ StorageError::Other(anyhow::anyhow!("vector chunks json decode: {error}"))
+ })?;
+ }
+ Ok(Ok(value))
+}
+
+/// Decode the identity and vector columns needed by exact kNN without
+/// reconstructing complete source documents.
+pub fn decode_stored_v2_knn_projection(
+ bytes: &[u8],
+ vector_field: &str,
+ vector_chunks_field: Option<&str>,
+) -> Result<StoredV2KnnProjectionResult> {
+ match decode_stored_v2_knn_projection_controlled(
+ bytes,
+ vector_field,
+ vector_chunks_field,
+ |_| std::ops::ControlFlow::Continue(()),
+ )? {
+ StoredDecodeRun::Complete(result) => Ok(result),
+ StoredDecodeRun::Cancelled => unreachable!("non-cancelling compatibility wrapper"),
+ }
+}
+
+pub fn decode_stored_v2_knn_projection_controlled<F>(
+ bytes: &[u8],
+ vector_field: &str,
+ vector_chunks_field: Option<&str>,
+ mut checkpoint: F,
+) -> Result<StoredDecodeRun<StoredV2KnnProjectionResult>>
+where
+ F: FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+{
+ if bytes.len() < 4 || &bytes[..4] != STORED_V2_MAGIC {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::NotV2,
+ ));
+ }
+ if matches!(vector_field, "__id" | "__seq_no")
+ || vector_chunks_field
+ .is_some_and(|field| matches!(field, "__id" | "__seq_no") || field == vector_field)
+ {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::UnsupportedVectorShape,
+ ));
+ }
+ let directory = parse_v2_directory(&bytes[4..])?;
+ let Some(vector_column) = directory
+ .columns
+ .iter()
+ .find(|column| column.name == vector_field)
+ else {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::MissingVectorColumn,
+ ));
+ };
+ let vector_index = directory
+ .columns
+ .iter()
+ .position(|column| std::ptr::eq(column, vector_column))
+ .unwrap();
+ if decode_cancelled(
+ &mut checkpoint,
+ StoredDecodePhase::BeforeColumn,
+ vector_index,
+ 0,
+ ) {
+ return Ok(StoredDecodeRun::Cancelled);
+ }
+ let Some(vectors) = (match decode_typed_vector_rows_controlled(
+ vector_column,
+ directory.num_docs,
+ vector_index,
+ &mut checkpoint,
+ )? {
+ Ok(value) => value,
+ Err(()) => return Ok(StoredDecodeRun::Cancelled),
+ }) else {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::UnsupportedVectorShape,
+ ));
+ };
+ if decode_cancelled(
+ &mut checkpoint,
+ StoredDecodePhase::AfterColumn,
+ vector_index,
+ directory.num_docs,
+ ) {
+ return Ok(StoredDecodeRun::Cancelled);
+ }
+ let vector_chunks = match vector_chunks_field {
+ Some(field) => match directory.columns.iter().find(|column| column.name == field) {
+ Some(column) => {
+ let index = directory
+ .columns
+ .iter()
+ .position(|candidate| std::ptr::eq(candidate, column))
+ .unwrap();
+ if decode_cancelled(&mut checkpoint, StoredDecodePhase::BeforeColumn, index, 0) {
+ return Ok(StoredDecodeRun::Cancelled);
+ }
+ let Some(chunks) = (match decode_typed_vector_chunk_rows_controlled(
+ column,
+ directory.num_docs,
+ index,
+ &mut checkpoint,
+ )? {
+ Ok(value) => value,
+ Err(()) => return Ok(StoredDecodeRun::Cancelled),
+ }) else {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::UnsupportedVectorShape,
+ ));
+ };
+ if decode_cancelled(
+ &mut checkpoint,
+ StoredDecodePhase::AfterColumn,
+ index,
+ directory.num_docs,
+ ) {
+ return Ok(StoredDecodeRun::Cancelled);
+ }
+ Some(chunks)
+ }
+ None => None,
+ },
+ None => None,
+ };
+ let (identity_num_docs, id_values, seq_values) =
+ match row_hydration::decode_v2_identity_columns_controlled(bytes, &mut checkpoint)? {
+ StoredDecodeRun::Complete(Some(values)) => values,
+ StoredDecodeRun::Complete(None) => {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::UnsupportedVectorShape,
+ ));
+ }
+ StoredDecodeRun::Cancelled => return Ok(StoredDecodeRun::Cancelled),
+ };
+ let ids = id_values
+ .into_iter()
+ .map(|value| value.as_str().map(ToOwned::to_owned))
+ .collect();
+ let seq_nos = seq_values.into_iter().map(|value| value.as_u64()).collect();
+ Ok(StoredDecodeRun::Complete(
+ StoredV2KnnProjectionResult::Projected(StoredV2KnnProjection {
+ num_docs: identity_num_docs,
+ ids,
+ seq_nos,
+ vectors,
+ vector_chunks,
+ }),
+ ))
+}
+
fn decode_stored_v2(body: &[u8]) -> Result<Vec<u8>> {
let mut cur = Cursor::new(body);
let num_docs = cur
@@ -1371,6 +2160,634 @@ mod tests {
assert_eq!(&decoded, raw);
}
+ fn projection_fixture() -> (Vec<serde_json::Value>, Vec<u8>) {
+ let docs: Vec<_> = (0..256)
+ .map(|i| {
+ json!({
+ "_id": format!("doc-{i}"),
+ "_seq_no": i,
+ "_source": {
+ "category": if i % 2 == 0 { "even" } else { "odd" },
+ "embedding": [i as f64 / 10.0, 0.25, -0.5],
+ "embedding_chunks": [
+ [i as f64 / 10.0, 0.25, -0.5],
+ [-0.0, 1.25e-10, -2]
+ ],
+ "large_unrequested": "the same payload repeated to compress well"
+ }
+ })
+ })
+ .collect();
+ let encoded = encode_stored_v2(&serde_json::to_vec(&docs).unwrap());
+ assert_eq!(&encoded[..4], STORED_V2_MAGIC);
+ (docs, encoded)
+ }
+
+ fn handcrafted_v2(num_docs: u32, columns: &[(&str, u8, Vec<u8>)]) -> Vec<u8> {
+ let mut out = Vec::new();
+ out.extend_from_slice(STORED_V2_MAGIC);
+ out.write_u32::<LittleEndian>(num_docs).unwrap();
+ out.write_u32::<LittleEndian>(columns.len() as u32).unwrap();
+ for (name, codec, payload) in columns {
+ out.write_u16::<LittleEndian>(name.len() as u16).unwrap();
+ out.extend_from_slice(name.as_bytes());
+ out.push(*codec);
+ out.write_u32::<LittleEndian>(payload.len() as u32).unwrap();
+ out.extend_from_slice(payload);
+ }
+ out
+ }
+
+ fn raw_cross_dep(source_index: u32) -> Vec<u8> {
+ let mut payload = vec![0];
+ payload.write_u32::<LittleEndian>(source_index).unwrap();
+ payload
+ }
+
+ fn valid_cross_dep(source_index: u32, mode: i64) -> Vec<u8> {
+ let mut payload = raw_cross_dep(source_index);
+ payload.write_u32::<LittleEndian>(1).unwrap();
+ payload.write_i64::<LittleEndian>(mode).unwrap();
+ payload.write_u32::<LittleEndian>(0).unwrap();
+ payload
+ }
+
+ fn lz4_json(value: &serde_json::Value) -> Vec<u8> {
+ lz4_flex::compress_prepend_size(&serde_json::to_vec(value).unwrap())
+ }
+
+ fn typed_fixture_with_columns(
+ num_docs: usize,
+ vector_codec: ColCodec,
+ vector_payload: Vec<u8>,
+ chunks: Option<(ColCodec, Vec<u8>)>,
+ ) -> Vec<u8> {
+ let ids = json!((0..num_docs).map(|i| format!("id-{i}")).collect::<Vec<_>>());
+ let seq = json!((0..num_docs).collect::<Vec<_>>());
+ let mut columns = vec![
+ ("__id", ColCodec::Lz4Json as u8, lz4_json(&ids)),
+ ("__seq_no", ColCodec::Lz4Json as u8, lz4_json(&seq)),
+ ("embedding", vector_codec as u8, vector_payload),
+ ];
+ if let Some((codec, payload)) = chunks {
+ columns.push(("embedding_chunks", codec as u8, payload));
+ }
+ handcrafted_v2(num_docs as u32, &columns)
+ }
+
+ #[test]
+ fn v2_projection_decodes_only_requested_columns_with_full_decode_parity() {
+ let (docs, encoded) = projection_fixture();
+ let StoredV2ProjectionResult::Projected(projected) =
+ decode_stored_v2_projection(&encoded, &["__id", "embedding"]).unwrap()
+ else {
+ panic!("fixture should support projection");
+ };
+ assert_eq!(projected.num_docs, docs.len());
+ assert_eq!(projected.columns.len(), 2);
+ assert!(!projected.columns.contains_key("large_unrequested"));
+ for (row, expected) in docs.iter().enumerate() {
+ assert_eq!(projected.columns["__id"][row], expected["_id"]);
+ assert_eq!(
+ projected.columns["embedding"][row],
+ expected["_source"]["embedding"]
+ );
+ }
+ let StoredV2ProjectionResult::Projected(seq_projection) =
+ decode_stored_v2_projection(&encoded, &["__seq_no"]).unwrap()
+ else {
+ panic!("CROSS_DEP sequence column should resolve");
+ };
+ for (row, expected) in docs.iter().enumerate() {
+ assert_eq!(seq_projection.columns["__seq_no"][row], expected["_seq_no"]);
+ }
+ }
+
+ #[test]
+ fn v2_projection_does_not_decode_unrequested_payload() {
+ let (_, mut encoded) = projection_fixture();
+ let (payload_offset, payload_len) = {
+ let directory = parse_v2_directory(&encoded[4..]).unwrap();
+ let column = directory
+ .columns
+ .iter()
+ .find(|column| column.name == "large_unrequested")
+ .unwrap();
+ (
+ column.payload.as_ptr() as usize - encoded.as_ptr() as usize,
+ column.payload.len(),
+ )
+ };
+ encoded[payload_offset + payload_len / 2] ^= 0xff;
+
+ let StoredV2ProjectionResult::Projected(projected) =
+ decode_stored_v2_projection(&encoded, &["__id"]).unwrap()
+ else {
+ panic!("an unrelated corrupt payload must not be decoded");
+ };
+ assert_eq!(projected.columns["__id"].len(), 256);
+ assert!(
+ decode_stored(&encoded).is_err(),
+ "the full decoder must still observe corrupt unrequested payloads"
+ );
+ }
+
+ #[test]
+ fn v2_knn_projection_resolves_identity_and_typed_vectors() {
+ let (docs, encoded) = projection_fixture();
+ let StoredV2KnnProjectionResult::Projected(projected) =
+ decode_stored_v2_knn_projection(&encoded, "embedding", Some("embedding_chunks"))
+ .unwrap()
+ else {
+ panic!("fixture should support typed projection");
+ };
+ assert_eq!(projected.num_docs, 256);
+ assert_eq!(projected.ids[42].as_deref(), Some("doc-42"));
+ assert_eq!(projected.seq_nos[42], Some(42));
+ for row in [0, 1, 42, 255] {
+ let expected = docs[row]["_source"]["embedding"].as_array().unwrap();
+ let actual = projected.vectors[row].as_ref().unwrap();
+ for (actual, expected) in actual.iter().zip(expected) {
+ assert_eq!(
+ actual.to_bits(),
+ (expected.as_f64().unwrap() as f32).to_bits()
+ );
+ }
+ }
+ let chunks = projected.vector_chunks.as_ref().unwrap()[7]
+ .as_ref()
+ .unwrap();
+ assert_eq!(chunks.len(), 2);
+ assert_eq!(chunks[1][0].to_bits(), (-0.0f32).to_bits());
+ assert_eq!(chunks[1][1].to_bits(), (1.25e-10f32).to_bits());
+ assert_eq!(chunks[1][2], -2.0);
+ }
+
+ #[test]
+ fn controlled_knn_projection_cancels_without_changing_compatibility_outcomes() {
+ let (_, encoded) = projection_fixture();
+ let mut observed = Vec::new();
+ let run = decode_stored_v2_knn_projection_controlled(
+ &encoded,
+ "embedding",
+ Some("embedding_chunks"),
+ |point| {
+ observed.push(point);
+ if point.phase == StoredDecodePhase::Rows && point.rows_processed == 128 {
+ std::ops::ControlFlow::Break(())
+ } else {
+ std::ops::ControlFlow::Continue(())
+ }
+ },
+ )
+ .unwrap();
+ assert_eq!(run, StoredDecodeRun::Cancelled);
+ assert!(observed.iter().any(|point| {
+ point.phase == StoredDecodePhase::BeforeColumn && point.rows_processed == 0
+ }));
+
+ let controlled = decode_stored_v2_knn_projection_controlled(
+ &encoded,
+ "embedding",
+ Some("embedding_chunks"),
+ |_| std::ops::ControlFlow::Continue(()),
+ )
+ .unwrap();
+ assert_eq!(
+ controlled,
+ StoredDecodeRun::Complete(
+ decode_stored_v2_knn_projection(&encoded, "embedding", Some("embedding_chunks"))
+ .unwrap()
+ )
+ );
+
+ assert_eq!(
+ decode_stored_v2_knn_projection_controlled(
+ &encode_stored_lz4(b"[]"),
+ "embedding",
+ None,
+ |_| std::ops::ControlFlow::Continue(())
+ )
+ .unwrap(),
+ StoredDecodeRun::Complete(StoredV2KnnProjectionResult::NotV2)
+ );
+ }
+
+ #[test]
+ fn controlled_knn_projection_stops_before_bad_row_129() {
+ let rows_with_bad_129 = |chunks: bool| {
+ let values: Vec<_> = (0..256)
+ .map(|row| {
+ if row == 128 {
+ json!("row-129-must-not-be-consumed")
+ } else if chunks {
+ json!([[1.0, 0.0]])
+ } else {
+ json!([1.0, 0.0])
+ }
+ })
+ .collect();
+ zstd::encode_all(
+ Cursor::new(serde_json::to_vec(&values).unwrap()),
+ STORED_ZSTD_LEVEL,
+ )
+ .unwrap()
+ };
+ let constant_id = serde_json::to_vec(&json!("id")).unwrap();
+ let constant_seq = serde_json::to_vec(&json!(1)).unwrap();
+
+ for bad_column in ["embedding", "embedding_chunks"] {
+ let embedding = if bad_column == "embedding" {
+ rows_with_bad_129(false)
+ } else {
+ let values = vec![json!([1.0, 0.0]); 256];
+ zstd::encode_all(
+ Cursor::new(serde_json::to_vec(&values).unwrap()),
+ STORED_ZSTD_LEVEL,
+ )
+ .unwrap()
+ };
+ let chunks = if bad_column == "embedding_chunks" {
+ rows_with_bad_129(true)
+ } else {
+ let values = vec![json!([[1.0, 0.0]]); 256];
+ zstd::encode_all(
+ Cursor::new(serde_json::to_vec(&values).unwrap()),
+ STORED_ZSTD_LEVEL,
+ )
+ .unwrap()
+ };
+ let encoded = handcrafted_v2(
+ 256,
+ &[
+ ("__id", ColCodec::Constant as u8, constant_id.clone()),
+ ("__seq_no", ColCodec::Constant as u8, constant_seq.clone()),
+ ("embedding", ColCodec::RawJson as u8, embedding),
+ ("embedding_chunks", ColCodec::RawJson as u8, chunks),
+ ],
+ );
+ let cancel_column = if bad_column == "embedding" { 2 } else { 3 };
+ assert_eq!(
+ decode_stored_v2_knn_projection_controlled(
+ &encoded,
+ "embedding",
+ Some("embedding_chunks"),
+ |point| {
+ if point.column_index == cancel_column
+ && point.phase == StoredDecodePhase::Rows
+ && point.rows_processed == 128
+ {
+ std::ops::ControlFlow::Break(())
+ } else {
+ std::ops::ControlFlow::Continue(())
+ }
+ }
+ )
+ .unwrap(),
+ StoredDecodeRun::Cancelled,
+ "{bad_column} must cancel before consuming row 129"
+ );
+ assert_eq!(
+ decode_stored_v2_knn_projection_controlled(
+ &encoded,
+ "embedding",
+ Some("embedding_chunks"),
+ |_| std::ops::ControlFlow::Continue(())
+ )
+ .unwrap(),
+ StoredDecodeRun::Complete(StoredV2KnnProjectionResult::UnsupportedVectorShape),
+ "without cancellation {bad_column} must consume bad row 129"
+ );
+ }
+ }
+
+ #[test]
+ fn v2_knn_projection_has_explicit_legacy_missing_and_shape_outcomes() {
+ let legacy = encode_stored_lz4(br#"[{"_id":"legacy"}]"#);
+ assert_eq!(
+ decode_stored_v2_knn_projection(&legacy, "embedding", None).unwrap(),
+ StoredV2KnnProjectionResult::NotV2
+ );
+
+ let (_, encoded) = projection_fixture();
+ assert_eq!(
+ decode_stored_v2_knn_projection(&encoded, "missing", None).unwrap(),
+ StoredV2KnnProjectionResult::MissingVectorColumn
+ );
+
+ let malformed_docs: Vec<_> = (0..256)
+ .map(|i| {
+ json!({
+ "_id": format!("bad-{i}"),
+ "_seq_no": i,
+ "_source": {
+ "embedding": if i == 128 {
+ json!([1.0, "not-a-number", 3.0])
+ } else {
+ json!([1.0, 2.0, 3.0])
+ }
+ }
+ })
+ })
+ .collect();
+ let malformed = encode_stored_v2(&serde_json::to_vec(&malformed_docs).unwrap());
+ assert_eq!(&malformed[..4], STORED_V2_MAGIC);
+ assert_eq!(
+ decode_stored_v2_knn_projection(&malformed, "embedding", None).unwrap(),
+ StoredV2KnnProjectionResult::UnsupportedVectorShape
+ );
+ }
+
+ #[test]
+ fn v2_projection_rejects_cross_dep_cycles_and_bad_source_indices() {
+ let cycle = handcrafted_v2(
+ 1,
+ &[
+ ("a", ColCodec::CrossDep as u8, raw_cross_dep(1)),
+ ("b", ColCodec::CrossDep as u8, raw_cross_dep(0)),
+ ],
+ );
+ let error = decode_stored_v2_projection(&cycle, &["a"]).unwrap_err();
+ assert!(error.to_string().contains("dependency cycle"), "{error}");
+
+ let out_of_range = handcrafted_v2(1, &[("a", ColCodec::CrossDep as u8, raw_cross_dep(9))]);
+ let error = decode_stored_v2_projection(&out_of_range, &["a"]).unwrap_err();
+ assert!(error.to_string().contains("out of range"), "{error}");
+
+ let bad_flag = handcrafted_v2(1, &[("a", ColCodec::CrossDep as u8, vec![7, 0, 0, 0, 0])]);
+ let error = decode_stored_v2_projection(&bad_flag, &["a"]).unwrap_err();
+ assert!(
+ error.to_string().contains("invalid compression flag"),
+ "{error}"
+ );
+ assert!(
+ decode_stored(&bad_flag).is_err(),
+ "full and selective decoders must reject the same bad flag"
+ );
+ }
+
+ #[test]
+ fn v2_projection_resolves_forward_multihop_and_shared_dependencies() {
+ let id_payload = serde_json::to_vec(&vec!["doc"; 4]).unwrap();
+ let seq_payload = serde_json::to_vec(&vec![0, 1, 2, 3]).unwrap();
+ let encoded = handcrafted_v2(
+ 4,
+ &[
+ (
+ "__id",
+ ColCodec::Lz4Json as u8,
+ lz4_flex::compress_prepend_size(&id_payload),
+ ),
+ (
+ "__seq_no",
+ ColCodec::Lz4Json as u8,
+ lz4_flex::compress_prepend_size(&seq_payload),
+ ),
+ ("a", ColCodec::CrossDep as u8, valid_cross_dep(3, 10)),
+ ("b", ColCodec::CrossDep as u8, valid_cross_dep(4, 5)),
+ ("base", ColCodec::Constant as u8, br#""key""#.to_vec()),
+ ("d", ColCodec::CrossDep as u8, valid_cross_dep(4, 20)),
+ ],
+ );
+ let StoredV2ProjectionResult::Projected(projected) =
+ decode_stored_v2_projection(&encoded, &["a", "d"]).unwrap()
+ else {
+ panic!("valid recursive dependencies should project");
+ };
+ assert_eq!(
+ projected
+ .columns
+ .keys()
+ .cloned()
+ .collect::<std::collections::HashSet<_>>(),
+ ["a".to_string(), "d".to_string()].into_iter().collect()
+ );
+ assert_eq!(projected.columns["a"], vec![json!(10); 4]);
+ assert_eq!(projected.columns["d"], vec![json!(20); 4]);
+
+ let full: Vec<serde_json::Value> =
+ serde_json::from_slice(&decode_stored(&encoded).unwrap()).unwrap();
+ for row in full {
+ assert_eq!(row["_source"]["a"], 10);
+ assert_eq!(row["_source"]["d"], 20);
+ }
+ }
+
+ #[test]
+ fn cross_dep_checked_exceptions_reject_truncation_overflow_and_trailing_bytes() {
+ let dependencies = vec![Vec::new(), vec![json!("key"); 4]];
+ let make = |exception_bytes: &[u8]| {
+ let mut payload = valid_cross_dep(1, 7);
+ let len = payload.len();
+ payload[len - 4..].copy_from_slice(&1u32.to_le_bytes());
+ payload.extend_from_slice(exception_bytes);
+ payload
+ };
+
+ let truncated = make(&[0x80]);
+ assert!(decode_cross_dep(&truncated, 4, &dependencies, &HashMap::new()).is_err());
+
+ let overlong = make(&[0x80; 11]);
+ assert!(decode_cross_dep(&overlong, 4, &dependencies, &HashMap::new()).is_err());
+
+ let out_of_range = make(&[4, 0]);
+ assert!(decode_cross_dep(&out_of_range, 4, &dependencies, &HashMap::new()).is_err());
+
+ let mut trailing = valid_cross_dep(1, 7);
+ trailing.push(0);
+ assert!(decode_cross_dep(&trailing, 4, &dependencies, &HashMap::new()).is_err());
+ }
+
+ #[test]
+ fn v2_knn_projection_preserves_384d_f32_bits_and_rejects_overflow() {
+ let docs: Vec<_> = (0..256)
+ .map(|row| {
+ let vector: Vec<f64> = (0..384)
+ .map(|dim| (row as f64 - dim as f64) / 997.0)
+ .collect();
+ json!({
+ "_id": format!("wide-{row}"),
+ "_seq_no": row,
+ "_source": {"embedding": vector}
+ })
+ })
+ .collect();
+ let encoded = encode_stored_v2(&serde_json::to_vec(&docs).unwrap());
+ assert_eq!(&encoded[..4], STORED_V2_MAGIC);
+ let StoredV2KnnProjectionResult::Projected(projected) =
+ decode_stored_v2_knn_projection(&encoded, "embedding", None).unwrap()
+ else {
+ panic!("384d vectors should project");
+ };
+ for row in [0, 127, 255] {
+ let actual = projected.vectors[row].as_ref().unwrap();
+ assert_eq!(actual.len(), 384);
+ for dim in [0, 1, 191, 383] {
+ let expected = docs[row]["_source"]["embedding"][dim].as_f64().unwrap() as f32;
+ assert_eq!(actual[dim].to_bits(), expected.to_bits());
+ }
+ }
+
+ let overflow_docs: Vec<_> = (0..256)
+ .map(|row| {
+ json!({
+ "_id": format!("overflow-{row}"),
+ "_seq_no": row,
+ "_source": {"embedding": [1e39, 0.0]}
+ })
+ })
+ .collect();
+ let overflow = encode_stored_v2(&serde_json::to_vec(&overflow_docs).unwrap());
+ assert_eq!(
+ decode_stored_v2_knn_projection(&overflow, "embedding", None).unwrap(),
+ StoredV2KnnProjectionResult::UnsupportedVectorShape
+ );
+ }
+
+ #[test]
+ fn v2_knn_projection_forced_lz4_nulls_and_optional_missing_chunks() {
+ let vectors = json!([[1.0, -0.0], null, [], [3, 4]]);
+ let chunks = json!([[[1.0, 2.0]], null, [], [[3.0], [4.0, 5.0]]]);
+ let encoded = typed_fixture_with_columns(
+ 4,
+ ColCodec::Lz4Json,
+ lz4_json(&vectors),
+ Some((ColCodec::Lz4Json, lz4_json(&chunks))),
+ );
+ let StoredV2KnnProjectionResult::Projected(projected) =
+ decode_stored_v2_knn_projection(&encoded, "embedding", Some("embedding_chunks"))
+ .unwrap()
+ else {
+ panic!("forced LZ4 vectors should project");
+ };
+ assert_eq!(
+ projected.vectors[0].as_ref().unwrap()[1].to_bits(),
+ (-0.0f32).to_bits()
+ );
+ assert_eq!(projected.vectors[1], None);
+ assert_eq!(projected.vectors[2], Some(Vec::new()));
+ assert_eq!(projected.vector_chunks.as_ref().unwrap()[1], None);
+ assert_eq!(
+ projected.vector_chunks.as_ref().unwrap()[3],
+ Some(vec![vec![3.0], vec![4.0, 5.0]])
+ );
+
+ let StoredV2KnnProjectionResult::Projected(missing_chunks) =
+ decode_stored_v2_knn_projection(&encoded, "embedding", Some("different_chunks"))
+ .unwrap()
+ else {
+ panic!("missing optional chunks must not block pooled vectors");
+ };
+ assert_eq!(missing_chunks.vector_chunks, None);
+ }
+
+ #[test]
+ fn v2_knn_projection_constant_vectors_and_identity_cell_semantics() {
+ let encoded = typed_fixture_with_columns(
+ 4,
+ ColCodec::Constant,
+ br#"[1.5,-0.0]"#.to_vec(),
+ Some((ColCodec::Constant, b"null".to_vec())),
+ );
+ let StoredV2KnnProjectionResult::Projected(projected) =
+ decode_stored_v2_knn_projection(&encoded, "embedding", Some("embedding_chunks"))
+ .unwrap()
+ else {
+ panic!("constant vectors should project");
+ };
+ assert_eq!(projected.vectors, vec![Some(vec![1.5, -0.0]); 4]);
+ assert_eq!(projected.vector_chunks, Some(vec![None; 4]));
+
+ let wrong_identity = handcrafted_v2(
+ 2,
+ &[
+ ("__id", ColCodec::Lz4Json as u8, lz4_json(&json!(["ok", 7]))),
+ (
+ "__seq_no",
+ ColCodec::Lz4Json as u8,
+ lz4_json(&json!([0, -1])),
+ ),
+ (
+ "embedding",
+ ColCodec::Lz4Json as u8,
+ lz4_json(&json!([[1.0], [2.0]])),
+ ),
+ ],
+ );
+ let StoredV2KnnProjectionResult::Projected(projected) =
+ decode_stored_v2_knn_projection(&wrong_identity, "embedding", None).unwrap()
+ else {
+ panic!("wrong identity cells are explicit None rows");
+ };
+ assert_eq!(projected.ids, vec![Some("ok".into()), None]);
+ assert_eq!(projected.seq_nos, vec![Some(0), None]);
+ }
+
+ #[test]
+ fn v2_knn_projection_rejects_reserved_or_colliding_role_names() {
+ let (_, encoded) = projection_fixture();
+ for (vector, chunks) in [
+ ("__id", None),
+ ("__seq_no", None),
+ ("embedding", Some("__id")),
+ ("embedding", Some("__seq_no")),
+ ("embedding", Some("embedding")),
+ ] {
+ assert_eq!(
+ decode_stored_v2_knn_projection(&encoded, vector, chunks).unwrap(),
+ StoredV2KnnProjectionResult::UnsupportedVectorShape
+ );
+ }
+ }
+
+ #[test]
+ fn v2_projection_enforces_dependency_depth_boundary() {
+ let chain = |edges: usize| {
+ let mut owned: Vec<(String, u8, Vec<u8>)> = (0..edges)
+ .map(|index| {
+ (
+ format!("c{index}"),
+ ColCodec::CrossDep as u8,
+ valid_cross_dep((index + 1) as u32, index as i64),
+ )
+ })
+ .collect();
+ owned.push((
+ format!("c{edges}"),
+ ColCodec::Constant as u8,
+ br#""base""#.to_vec(),
+ ));
+ let borrowed: Vec<_> = owned
+ .iter()
+ .map(|(name, codec, payload)| (name.as_str(), *codec, payload.clone()))
+ .collect();
+ handcrafted_v2(1, &borrowed)
+ };
+
+ let at_limit = chain(256);
+ assert!(
+ decode_stored_v2_projection(&at_limit, &["c0"]).is_ok(),
+ "256 dependency edges are supported"
+ );
+ let over_limit = chain(257);
+ let error = decode_stored_v2_projection(&over_limit, &["c0"]).unwrap_err();
+ assert!(error.to_string().contains("depth exceeds 256"), "{error}");
+ }
+
+ #[test]
+ fn v2_projection_validates_framing_and_preserves_legacy_fallback() {
+ let (_, encoded) = projection_fixture();
+ let mut trailing = encoded.clone();
+ trailing.push(0);
+ assert!(decode_stored_v2_projection(&trailing, &["__id"]).is_err());
+
+ let legacy = encode_stored_lz4(br#"[{"_id":"legacy"}]"#);
+ assert_eq!(
+ decode_stored_v2_projection(&legacy, &["__id"]).unwrap(),
+ StoredV2ProjectionResult::NotV2
+ );
+ }
+
#[test]
fn v2_roundtrip_nginx_like() {
// Synthesise 256 nginx-like docs with strong determinism: URL → status, URL → bytes.
diff --git a/engine/crates/xerj-storage/src/stored_codec/row_hydration.rs b/engine/crates/xerj-storage/src/stored_codec/row_hydration.rs
index 49fabae54..2bc5b9a9a 100644
--- a/engine/crates/xerj-storage/src/stored_codec/row_hydration.rs
+++ b/engine/crates/xerj-storage/src/stored_codec/row_hydration.rs
@@ -1,5 +1,6 @@
use super::*;
use serde::de::Deserializer as _;
+use std::cell::Cell;
use std::collections::{HashMap, HashSet};
/// Logical work performed by row-selective hydration.
@@ -38,9 +39,74 @@ pub enum StoredV2RowHydrationResult {
},
}
+type IdentityColumns = (usize, Vec<serde_json::Value>, Vec<serde_json::Value>);
+
+pub(super) fn decode_v2_identity_columns_controlled(
+ bytes: &[u8],
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<StoredDecodeRun<Option<IdentityColumns>>> {
+ let directory = parse_v2_directory(&bytes[4..])?;
+ let id_index = directory
+ .columns
+ .iter()
+ .position(|column| column.name == "__id")
+ .ok_or_else(|| StorageError::Other(anyhow::anyhow!("v2 missing __id column")))?;
+ let seq_index = directory
+ .columns
+ .iter()
+ .position(|column| column.name == "__seq_no")
+ .ok_or_else(|| StorageError::Other(anyhow::anyhow!("v2 missing __seq_no column")))?;
+ let selected: Vec<usize> = (0..directory.num_docs).collect();
+ let mut stats = StoredV2RowHydrationStats::default();
+ let mut dict_ids = HashMap::new();
+ let mut decode =
+ |index| -> Result<std::result::Result<Vec<serde_json::Value>, Option<String>>> {
+ if decode_cancelled(checkpoint, StoredDecodePhase::BeforeColumn, index, 0) {
+ return Ok(Err(None));
+ }
+ let result = select_column_rows(
+ index,
+ &directory,
+ &selected,
+ &mut stats,
+ &mut dict_ids,
+ checkpoint,
+ )?;
+ if result.is_ok()
+ && decode_cancelled(
+ checkpoint,
+ StoredDecodePhase::AfterColumn,
+ index,
+ directory.num_docs,
+ )
+ {
+ return Ok(Err(None));
+ }
+ Ok(result)
+ };
+ let ids = match decode(id_index)? {
+ Ok(values) => values,
+ Err(None) => return Ok(StoredDecodeRun::Cancelled),
+ Err(Some(_)) => return Ok(StoredDecodeRun::Complete(None)),
+ };
+ let seq_nos = match decode(seq_index)? {
+ Ok(values) => values,
+ Err(None) => return Ok(StoredDecodeRun::Cancelled),
+ Err(Some(_)) => return Ok(StoredDecodeRun::Complete(None)),
+ };
+ Ok(StoredDecodeRun::Complete(Some((
+ directory.num_docs,
+ ids,
+ seq_nos,
+ ))))
+}
+
struct SelectedRowsVisitor<'a> {
selected: &'a [usize],
expected_rows: usize,
+ column_index: usize,
+ checkpoint: &'a mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+ cancelled: &'a Cell<bool>,
}
impl<'de> serde::de::Visitor<'de> for SelectedRowsVisitor<'_> {
@@ -69,6 +135,18 @@ impl<'de> serde::de::Visitor<'de> for SelectedRowsVisitor<'_> {
.next_element::<serde::de::IgnoredAny>()?
.ok_or_else(|| serde::de::Error::custom("stored column ended early"))?;
}
+ let processed = row + 1;
+ if processed % STORED_DECODE_CHECK_INTERVAL == 0
+ && (self.checkpoint)(StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index: self.column_index,
+ rows_processed: processed,
+ })
+ .is_break()
+ {
+ self.cancelled.set(true);
+ return Err(serde::de::Error::custom("stored decode cancelled"));
+ }
}
if sequence.next_element::<serde::de::IgnoredAny>()?.is_some() {
return Err(serde::de::Error::custom(
@@ -84,18 +162,28 @@ fn select_json_rows<R: std::io::Read>(
selected: &[usize],
expected_rows: usize,
context: &str,
-) -> Result<Vec<serde_json::Value>> {
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Vec<serde_json::Value>, ()>> {
+ let cancelled = Cell::new(false);
let mut deserializer = serde_json::Deserializer::from_reader(reader);
- let values = deserializer
- .deserialize_seq(SelectedRowsVisitor {
- selected,
- expected_rows,
- })
- .map_err(|error| StorageError::Other(anyhow::anyhow!("{context}: {error}")))?;
+ let values = match deserializer.deserialize_seq(SelectedRowsVisitor {
+ selected,
+ expected_rows,
+ column_index,
+ checkpoint,
+ cancelled: &cancelled,
+ }) {
+ Ok(values) => values,
+ Err(_) if cancelled.get() => return Ok(Err(())),
+ Err(error) => {
+ return Err(StorageError::Other(anyhow::anyhow!("{context}: {error}")));
+ }
+ };
deserializer
.end()
.map_err(|error| StorageError::Other(anyhow::anyhow!("{context}: {error}")))?;
- Ok(values)
+ Ok(Ok(values))
}
fn unpack_id(packed: &[u8], bit_width: u8, ordinal: usize) -> Option<u32> {
@@ -122,7 +210,13 @@ struct SelectedDict {
decompressed_bytes: usize,
}
-fn decode_dict_rows(payload: &[u8], selected: &[usize], num_docs: usize) -> Result<SelectedDict> {
+fn decode_dict_rows(
+ payload: &[u8],
+ selected: &[usize],
+ num_docs: usize,
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<SelectedDict, ()>> {
let mut cursor = Cursor::new(payload);
let dict_count = cursor
.read_u32::<LittleEndian>()
@@ -196,6 +290,16 @@ fn decode_dict_rows(payload: &[u8], selected: &[usize], num_docs: usize) -> Resu
"dict id {id} outside dictionary"
)));
}
+ if (ordinal + 1) % STORED_DECODE_CHECK_INTERVAL == 0
+ && checkpoint(StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index,
+ rows_processed: ordinal + 1,
+ })
+ .is_break()
+ {
+ return Ok(Err(()));
+ }
}
let ids: Vec<u32> = selected
.iter()
@@ -214,7 +318,17 @@ fn decode_dict_rows(payload: &[u8], selected: &[usize], num_docs: usize) -> Resu
needed.dedup();
let decoder = zstd::stream::read::Decoder::new(&payload[dict_start..dict_end])
.map_err(|error| StorageError::Other(anyhow::anyhow!("dict zstd: {error}")))?;
- let entries = select_json_rows(decoder, &needed, dict_count, "dict json")?;
+ let entries = match select_json_rows(
+ decoder,
+ &needed,
+ dict_count,
+ "dict json",
+ column_index,
+ checkpoint,
+ )? {
+ Ok(entries) => entries,
+ Err(()) => return Ok(Err(())),
+ };
let entries: HashMap<usize, serde_json::Value> = needed.iter().copied().zip(entries).collect();
let values = ids
.iter()
@@ -228,12 +342,12 @@ fn decode_dict_rows(payload: &[u8], selected: &[usize], num_docs: usize) -> Resu
}
})
.collect::<Result<_>>()?;
- Ok(SelectedDict {
+ Ok(Ok(SelectedDict {
values,
ids,
selected_entries: needed.len(),
decompressed_bytes: packed.len(),
- })
+ }))
}
fn decode_cross_dep_rows(
@@ -242,7 +356,9 @@ fn decode_cross_dep_rows(
source_ids: &[u32],
num_docs: usize,
stats: &mut StoredV2RowHydrationStats,
-) -> Result<Vec<serde_json::Value>> {
+ column_index: usize,
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Vec<serde_json::Value>, ()>> {
let body = decode_cross_dep_body(column.payload)?;
stats.decompressed_buffer_bytes += body.len();
let mut cursor = Cursor::new(body.as_slice());
@@ -285,13 +401,23 @@ fn decode_cross_dep_rows(
exceptions.insert(ordinal, value);
}
previous = ordinal;
+ if (exception_index + 1) % STORED_DECODE_CHECK_INTERVAL == 0
+ && checkpoint(StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index,
+ rows_processed: exception_index + 1,
+ })
+ .is_break()
+ {
+ return Ok(Err(()));
+ }
}
if position != body.len() {
return Err(StorageError::Other(anyhow::anyhow!(
"cross_dep trailing exception bytes"
)));
}
- Ok(selected
+ Ok(Ok(selected
.iter()
.zip(source_ids)
.map(|(ordinal, source_id)| {
@@ -310,7 +436,7 @@ fn decode_cross_dep_rows(
}
}
})
- .collect())
+ .collect()))
}
fn select_column_rows(
@@ -319,21 +445,42 @@ fn select_column_rows(
selected: &[usize],
stats: &mut StoredV2RowHydrationStats,
dict_ids: &mut HashMap<usize, Vec<u32>>,
-) -> Result<std::result::Result<Vec<serde_json::Value>, String>> {
+ checkpoint: &mut dyn FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+) -> Result<std::result::Result<Vec<serde_json::Value>, Option<String>>> {
let column = &directory.columns[column_index];
let values = match column.codec {
ColCodec::RawJson => {
stats.encoded_rows_visited += directory.num_docs;
let decoder = zstd::stream::read::Decoder::new(column.payload)
.map_err(|error| StorageError::Other(anyhow::anyhow!("raw zstd: {error}")))?;
- select_json_rows(decoder, selected, directory.num_docs, "raw json")?
+ match select_json_rows(
+ decoder,
+ selected,
+ directory.num_docs,
+ "raw json",
+ column_index,
+ checkpoint,
+ )? {
+ Ok(values) => values,
+ Err(()) => return Ok(Err(None)),
+ }
}
ColCodec::Lz4Json => {
let raw = lz4_flex::decompress_size_prepended(column.payload)
.map_err(|error| StorageError::Other(anyhow::anyhow!("lz4 decode: {error}")))?;
stats.decompressed_buffer_bytes += raw.len();
stats.encoded_rows_visited += directory.num_docs;
- select_json_rows(raw.as_slice(), selected, directory.num_docs, "lz4 json")?
+ match select_json_rows(
+ raw.as_slice(),
+ selected,
+ directory.num_docs,
+ "lz4 json",
+ column_index,
+ checkpoint,
+ )? {
+ Ok(values) => values,
+ Err(()) => return Ok(Err(None)),
+ }
}
ColCodec::Constant => {
let value: serde_json::Value = serde_json::from_slice(column.payload)
@@ -341,7 +488,16 @@ fn select_column_rows(
vec![value; selected.len()]
}
ColCodec::DictBitpack => {
- let decoded = decode_dict_rows(column.payload, selected, directory.num_docs)?;
+ let decoded = match decode_dict_rows(
+ column.payload,
+ selected,
+ directory.num_docs,
+ column_index,
+ checkpoint,
+ )? {
+ Ok(decoded) => decoded,
+ Err(()) => return Ok(Err(None)),
+ };
stats.selected_dictionary_entries += decoded.selected_entries;
stats.decompressed_buffer_bytes += decoded.decompressed_bytes;
dict_ids.insert(column_index, decoded.ids);
@@ -361,28 +517,47 @@ fn select_column_rows(
// validate this column's complete body and exception stream
// before asking the caller to use the compatibility path.
let placeholder_source_ids = vec![0; selected.len()];
- decode_cross_dep_rows(
+ match decode_cross_dep_rows(
column,
selected,
&placeholder_source_ids,
directory.num_docs,
stats,
- )?;
- return Ok(Err(column.name.to_string()));
+ column_index,
+ checkpoint,
+ )? {
+ Ok(_) => {}
+ Err(()) => return Ok(Err(None)),
+ }
+ return Ok(Err(Some(column.name.to_string())));
}
if let std::collections::hash_map::Entry::Vacant(entry) = dict_ids.entry(source_index) {
- let decoded = decode_dict_rows(source.payload, selected, directory.num_docs)?;
+ let decoded = match decode_dict_rows(
+ source.payload,
+ selected,
+ directory.num_docs,
+ source_index,
+ checkpoint,
+ )? {
+ Ok(decoded) => decoded,
+ Err(()) => return Ok(Err(None)),
+ };
stats.selected_dictionary_entries += decoded.selected_entries;
stats.decompressed_buffer_bytes += decoded.decompressed_bytes;
entry.insert(decoded.ids);
}
- decode_cross_dep_rows(
+ match decode_cross_dep_rows(
column,
selected,
&dict_ids[&source_index],
directory.num_docs,
stats,
- )?
+ column_index,
+ checkpoint,
+ )? {
+ Ok(values) => values,
+ Err(()) => return Ok(Err(None)),
+ }
}
};
stats.selected_json_values += values.len();
@@ -394,8 +569,26 @@ pub fn decode_stored_v2_rows(
bytes: &[u8],
ordinals: &[usize],
) -> Result<StoredV2RowHydrationResult> {
+ match decode_stored_v2_rows_controlled(
+ bytes,
+ ordinals,
+ |_| std::ops::ControlFlow::Continue(()),
+ )? {
+ StoredDecodeRun::Complete(result) => Ok(result),
+ StoredDecodeRun::Cancelled => unreachable!("non-cancelling compatibility wrapper"),
+ }
+}
+
+pub fn decode_stored_v2_rows_controlled<F>(
+ bytes: &[u8],
+ ordinals: &[usize],
+ mut checkpoint: F,
+) -> Result<StoredDecodeRun<StoredV2RowHydrationResult>>
+where
+ F: FnMut(StoredDecodeCheckpoint) -> std::ops::ControlFlow<()>,
+{
if bytes.len() < 4 || &bytes[..4] != STORED_V2_MAGIC {
- return Ok(StoredV2RowHydrationResult::NotV2);
+ return Ok(StoredDecodeRun::Complete(StoredV2RowHydrationResult::NotV2));
}
let directory = parse_v2_directory(&bytes[4..])?;
let id_index = directory
@@ -420,20 +613,43 @@ pub fn decode_stored_v2_rows(
)));
}
if selected.is_empty() {
- return Ok(StoredV2RowHydrationResult::Hydrated {
- rows: Vec::new(),
- stats: StoredV2RowHydrationStats::default(),
- });
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2RowHydrationResult::Hydrated {
+ rows: Vec::new(),
+ stats: StoredV2RowHydrationStats::default(),
+ },
+ ));
}
let mut stats = StoredV2RowHydrationStats::default();
let mut columns = Vec::with_capacity(directory.columns.len());
let mut dict_ids = HashMap::new();
for index in 0..directory.columns.len() {
- match select_column_rows(index, &directory, &selected, &mut stats, &mut dict_ids)? {
+ if decode_cancelled(&mut checkpoint, StoredDecodePhase::BeforeColumn, index, 0) {
+ return Ok(StoredDecodeRun::Cancelled);
+ }
+ match select_column_rows(
+ index,
+ &directory,
+ &selected,
+ &mut stats,
+ &mut dict_ids,
+ &mut checkpoint,
+ )? {
Ok(values) => columns.push(values),
- Err(column) => {
- return Ok(StoredV2RowHydrationResult::UnsupportedDependencyShape { column });
+ Err(Some(column)) => {
+ return Ok(StoredDecodeRun::Complete(
+ StoredV2RowHydrationResult::UnsupportedDependencyShape { column },
+ ));
}
+ Err(None) => return Ok(StoredDecodeRun::Cancelled),
+ }
+ if decode_cancelled(
+ &mut checkpoint,
+ StoredDecodePhase::AfterColumn,
+ index,
+ directory.num_docs,
+ ) {
+ return Ok(StoredDecodeRun::Cancelled);
}
}
let mut rows = Vec::with_capacity(selected.len());
@@ -457,7 +673,9 @@ pub fn decode_stored_v2_rows(
source,
});
}
- Ok(StoredV2RowHydrationResult::Hydrated { rows, stats })
+ Ok(StoredDecodeRun::Complete(
+ StoredV2RowHydrationResult::Hydrated { rows, stats },
+ ))
}
#[cfg(test)]
@@ -665,6 +883,123 @@ mod tests {
assert_eq!(selected(small), selected(large));
}
+ #[test]
+ fn controlled_hydration_has_deterministic_order_and_distinct_cancellation() {
+ let encoded = fixture(256, ColCodec::RawJson);
+ let mut observed = Vec::new();
+ let run = decode_stored_v2_rows_controlled(&encoded, &[0, 7], |point| {
+ observed.push(point);
+ if point.phase == StoredDecodePhase::Rows && point.rows_processed == 128 {
+ std::ops::ControlFlow::Break(())
+ } else {
+ std::ops::ControlFlow::Continue(())
+ }
+ })
+ .unwrap();
+ assert_eq!(run, StoredDecodeRun::Cancelled);
+ assert_eq!(
+ observed[0],
+ StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::BeforeColumn,
+ column_index: 0,
+ rows_processed: 0,
+ }
+ );
+ assert_eq!(
+ observed[1],
+ StoredDecodeCheckpoint {
+ phase: StoredDecodePhase::Rows,
+ column_index: 0,
+ rows_processed: 128,
+ }
+ );
+
+ let complete = decode_stored_v2_rows_controlled(&encoded, &[0, 7], |_| {
+ std::ops::ControlFlow::Continue(())
+ })
+ .unwrap();
+ assert_eq!(
+ complete,
+ StoredDecodeRun::Complete(decode_stored_v2_rows(&encoded, &[0, 7]).unwrap())
+ );
+ }
+
+ #[test]
+ fn controlled_hydration_cancellation_precedes_unvisited_corruption() {
+ let mut encoded = fixture(256, ColCodec::RawJson);
+ let (offset, payload_len) = {
+ let directory = parse_v2_directory(&encoded[4..]).unwrap();
+ let last = directory.columns.last().unwrap();
+ (
+ last.payload.as_ptr() as usize - encoded.as_ptr() as usize,
+ last.payload.len(),
+ )
+ };
+ encoded[offset + payload_len / 2] ^= 0xff;
+
+ assert_eq!(
+ decode_stored_v2_rows_controlled(&encoded, &[0], |_| {
+ std::ops::ControlFlow::Break(())
+ })
+ .unwrap(),
+ StoredDecodeRun::Cancelled
+ );
+ assert!(decode_stored_v2_rows_controlled(&encoded, &[0], |_| {
+ std::ops::ControlFlow::Continue(())
+ })
+ .is_err());
+ }
+
+ #[test]
+ fn controlled_hydration_stops_before_malformed_row_129() {
+ let mut json = String::from("[");
+ for row in 0..128 {
+ if row != 0 {
+ json.push(',');
+ }
+ json.push_str(&row.to_string());
+ }
+ json.push_str(",row_129_is_invalid]");
+ let malformed = zstd::encode_all(Cursor::new(json.as_bytes()), STORED_ZSTD_LEVEL).unwrap();
+ let encoded = assemble(
+ 256,
+ &[
+ (
+ "__id",
+ ColCodec::Constant,
+ serde_json::to_vec(&json!("id")).unwrap(),
+ ),
+ (
+ "__seq_no",
+ ColCodec::Constant,
+ serde_json::to_vec(&json!(1)).unwrap(),
+ ),
+ ("bad", ColCodec::RawJson, malformed),
+ ],
+ );
+ assert_eq!(
+ decode_stored_v2_rows_controlled(&encoded, &[0], |point| {
+ if point.column_index == 2
+ && point.phase == StoredDecodePhase::Rows
+ && point.rows_processed == 128
+ {
+ std::ops::ControlFlow::Break(())
+ } else {
+ std::ops::ControlFlow::Continue(())
+ }
+ })
+ .unwrap(),
+ StoredDecodeRun::Cancelled
+ );
+ assert!(
+ decode_stored_v2_rows_controlled(&encoded, &[0], |_| {
+ std::ops::ControlFlow::Continue(())
+ })
+ .is_err(),
+ "without cancellation the parser must consume malformed row 129"
+ );
+ }
+
#[test]
fn malformed_framing_and_unsupported_dependency_are_explicit() {
let encoded = fixture(4, ColCodec::RawJson);