{"record":{"id":"ba3a9fccd294422c","repo":"astrid-runtime/astrid","slug":"unexpected-entry-in-released-legacy-surrealkv-sour","errorCode":null,"errorMessage":"unexpected entry in released legacy SurrealKV source: {}","messagePattern":"unexpected entry in released legacy SurrealKV source: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-core/src/dirs_layout_retirement.rs","lineNumber":177,"sourceCode":"        },\n        [directory, name] if directory.as_os_str() == \"wal\" && is_file => {\n            is_numbered_legacy_file(name.as_os_str(), b\".wal\")\n        },\n        [directory, name] if directory.as_os_str() == \"sstables\" && is_file => {\n            is_numbered_legacy_file(name.as_os_str(), b\".sst\")\n        },\n        [directory, name] if directory.as_os_str() == \"vlog\" && is_file => {\n            is_numbered_legacy_file(name.as_os_str(), b\".vlog\")\n        },\n        [directory, name]\n            if directory.as_os_str() == \"versioned_index\" && name.as_os_str() == \"index.bpt\" =>\n        {\n            is_file\n        },\n        _ => false,\n    };\n    if !valid {\n        return Err(io::Error::new(\n            io::ErrorKind::InvalidData,\n            format!(\n                \"unexpected entry in released legacy SurrealKV source: {}\",\n                relative.display()\n            ),\n        ));\n    }\n    Ok(())\n}\n\nfn is_numbered_legacy_file(name: &std::ffi::OsStr, extension: &[u8]) -> bool {\n    let bytes = name.as_encoded_bytes();\n    bytes.split_at_checked(20).is_some_and(|(digits, suffix)| {\n        digits.iter().all(u8::is_ascii_digit) && suffix == extension\n    })\n}\n\npub(super) fn retire_legacy_source_tree(path: &Path) -> io::Result<()> {","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-core/src/dirs_layout_retirement.rs#L159-L195","documentation":"validate_legacy_surrealkv_entry whitelists exactly which entries may appear in a released legacy SurrealKV source directory. Any entry failing that whitelist check (e.g. unexpected regular file, wrong file type at a known name) causes InvalidData with the relative path. This guard runs before deletion so retirement never destroys unrecognized data.","triggerScenarios":"Calling retire_legacy_source_tree on a legacy SurrealKV dir whose contents include anything beyond the expected released layout (extra files, missing expected files, unexpected file/dir type at a known path).","commonSituations":"User data or logs were written into the SurrealKV directory; a partially applied migration left extra artifacts; an older/newer version created files the validator doesn't know.","solutions":["Move the unexpected entry out of the legacy SurrealKV directory (archive it elsewhere), then retry retirement.","Compare the directory against the expected released layout and remove or rename stray artifacts.","If the entry is legitimate new-version data, abort retirement — the validator indicates this tree is not the legacy shape it expects."],"exampleFix":"// before\nlegacy/surrealkv/{data/, extra.log}\n// after\nmv legacy/surrealkv/extra.log ~/archive/extra.log","handlingStrategy":"validation","validationCode":"fn assert_known_layout(dir: &Path, allowed: &[&str]) -> io::Result<()> {\n    for e in std::fs::read_dir(dir)? {\n        let name = e?.file_name().to_string_lossy().into_owned();\n        if !allowed.contains(&name.as_str()) {\n            return Err(io::Error::new(io::ErrorKind::InvalidData, format!(\"unexpected: {name}\")));\n        }\n    }\n    Ok(())\n}","typeGuard":"fn is_whitelisted(rel: &Path, allowed: &[&str]) -> bool {\n    rel.to_str().map(|s| allowed.contains(&s)).unwrap_or(false)\n}","tryCatchPattern":"match retire_legacy_source_tree(&path, dev) {\n    Err(e) if e.to_string().contains(\"unexpected entry\") => archive_stray_entries(&path)?,\n    other => other?,\n}","preventionTips":["Keep SurrealKV state dirs free of user files and logs","Archive unknown files before upgrading/migrating","Diff directory contents against the documented released layout before retirement"],"tags":["rust","validation","filesystem"],"backgroundTag":"schema-validation-failed","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}