a representation record must cover at least one logical…

Error message

a representation record must cover at least one logical chunk

What it means

add_record (backing add_whole_record and add_chunk_record) rejects representation records that claim to cover zero logical chunks. Chunk-count accounting assumes every recorded representation contributes at least one chunk, otherwise totals and ratios would be meaningless.

Solutions

Ensure the caller only records representations that produced >= 1 logical chunk.
Skip or special-case empty inputs before calling add_*_record.
Fix the upstream chunker so it emits at least one chunk for non-empty input.

Example fix

// before
metrics.add_chunk_record(bytes, chunks.len() as u64);
// after
if !chunks.is_empty() {
    metrics.add_chunk_record(bytes, chunks.len() as u64);
}

Defensive patterns

Strategy: validation

Validate before calling

if logical_chunks == 0 { skip_record(); } else { metrics.add_chunk_record(bytes, logical_chunks)?; }

Try / catch

match metrics.add_chunk_record(bytes, n) {
    Err(e) if e.to_string().contains("at least one logical chunk") => eprintln!("empty representation skipped"),
    Err(e) => return Err(e),
    Ok(()) => {},
}

Prevention

Skip empty inputs before recording
Assert chunkers emit >=1 chunk for non-empty input
Test custom chunkers against empty and single-byte files

When it happens

Trigger: Calling add_chunk_record(bytes, 0) or add_whole_record(bytes, 0) — e.g. when upstream chunk counting returned an empty iterator or a counter was never incremented.

Common situations: Processing an empty file and passing 0 chunks instead of skipping the record; a bug in a custom chunker producing no chunks; miswired counters in calling code.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/892a133af4e458af. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-storage-chunker-evidence/src/metrics.rs:94

                if *entry.get() != length {
                    bail!("BLAKE3 evidence collision with inconsistent file lengths");
                }
            },
        }
        Ok(())
    }

    pub fn add_whole_record(&mut self, bytes: &[u8]) -> Result<()> {
        self.add_record(bytes, 1, false)
    }

    pub fn add_chunk_record(&mut self, bytes: &[u8], logical_chunks: u64) -> Result<()> {
        self.add_record(bytes, logical_chunks, true)
    }

    fn add_record(&mut self, bytes: &[u8], logical_chunks: u64, cdc: bool) -> Result<()> {
        if logical_chunks == 0 {
            bail!("a representation record must cover at least one logical chunk");
        }
        let length = u64::try_from(bytes.len())?;
        self.total_chunks = checked_add(self.total_chunks, logical_chunks, "chunk count")?;
        self.representation_records = checked_add(
            self.representation_records,
            1,
            "representation record count",
        )?;
        self.chunk_lengths.push((length, logical_chunks));
        if cdc {
            self.cdc_chunk_lengths.push((length, logical_chunks));
        }
        insert_identity(&mut self.chunks, bytes, &mut self.unique_chunk_bytes)
    }

    pub fn finish(mut self, elapsed: Duration) -> Result<Measurements> {
        self.chunk_lengths.sort_unstable();
        self.cdc_chunk_lengths.sort_unstable();

View on GitHub (pinned to affd8760f4)