{"record":{"id":"e957f8103187d3d1","repo":"astrid-runtime/astrid","slug":"volume-backend-does-not-provide-physical-reclamati","errorCode":null,"errorMessage":"volume backend does not provide physical reclamation","messagePattern":"volume backend does not provide physical reclamation","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"warning","filePath":"crates/astrid-storage/src/volume.rs","lineNumber":234,"sourceCode":"    /// Returns an underlying media-capacity error.\n    fn available_space(&self) -> io::Result<Option<u64>> {\n        Ok(None)\n    }\n\n    /// Physically reclaim obsolete container extents after a logical rewrite.\n    ///\n    /// The operation is invoked only after the replacement namespace and its\n    /// evidence are durable. Implementations must use their own crash-safe\n    /// media transaction; the default rejects backends that cannot provide a\n    /// reclaim boundary, so callers never mistake logical reachability for\n    /// physical reclamation.\n    ///\n    /// # Errors\n    ///\n    /// Returns [`io::ErrorKind::Unsupported`] when the backend has no safe\n    /// reclaim primitive, or an underlying media error.\n    fn reclaim(&self) -> io::Result<()> {\n        Err(io::Error::new(\n            io::ErrorKind::Unsupported,\n            \"volume backend does not provide physical reclamation\",\n        ))\n    }\n\n    /// Flush all preceding volume mutations to durable media.\n    ///\n    /// # Errors\n    ///\n    /// Returns an underlying durability-barrier error.\n    fn sync(&self) -> io::Result<()>;\n}\n\n/// Seekable handle to one region in an [`AstridVolume`].\n#[derive(Clone)]\npub struct VolumeFile {\n    volume: Arc<dyn AstridVolume>,\n    region: VolumeRegion,","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-storage/src/volume.rs#L216-L252","documentation":"The default Volume trait reclaim() implementation returns io::ErrorKind::Unsupported because the backend has no safe physical reclamation primitive (e.g. TRIM/deallocate). Only backends that explicitly override reclaim() can physically free space; calling it on a default backend always fails.","triggerScenarios":"Calling volume.reclaim() on a backend that does not override the trait default, e.g. HostedFileVolume or any custom backend implementing only the required methods.","commonSituations":"Building a space-reclamation/maintenance routine that assumes all backends support TRIM-like operations; portable code calling reclaim() without checking backend capability.","solutions":["Check backend capability before calling and skip reclaim gracefully when Unsupported is returned","Match on err.kind() == io::ErrorKind::Unsupported and treat as a no-op","Use a backend that overrides reclaim() with a real primitive","Document/log that reclamation is unavailable for this backend instead of failing the maintenance job"],"exampleFix":"// before\nvolume.reclaim()?;\n// after\nif let Err(e) = volume.reclaim() {\n    if e.kind() != std::io::ErrorKind::Unsupported { return Err(e); } // skip: backend can't reclaim\n}","handlingStrategy":"fallback","validationCode":"// No pre-check API; guard by kind after the call:\nfn reclaim_if_supported(v: &dyn Volume) -> io::Result<bool> {\n    match v.reclaim() { Ok(()) => Ok(true), Err(e) if e.kind() == io::ErrorKind::Unsupported => Ok(false), Err(e) => Err(e) }\n}","typeGuard":"fn supports_reclaim(v: &dyn Volume) -> bool { v.reclaim().map(|_| true).or_else(|e| if e.kind() == io::ErrorKind::Unsupported { Ok(false) } else { Err(e) }).unwrap_or(true) }","tryCatchPattern":"match volume.reclaim() {\n    Err(e) if e.kind() == std::io::ErrorKind::Unsupported => log::info!(\"backend cannot reclaim; skipping\"),\n    other => other?,\n}","preventionTips":["Treat Unsupported as a capability signal, not a failure","Wrap reclaim in a helper that returns Option/bool","Document per-backend reclaim support in your infra code","Only call reclaim in maintenance jobs where skipping is safe"],"tags":["unsupported-operation","storage","io"],"backgroundTag":"unsupported-operation","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"}