Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(core): refuse non-portable page paths at write time
AkitaOnRails3e72462816f8
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1b227ea0..57e3907e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Fixed+- Page paths that cannot be materialised on every supported platform are now+ refused at write time instead of failing late (#462). `PagePath` accepted+ DOS device names (`CON.md`, `aux.md`), components ending in a dot or space,+ the characters `< > : " | ? *`, and control characters. On native Windows+ some of those failed with a generic HTTP 500, while others were written+ successfully but could not be checkpointed by libgit2 or deleted through the+ normal API — silent partial state, which is worse than a clean rejection.+ The check runs in `Wiki::write_page`, the single funnel every page creation+ passes through, and returns an error naming the offending component and the+ reason. It is deliberately **not** in `PagePath::new`: persisted rows are+ reconstructed through that constructor on every read, so tightening it would+ make an already-stored non-portable page unreadable and break the whole+ listing it appears in. The rule is identical on every platform, so a wiki+ authored on Linux stays usable on Windows.- Made non-FTS search hits describe the page instead of repeating itsheading. Only the FTS5 path built a real excerpt (`snippet(pages_fts, ...)`,centred on the matched terms); the vector, entity-match, graph-neighbour anddiff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rsindex a977c02a..5b8e110d 100644--- a/crates/ai-memory-core/src/ids.rs+++ b/crates/ai-memory-core/src/ids.rs@@ -106,6 +106,33 @@ impl PagePath {////// # Errors/// Returns [`MemoryError::InvalidPagePath`] when the input is empty or+ /// Reject a path that cannot be materialised and checkpointed on every+ /// supported platform.+ ///+ /// Deliberately **not** part of [`PagePath::new`]. Persisted rows are+ /// reconstructed through that constructor on every read+ /// (`reader.rs` does so in the recency, search, vector and graph+ /// queries), so tightening it would make any already-stored+ /// non-portable page unreadable — and because those are list queries,+ /// one such page would break a whole listing rather than just itself.+ /// The rule therefore applies where a *new* path enters the system.+ ///+ /// The rule is the same on every platform on purpose. A wiki authored+ /// on Linux is expected to be usable on Windows by the same release;+ /// making the check platform-conditional would let a Linux session+ /// create pages a Windows session cannot read, which is the defect+ /// being fixed rather than a fix for it (#462).+ ///+ /// # Errors+ /// Returns [`MemoryError::InvalidPagePath`] naming the offending+ /// component and the reason.+ pub fn ensure_portable(&self) -> Result<(), MemoryError> {+ for component in self.as_str().split('/') {+ ensure_portable_component(component, self.as_str())?;+ }+ Ok(())+ }+/// contains a path component that would escape or alias the wiki root.pub fn new(raw: impl Into<String>) -> Result<Self, MemoryError> {let raw = raw.into();@@ -578,3 +605,126 @@ mod tests {);}}++/// Names Windows reserves regardless of extension: `CON.md` is still the+/// console device.+const DOS_DEVICE_NAMES: &[&str] = &[+ "con", "prn", "aux", "nul", "com1", "com2", "com3", "com4", "com5", "com6", "com7", "com8",+ "com9", "lpt1", "lpt2", "lpt3", "lpt4", "lpt5", "lpt6", "lpt7", "lpt8", "lpt9",+];++/// Characters Windows refuses in a filename. `/` is the separator and is+/// handled by the caller; `\\` and a drive prefix are already rejected by+/// [`PagePath::new`].+const WINDOWS_RESERVED_CHARS: &[char] = &['<', '>', ':', '"', '|', '?', '*'];++fn ensure_portable_component(component: &str, full: &str) -> Result<(), MemoryError> {+ let invalid = |reason: &str| {+ Err(MemoryError::InvalidPagePath(format!(+ "page path {full:?}: component {component:?} {reason}"+ )))+ };++ if let Some(bad) = component+ .chars()+ .find(|c| WINDOWS_RESERVED_CHARS.contains(c))+ {+ return invalid(&format!(+ "contains {bad:?}, which Windows refuses in a filename"+ ));+ }+ if let Some(bad) = component.chars().find(|c| (*c as u32) < 0x20) {+ return invalid(&format!(+ "contains control character U+{:04X}, which is not a legal filename byte",+ bad as u32+ ));+ }+ // A trailing dot or space is silently stripped by the Win32 layer, so the+ // file lands under a different name than the one recorded in the index.+ if component.ends_with('.') || component.ends_with(' ') {+ return invalid("ends with a dot or space, which Windows strips on create");+ }+ // Device names match on the stem, so `CON`, `CON.md` and `con.markdown`+ // are all the console.+ let stem = component.split('.').next().unwrap_or(component);+ if DOS_DEVICE_NAMES.contains(&stem.to_ascii_lowercase().as_str()) {+ return invalid(&format!(+ "uses the reserved DOS device name {stem:?}; Windows resolves it to a device, not a file"+ ));+ }+ Ok(())+}++#[cfg(test)]+mod portable_page_path_tests {+ use super::PagePath;++ /// Every shape #462 reproduced on native Windows. Each either fails late+ /// with a 500, or writes but cannot be checkpointed by libgit2 and cannot+ /// be deleted through the normal API — silent partial state, which is+ /// worse than a clean rejection.+ #[test]+ fn windows_hostile_paths_are_rejected() {+ for raw in [+ "CON.md",+ "notes/aux.md",+ "notes/NUL.md",+ "notes/com1.md",+ "notes/LPT9.txt",+ "notes/trailing./x.md",+ "notes/trailing /x.md",+ "notes/end.md.",+ "notes/end.md ",+ "notes/a<b.md",+ "notes/a>b.md",+ "notes/a\"b.md",+ "notes/a|b.md",+ "notes/a?b.md",+ "notes/a*b.md",+ "notes/a:b.md",+ "notes/a\u{1}b.md",+ ] {+ let path = PagePath::new(raw).expect("still constructible: reads must keep working");+ assert!(+ path.ensure_portable().is_err(),+ "{raw:?} is not portable and must be refused at write time"+ );+ }+ }++ /// The rule must not reject ordinary pages. `con` is only reserved as a+ /// whole component, so `concepts/` and `icon.md` are fine.+ #[test]+ fn ordinary_paths_stay_writable() {+ for raw in [+ "notes/portable.md",+ "concepts/no-impl-without-test.md",+ "sessions/2026-08-22.md",+ "notes/icon.md",+ "notes/console.md",+ "prn-notes/aux-iliary.md",+ "a/b/c/deep.md",+ "notes/dot.in.middle.md",+ "notes/UPPER.MD",+ ] {+ let path = PagePath::new(raw).expect("valid path");+ assert!(+ path.ensure_portable().is_ok(),+ "{raw:?} is portable and must stay writable"+ );+ }+ }++ /// Reads must keep working for pages already stored under a+ /// non-portable name: `PagePath::new` stays tolerant so a listing does+ /// not break on one bad row.+ #[test]+ fn existing_non_portable_pages_remain_constructible() {+ for raw in ["CON.md", "notes/a|b.md", "notes/trailing./x.md"] {+ assert!(+ PagePath::new(raw).is_ok(),+ "{raw:?} must still construct so persisted rows stay readable"+ );+ }+ }+}diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex e144621c..be46fc0c 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -1631,6 +1631,18 @@ impl Wiki {/// # Errors/// Returns [`WikiError`] for any filesystem, parsing, or store error.pub async fn write_page(&self, req: WritePageRequest) -> WikiResult<PageId> {+ // Reject a path that cannot be materialised and checkpointed on every+ // supported platform, before anything is written.+ //+ // This is the single funnel every page creation passes through, and+ // it is the moment the two failing operations happen: the file hits+ // the filesystem and libgit2 checkpoints it. Catching it earlier (in+ // `PagePath::new`) would break reads of already-stored pages, and+ // catching it later leaves the worst outcome observed in #462 — a+ // page written successfully but uncheckpointable and undeletable+ // through the normal API.+ req.path.ensure_portable()?;+let WritePageRequest {workspace_id,project_id,