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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
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.rsindex 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.rsindex 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) -> Resuneeded.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);