Skip to content

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.md
index 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 its
heading. Only the FTS5 path built a real excerpt (`snippet(pages_fts, ...)`,
centred on the matched terms); the vector, entity-match, graph-neighbour and
diff --git a/crates/ai-memory-core/src/ids.rs b/crates/ai-memory-core/src/ids.rs
index 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.rs
index 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,