{"record":{"id":"a8b984b585ef277f","repo":"astrid-runtime/astrid","slug":"message-a8b984","errorCode":null,"errorMessage":"message","messagePattern":"message","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-storage/src/volume/hosted/mod.rs","lineNumber":592,"sourceCode":"    })?))\n}\n\nfn read_metadata_region(bytes: &[u8], cursor: &mut usize) -> io::Result<VolumeRegion> {\n    let length = usize::from(read_u16(bytes, cursor)?);\n    let end = cursor\n        .checked_add(length)\n        .ok_or_else(|| invalid_transition(\"metadata region name length overflow\"))?;\n    let name = bytes\n        .get(*cursor..end)\n        .ok_or_else(|| invalid_transition(\"truncated metadata region name\"))?;\n    *cursor = end;\n    let name = std::str::from_utf8(name)\n        .map_err(|_| invalid_transition(\"metadata region name is not UTF-8\"))?;\n    VolumeRegion::new(name.to_owned())\n}\n\nfn invalid_transition(message: &'static str) -> io::Error {\n    io::Error::new(io::ErrorKind::InvalidData, message)\n}\n\nfn overlapping_extents(\n    region_state: &RegionState,\n    offset: u64,\n    read_end: u64,\n) -> Vec<(u64, Extent)> {\n    let start_key = region_state\n        .extents\n        .range(..=offset)\n        .next_back()\n        .and_then(|(start, extent)| (extent.logical_end > offset).then_some(*start))\n        .unwrap_or(offset);\n    let mut overlaps = Vec::new();\n    for (start, extent) in region_state.extents.range(start_key..read_end) {\n        #[cfg(test)]\n        EXTENT_VISITS.with(|count| count.set(count.get().saturating_add(1)));\n        if extent.logical_end > offset {","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage/src/volume/hosted/mod.rs#L574-L610","documentation":"invalid_transition is the shared constructor for InvalidData errors raised while decoding or applying volume metadata/footer structures. The displayed message \"message\" is the function's parameter name; the real message comes from each call site (e.g. \"metadata region name is not UTF-8\"). It signals that the on-disk structure is inconsistent with the expected format at that point.","triggerScenarios":"Any of its callers hit malformed data: decode_metadata_mutations reading bad kind/length fields, read_u16 or read_metadata_region hitting EOF mid-field, a region name failing UTF-8 validation, encode_region_snapshot/write_footer invariant failures, or apply_metadata_mutations encountering an impossible region transition.","commonSituations":"Disk corruption or torn writes in the volume footer/metadata area; a volume written by a different (incompatible) format version; manually editing or truncating the volume file; decoding at a stale offset after an interrupted commit.","solutions":["Read the real message inside the error to identify which structural check failed.","Run recovery (recover_container) so the volume resynchronizes to the last valid commit.","Confirm the writer and reader use compatible astrid-storage versions/formats.","Restore the volume from backup if the footer/metadata region is physically corrupt."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match decode_metadata(file, offset) {\n    Err(e) if e.kind() == io::ErrorKind::InvalidData => {\n        eprintln!(\"metadata structure invalid: {e}; running recovery\");\n        recover_container(file)?;\n    }\n    other => other,\n}","preventionTips":["Run recovery on open rather than hand-decoding metadata regions.","Never manually edit or truncate volume files.","Sync cleanly on shutdown so the footer is not torn mid-write.","Keep format versions compatible between writer and reader."],"tags":["storage","corruption","decoding","metadata"],"backgroundTag":"invalid-state-transition","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}