Skip to main content

rigspark_runtime/
memory.rs

1#[cfg(test)]
2mod recovery_tests {
3    use super::*;
4    #[test]
5    fn interrupted_move_restores_source_and_target_from_either_entry_point() {
6        for open_source in [true, false] {
7            let root = tempfile::tempdir().unwrap();
8            let source = MemoryStore::open(root.path(), "source", "original-source").unwrap();
9            let target = MemoryStore::open(root.path(), "target", "original-target").unwrap();
10            let expected = target.files().unwrap();
11            let mut next = expected.clone();
12            next.insert("system.md".into(), "migrated persona".into());
13            let guard = source.lock().unwrap();
14            target.publish_pending(&guard, &expected, &next).unwrap();
15            target.prepare_move(&source, &guard).unwrap();
16            guard.release().unwrap();
17            if open_source {
18                MemoryStore::existing(root.path(), "source").unwrap();
19            } else {
20                MemoryStore::existing(root.path(), "target").unwrap();
21            }
22            assert_eq!(
23                MemoryStore::existing(root.path(), "source")
24                    .unwrap()
25                    .meta
26                    .created_at,
27                "original-source"
28            );
29            assert_eq!(
30                MemoryStore::existing(root.path(), "target")
31                    .unwrap()
32                    .files()
33                    .unwrap(),
34                expected
35            );
36        }
37    }
38}
39use crate::state::{Config, LockGuard, StateStore};
40use serde::{Deserialize, Serialize};
41use sha2::{Digest, Sha256};
42use std::{
43    fs,
44    io::Write,
45    path::{Path, PathBuf},
46    time::Duration,
47};
48
49#[derive(Debug, thiserror::Error)]
50#[error("memory: {0}")]
51pub struct MemoryError(pub String);
52impl From<std::io::Error> for MemoryError {
53    fn from(error: std::io::Error) -> Self {
54        Self(error.to_string())
55    }
56}
57impl From<serde_json::Error> for MemoryError {
58    fn from(error: serde_json::Error) -> Self {
59        Self(error.to_string())
60    }
61}
62impl From<crate::state::StateError> for MemoryError {
63    fn from(error: crate::state::StateError) -> Self {
64        Self(error.to_string())
65    }
66}
67#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
68#[serde(deny_unknown_fields)]
69pub struct EmbeddingMeta {
70    pub model: String,
71    pub dimension: usize,
72}
73#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize)]
74#[serde(rename_all = "camelCase", deny_unknown_fields)]
75pub struct MemoryMeta {
76    pub schema_version: u8,
77    pub model_id: String,
78    pub created_at: String,
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub embedding: Option<EmbeddingMeta>,
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub embedding_unsupported: Option<bool>,
83}
84impl MemoryMeta {
85    pub fn validate(&self) -> Result<(), MemoryError> {
86        if self.schema_version != 1
87            || self.model_id.is_empty()
88            || self.model_id.len() > 8192
89            || self.created_at.is_empty()
90            || self.created_at.len() > 1024
91            || self.embedding_unsupported == Some(false)
92            || self.embedding.as_ref().is_some_and(|embedding| {
93                embedding.model.is_empty()
94                    || embedding.model.len() > 8192
95                    || embedding.dimension == 0
96                    || embedding.dimension > 100000
97            })
98        {
99            return Err(MemoryError("invalid metadata".into()));
100        }
101        Ok(())
102    }
103}
104pub fn memory_slug(id: &str, windows: bool) -> Result<String, MemoryError> {
105    if id.len() > 1024 * 1024 {
106        return Err(MemoryError("model id exceeds limit".into()));
107    }
108    let mut slug = String::new();
109    for character in id.trim().to_lowercase().chars() {
110        let character = if character.is_ascii_alphanumeric() || "._-".contains(character) {
111            character
112        } else {
113            '-'
114        };
115        if character != '-' || !slug.ends_with('-') {
116            slug.push(character);
117        }
118    }
119    slug = slug.trim_matches(['-', '.']).into();
120    let stem = slug.split('.').next().unwrap_or("");
121    if windows
122        && (["con", "prn", "aux", "nul"].contains(&stem)
123            || (stem.starts_with("com") || stem.starts_with("lpt"))
124                && stem.len() == 4
125                && matches!(stem.as_bytes()[3], b'1'..=b'9'))
126    {
127        slug = format!("x-{slug}");
128    }
129    if slug.is_empty() {
130        return Err(MemoryError("model id has no filesystem-safe slug".into()));
131    }
132    if slug.len() > 128 {
133        let digest = format!("{:x}", Sha256::digest(slug.as_bytes()));
134        slug = format!(
135            "{}-{}",
136            slug[..111].trim_end_matches(['-', '.']),
137            &digest[..16]
138        );
139    }
140    Ok(slug)
141}
142pub(crate) fn private_directory(path: &Path) -> Result<(), MemoryError> {
143    match fs::symlink_metadata(path) {
144        Ok(metadata) if metadata.is_dir() && !metadata.file_type().is_symlink() => (),
145        Ok(_) => {
146            return Err(MemoryError(
147                "directory is symlinked or not a directory".into(),
148            ));
149        }
150        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
151            if let Some(parent) = path.parent() {
152                private_directory(parent)?;
153            }
154            let builder = fs::DirBuilder::new();
155            #[cfg(unix)]
156            let mut builder = builder;
157            #[cfg(unix)]
158            {
159                use std::os::unix::fs::DirBuilderExt;
160                builder.mode(0o700);
161            }
162            match builder.create(path) {
163                Ok(()) => (),
164                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {
165                    return private_directory(path);
166                }
167                Err(error) => return Err(error.into()),
168            }
169        }
170        Err(error) => return Err(error.into()),
171    }
172    Ok(())
173}
174pub(crate) fn owned_directory(path: &Path) -> Result<(), MemoryError> {
175    private_directory(path)?;
176    #[cfg(unix)]
177    {
178        use std::os::unix::fs::PermissionsExt;
179        crate::secure_fs::Directory::open(path)?
180            .dir()?
181            .open(".")?
182            .into_std()
183            .set_permissions(fs::Permissions::from_mode(0o700))?;
184    }
185    Ok(())
186}
187pub(crate) fn atomic_file(path: &Path, bytes: &[u8]) -> Result<(), MemoryError> {
188    let parent = path
189        .parent()
190        .ok_or_else(|| MemoryError("missing file parent".into()))?;
191    private_directory(parent)?;
192    let mut staged = tempfile::NamedTempFile::new_in(parent)?;
193    staged.write_all(bytes)?;
194    staged.as_file().sync_all()?;
195    staged
196        .persist(path)
197        .map_err(|error| MemoryError(error.to_string()))?;
198    #[cfg(unix)]
199    fs::File::open(parent)?.sync_all()?;
200    Ok(())
201}
202#[derive(Debug, Clone)]
203pub struct MemoryStore {
204    pub dir: PathBuf,
205    pub meta: MemoryMeta,
206    home: PathBuf,
207    home_directory: std::sync::Arc<crate::secure_fs::Directory>,
208}
209#[derive(Serialize, Deserialize)]
210#[serde(deny_unknown_fields)]
211struct MoveJournal {
212    source: String,
213    recovery: String,
214}
215impl MemoryStore {
216    pub fn open(home: &Path, id: &str, created_at: &str) -> Result<Self, MemoryError> {
217        let home = std::path::absolute(home)?;
218        let root = home.join("memory");
219        owned_directory(&home)?;
220        let home_directory = std::sync::Arc::new(crate::secure_fs::Directory::open(&home)?);
221        home_directory.ensure_dir(Path::new("memory"))?;
222        let dir = root.join(memory_slug(id, cfg!(windows))?);
223        let store = Self {
224            dir,
225            home,
226            home_directory,
227            meta: MemoryMeta {
228                schema_version: 1,
229                model_id: id.into(),
230                created_at: created_at.into(),
231                embedding: None,
232                embedding_unsupported: None,
233            },
234        };
235        store.initialize()
236    }
237    fn initialize(self) -> Result<Self, MemoryError> {
238        let mut store = self;
239        store.recover_if_needed()?;
240        store.mkdir(&store.dir)?;
241        let path = store.dir.join("meta.json");
242        if !path.try_exists()? {
243            store.meta.validate()?;
244            let mut bytes = serde_json::to_vec_pretty(&store.meta)?;
245            bytes.push(b'\n');
246            match store
247                .home_directory
248                .write(store.relative(&path)?, &bytes, true, false)
249            {
250                Ok(()) => (),
251                Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => (),
252                Err(error) => return Err(error.into()),
253            }
254        }
255        store.meta = store.read_meta()?;
256        Ok(store)
257    }
258    pub fn existing(home: &Path, id: &str) -> Result<Self, MemoryError> {
259        Self::existing_inner(home, id, true)
260    }
261    pub fn snapshot(home: &Path, id: &str) -> Result<SourceMemory, MemoryError> {
262        let store = Self::existing_inner(home, id, false)?;
263        load_files(&store.files()?, &store.read_meta()?)
264    }
265    fn existing_inner(home: &Path, id: &str, recover: bool) -> Result<Self, MemoryError> {
266        let home = std::path::absolute(home)?;
267        let dir = home.join("memory").join(memory_slug(id, cfg!(windows))?);
268        let mut store = Self {
269            dir,
270            home_directory: std::sync::Arc::new(crate::secure_fs::Directory::open(&home)?),
271            home,
272            meta: MemoryMeta {
273                schema_version: 1,
274                model_id: id.into(),
275                created_at: String::new(),
276                embedding: None,
277                embedding_unsupported: None,
278            },
279        };
280        if recover {
281            store.recover_if_needed()?;
282        } else if store.transaction_dir()?.try_exists()? {
283            return Err(MemoryError(
284                "memory recovery required before preview".into(),
285            ));
286        }
287        store.meta = store.read_meta()?;
288        Ok(store)
289    }
290    fn check_path(&self) -> Result<(), MemoryError> {
291        self.home_directory.check()?;
292        for path in [&self.home, &self.home.join("memory"), &self.dir] {
293            let metadata = fs::symlink_metadata(path)?;
294            if !metadata.is_dir() || metadata.file_type().is_symlink() {
295                return Err(MemoryError("unsafe memory directory".into()));
296            }
297        }
298        #[cfg(unix)]
299        {
300            use std::os::unix::fs::PermissionsExt;
301            if fs::metadata(&self.dir)?.permissions().mode() & 0o077 != 0 {
302                return Err(MemoryError("memory store permissions are too broad".into()));
303            }
304        }
305        if !self
306            .dir
307            .canonicalize()?
308            .starts_with(self.home.join("memory").canonicalize()?)
309        {
310            return Err(MemoryError("memory path escaped root".into()));
311        }
312        Ok(())
313    }
314    pub fn read_meta(&self) -> Result<MemoryMeta, MemoryError> {
315        self.check_path()?;
316        let raw = self.read_at(&self.dir.join("meta.json"), 16384, true)?;
317        let value: serde_json::Value = serde_json::from_str(&raw)?;
318        if value
319            .as_object()
320            .is_some_and(|object| object.values().any(serde_json::Value::is_null))
321        {
322            return Err(MemoryError("null metadata fields".into()));
323        }
324        let meta: MemoryMeta = serde_json::from_value(value)?;
325        meta.validate()?;
326        if meta.model_id != self.meta.model_id {
327            return Err(MemoryError("memory slug collision".into()));
328        }
329        Ok(meta)
330    }
331    pub fn lock(&self) -> Result<LockGuard, MemoryError> {
332        Ok(StateStore::new(Config::from_home(&self.home)?).lock(Duration::from_secs(10))?)
333    }
334    pub fn write_meta(&self, guard: &LockGuard, meta: &MemoryMeta) -> Result<(), MemoryError> {
335        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
336        self.read_meta()?;
337        meta.validate()?;
338        if meta.model_id != self.meta.model_id {
339            return Err(MemoryError("metadata owner changed".into()));
340        }
341        let mut bytes = serde_json::to_vec_pretty(meta)?;
342        bytes.push(b'\n');
343        self.write_at(&self.dir.join("meta.json"), &bytes)
344    }
345    fn relative<'path>(&self, path: &'path Path) -> Result<&'path Path, MemoryError> {
346        path.strip_prefix(&self.home)
347            .map_err(|_| MemoryError("path escaped memory home".into()))
348    }
349    fn mkdir(&self, path: &Path) -> Result<(), MemoryError> {
350        Ok(self.home_directory.ensure_dir(self.relative(path)?)?)
351    }
352    fn write_at(&self, path: &Path, bytes: &[u8]) -> Result<(), MemoryError> {
353        Ok(self
354            .home_directory
355            .write(self.relative(path)?, bytes, false, false)?)
356    }
357    fn read_at(
358        &self,
359        path: &Path,
360        maximum: usize,
361        secret: bool,
362    ) -> Result<String, crate::state::StateError> {
363        let relative = path
364            .strip_prefix(&self.home)
365            .map_err(|_| crate::state::StateError {
366                kind: "invalid",
367                message: "path escaped memory home".into(),
368            })?;
369        let bytes = self
370            .home_directory
371            .read(relative, maximum as u64, secret)
372            .map_err(|error| crate::state::StateError {
373                kind: if error.kind() == std::io::ErrorKind::NotFound {
374                    "absent"
375                } else {
376                    "io"
377                },
378                message: error.to_string(),
379            })?;
380        String::from_utf8(bytes).map_err(|_| crate::state::StateError {
381            kind: "invalid",
382            message: "memory file is not UTF-8".into(),
383        })
384    }
385    fn rename_at(&self, from: impl AsRef<Path>, to: impl AsRef<Path>) -> Result<(), MemoryError> {
386        let directory = self.home_directory.dir()?;
387        directory.rename(
388            self.relative(from.as_ref())?,
389            directory,
390            self.relative(to.as_ref())?,
391        )?;
392        #[cfg(unix)]
393        directory.open(".")?.sync_all()?;
394        Ok(())
395    }
396    fn remove_dir_at(&self, path: impl AsRef<Path>) -> Result<(), MemoryError> {
397        Ok(self
398            .home_directory
399            .dir()?
400            .remove_dir_all(self.relative(path.as_ref())?)?)
401    }
402}
403
404#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
405#[serde(deny_unknown_fields)]
406pub struct Turn {
407    pub role: String,
408    pub content: String,
409    pub ts: String,
410}
411#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
412#[serde(deny_unknown_fields)]
413pub struct Chunk {
414    pub id: String,
415    pub text: String,
416    pub ts: String,
417}
418#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
419#[serde(deny_unknown_fields)]
420pub struct Vector {
421    pub id: String,
422    pub vector: Vec<f64>,
423}
424#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
425#[serde(deny_unknown_fields)]
426pub struct Fact {
427    pub text: String,
428    pub ts: String,
429}
430#[derive(Debug, Clone, Deserialize, Serialize)]
431#[serde(rename_all = "camelCase", deny_unknown_fields)]
432struct Facts {
433    schema_version: u8,
434    facts: Vec<Fact>,
435}
436#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
437#[serde(rename_all = "camelCase", deny_unknown_fields)]
438pub struct SourceMemory {
439    pub turns: Vec<Turn>,
440    #[serde(skip_serializing_if = "Option::is_none")]
441    pub system_prompt: Option<String>,
442    pub facts_text: String,
443    pub facts_present: bool,
444    #[serde(skip_serializing_if = "Option::is_none")]
445    pub embedding: Option<SourceEmbedding>,
446}
447#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
448#[serde(deny_unknown_fields)]
449pub struct SourceEmbedding {
450    pub meta: EmbeddingMeta,
451    pub chunks: Vec<Chunk>,
452    pub vectors: Vec<Vector>,
453}
454pub struct EmbeddingOutput {
455    pub vectors: Vec<Vec<f64>>,
456    pub dimension: usize,
457}
458#[async_trait::async_trait]
459pub trait Embedder: Send + Sync {
460    fn model(&self) -> &str;
461    async fn embed(
462        &self,
463        texts: &[String],
464        cancel: &tokio_util::sync::CancellationToken,
465    ) -> Result<EmbeddingOutput, MemoryError>;
466}
467pub struct CaptureOptions<'capture> {
468    pub timestamp: &'capture str,
469    pub embedder: Option<&'capture dyn Embedder>,
470    pub embedding_unsupported: bool,
471}
472#[derive(Debug, Serialize)]
473#[serde(rename_all = "camelCase")]
474pub struct CaptureResult {
475    pub turns_appended: usize,
476    pub facts_extracted: usize,
477    pub vectors_embedded: usize,
478    /// Why recall vectors were not written; the turns and facts were still saved.
479    #[serde(skip_serializing_if = "Option::is_none")]
480    pub embedding_skipped: Option<String>,
481}
482type Files = std::collections::BTreeMap<String, String>;
483fn jsonl<T: serde::de::DeserializeOwned>(raw: &str) -> Result<Vec<T>, MemoryError> {
484    let mut records = Vec::new();
485    for line in raw.lines().filter(|line| !line.trim().is_empty()) {
486        records.push(serde_json::from_str(line)?);
487        if records.len() > 100000 {
488            return Err(MemoryError("record limit exceeded".into()));
489        }
490    }
491    Ok(records)
492}
493fn encode_lines<T: Serialize>(records: &[T]) -> Result<String, MemoryError> {
494    let mut result = String::new();
495    for record in records {
496        result.push_str(&serde_json::to_string(record)?);
497        result.push('\n');
498    }
499    Ok(result)
500}
501fn pretty<T: Serialize>(value: &T) -> Result<String, MemoryError> {
502    Ok(format!("{}\n", serde_json::to_string_pretty(value)?))
503}
504pub fn extract_facts(text: &str) -> Result<Vec<String>, MemoryError> {
505    let rules = [
506        (
507            r"(?i)(?-u:\b)(?:my name is|call me)\s+([^.,;!?\n]+)",
508            "name = ",
509        ),
510        (
511            r"(?i)(?-u:\b)i (?:live|reside) in\s+([^.,;!?\n]+)",
512            "location = ",
513        ),
514        (
515            r"(?i)(?-u:\b)i work (?:as|at)\s+([^.,;!?\n]+)",
516            "occupation = ",
517        ),
518        (
519            r"(?i)(?-u:\b)i (?:like|love|prefer|enjoy)\s+([^.,;!?\n]+)",
520            "preference = ",
521        ),
522        (r"(?i)(?-u:\b)remember(?: that)?[:\s]+([^.\n]+)", ""),
523    ];
524    let mut result = Vec::new();
525    let mut seen = std::collections::HashSet::new();
526    for (pattern, prefix) in rules {
527        let regex = regex::Regex::new(pattern).map_err(|error| MemoryError(error.to_string()))?;
528        for captures in regex.captures_iter(text) {
529            let Some(value) = captures
530                .get(1)
531                .map(|value| value.as_str().trim())
532                .filter(|value| !value.is_empty())
533            else {
534                continue;
535            };
536            let fact = format!("{prefix}{value}");
537            if seen.insert(fact.to_lowercase()) {
538                result.push(fact);
539            }
540        }
541    }
542    Ok(result)
543}
544fn validate_embeddings(output: &EmbeddingOutput, count: usize) -> Result<(), MemoryError> {
545    if output.dimension == 0
546        || output.dimension > 100000
547        || output.vectors.len() != count
548        || count
549            .checked_mul(output.dimension)
550            .is_none_or(|size| size > 2000000)
551        || output.vectors.iter().any(|vector| {
552            vector.len() != output.dimension || vector.iter().any(|value| !value.is_finite())
553        })
554    {
555        return Err(MemoryError("invalid embedding vectors or dimension".into()));
556    }
557    Ok(())
558}
559impl MemoryStore {
560    fn files(&self) -> Result<Files, MemoryError> {
561        self.read_meta()?;
562        let mut files = Files::new();
563        fn scan(
564            store: &MemoryStore,
565            directory: &cap_std::fs::Dir,
566            relative: &Path,
567            files: &mut Files,
568            total: &mut usize,
569            entries: &mut usize,
570            depth: usize,
571        ) -> Result<(), MemoryError> {
572            if depth > 40 {
573                return Err(MemoryError("memory directory depth exceeds limit".into()));
574            }
575            for entry in directory.entries()? {
576                let entry = entry?;
577                *entries += 1;
578                if *entries > 1024 {
579                    return Err(MemoryError("memory file count exceeds limit".into()));
580                }
581                let kind = entry.file_type()?;
582                let child = relative.join(entry.file_name());
583                if kind.is_dir() {
584                    scan(
585                        store,
586                        &directory.open_dir(entry.file_name())?,
587                        &child,
588                        files,
589                        total,
590                        entries,
591                        depth + 1,
592                    )?;
593                } else if kind.is_file() {
594                    let relative = child
595                        .to_str()
596                        .ok_or_else(|| MemoryError("invalid memory filename encoding".into()))?
597                        .replace('\\', "/");
598                    let maximum = match relative.as_str() {
599                        "meta.json" => 16384,
600                        "facts.json" => 1048576,
601                        "system.md" => 65536,
602                        "embeddings/vectors.jsonl" => 16 * 1024 * 1024,
603                        _ => 8 * 1024 * 1024,
604                    };
605                    let raw = store.read_at(&store.dir.join(&child), maximum, true)?;
606                    *total += raw.len();
607                    if *total > 64 * 1024 * 1024 {
608                        return Err(MemoryError("memory store exceeds limit".into()));
609                    }
610                    files.insert(relative, raw);
611                } else {
612                    return Err(MemoryError("symlink or special memory file".into()));
613                }
614            }
615            Ok(())
616        }
617        let directory = self.home_directory.subdir(self.relative(&self.dir)?)?;
618        scan(
619            self,
620            &directory,
621            Path::new(""),
622            &mut files,
623            &mut 0,
624            &mut 0,
625            0,
626        )?;
627        Ok(files)
628    }
629    pub fn load(&self) -> Result<SourceMemory, MemoryError> {
630        self.recover_if_needed()?;
631        let files = self.files()?;
632        load_files(&files, &self.read_meta()?)
633    }
634    fn transaction_dir(&self) -> Result<PathBuf, MemoryError> {
635        Ok(self.home.join(".staging").join(format!(
636            "memory-{}",
637            memory_slug(&self.meta.model_id, cfg!(windows))?
638        )))
639    }
640    pub fn recover(&self, guard: &LockGuard) -> Result<(), MemoryError> {
641        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
642        let transaction = self.transaction_dir()?;
643        if !transaction.try_exists()? {
644            return Ok(());
645        }
646        self.home_directory.subdir(self.relative(&transaction)?)?;
647        let marker = match self.read_at(&transaction.join("phase"), 32, true) {
648            Ok(marker) => marker,
649            Err(error) if error.kind == "absent" => "staging".into(),
650            Err(error) => return Err(error.into()),
651        };
652        let previous = transaction.join("previous");
653        let next = transaction.join("next");
654        if marker.trim() == "moving" {
655            let target_id = self.read_at(&transaction.join("target"), 8192, true)?;
656            if memory_slug(&target_id, cfg!(windows))?
657                == memory_slug(&self.meta.model_id, cfg!(windows))?
658            {
659                return Err(MemoryError("recursive memory recovery".into()));
660            }
661            let target = Self {
662                home_directory: self.home_directory.clone(),
663                dir: self
664                    .home
665                    .join("memory")
666                    .join(memory_slug(&target_id, cfg!(windows))?),
667                home: self.home.clone(),
668                meta: MemoryMeta {
669                    model_id: target_id,
670                    ..self.meta.clone()
671                },
672            };
673            if target.transaction_dir()?.try_exists()? {
674                let phase = self.read_at(&target.transaction_dir()?.join("phase"), 32, true)?;
675                if !["prepared", "committed"].contains(&phase.trim()) {
676                    return Err(MemoryError("invalid move target journal".into()));
677                }
678                target.recover(guard)?;
679            }
680            if transaction.try_exists()? {
681                self.remove_dir_at(transaction)?;
682            }
683            return Ok(());
684        }
685        if marker.trim() == "staging" {
686            if previous.try_exists()? {
687                return Err(MemoryError("ambiguous staging journal".into()));
688            }
689            self.read_meta()?;
690            let quarantine = self
691                .home
692                .join(".staging")
693                .join(format!("memory-recovered-{}", uuid::Uuid::new_v4()));
694            self.rename_at(transaction, quarantine)?;
695            return Ok(());
696        }
697        if marker.trim() == "committed" {
698            self.read_meta()?;
699            self.recover_move(guard, false)?;
700            self.remove_dir_at(transaction)?;
701            return Ok(());
702        }
703        if marker.trim() != "prepared" {
704            return Err(MemoryError("invalid memory recovery journal".into()));
705        }
706        if previous.try_exists()? {
707            self.home_directory.subdir(self.relative(&previous)?)?;
708            if self.dir.try_exists()? {
709                self.check_path()?;
710                if next.try_exists()? {
711                    return Err(MemoryError(
712                        "ambiguous memory recovery; preserve all generations".into(),
713                    ));
714                }
715                self.rename_at(&self.dir, &next)?;
716            }
717            self.rename_at(&previous, &self.dir)?;
718        }
719        self.read_meta()?;
720        self.recover_move(guard, true)?;
721        if next.try_exists()? {
722            let quarantine = self
723                .home
724                .join(".staging")
725                .join(format!("memory-recovered-{}", uuid::Uuid::new_v4()));
726            self.rename_at(&next, quarantine)?;
727        }
728        self.remove_dir_at(transaction)?;
729        Ok(())
730    }
731    fn recover_if_needed(&self) -> Result<(), MemoryError> {
732        if self.transaction_dir()?.try_exists()? {
733            let guard = self.lock()?;
734            self.recover(&guard)?;
735            guard.release()?;
736        }
737        Ok(())
738    }
739    fn publish(
740        &self,
741        guard: &LockGuard,
742        expected: &Files,
743        next: &Files,
744    ) -> Result<(), MemoryError> {
745        self.publish_pending(guard, expected, next)?;
746        self.commit_pending(guard)
747    }
748    fn publish_pending(
749        &self,
750        guard: &LockGuard,
751        expected: &Files,
752        next: &Files,
753    ) -> Result<(), MemoryError> {
754        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
755        self.recover(guard)?;
756        if &self.files()? != expected {
757            return Err(MemoryError("memory changed during preparation".into()));
758        }
759        let transaction = self.transaction_dir()?;
760        self.mkdir(&self.home.join(".staging"))?;
761        if transaction.try_exists()? {
762            return Err(MemoryError("memory transaction already exists".into()));
763        }
764        self.mkdir(&transaction)?;
765        self.write_at(&transaction.join("phase"), b"staging\n")?;
766        let staged = transaction.join("next");
767        self.mkdir(&staged)?;
768        let staged_result = (|| {
769            for (name, raw) in next {
770                if !crate::acquire::safe_file(name) {
771                    return Err(MemoryError("unsafe memory artifact name".into()));
772                }
773                let path = staged.join(name);
774                self.mkdir(
775                    path.parent()
776                        .ok_or_else(|| MemoryError("missing memory parent".into()))?,
777                )?;
778                self.write_at(&path, raw.as_bytes())?;
779            }
780            self.write_at(&transaction.join("phase"), b"prepared\n")?;
781            Ok::<_, MemoryError>(())
782        })();
783        if let Err(error) = staged_result {
784            self.remove_dir_at(&transaction)?;
785            return Err(error);
786        }
787        let commit = (|| {
788            guard.assert_owned()?;
789            if &self.files()? != expected {
790                return Err(MemoryError("memory changed before publication".into()));
791            }
792            self.rename_at(&self.dir, transaction.join("previous"))?;
793            self.rename_at(&staged, &self.dir)?;
794            if self.files()? != *next {
795                return Err(MemoryError("published memory verification failed".into()));
796            }
797            Ok::<_, MemoryError>(())
798        })();
799        if let Err(error) = commit {
800            self.recover(guard)?;
801            return Err(error);
802        }
803        Ok(())
804    }
805    fn commit_pending(&self, guard: &LockGuard) -> Result<(), MemoryError> {
806        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
807        self.write_at(&self.transaction_dir()?.join("phase"), b"committed\n")?;
808        self.recover(guard)
809    }
810    fn prepare_move(&self, source: &MemoryStore, guard: &LockGuard) -> Result<(), MemoryError> {
811        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
812        if source.home != self.home {
813            return Err(MemoryError("move crosses memory homes".into()));
814        }
815        source.check_path()?;
816        let recovery = format!("memory-moved-{}", uuid::Uuid::new_v4());
817        self.write_at(
818            &self.transaction_dir()?.join("move.json"),
819            &serde_json::to_vec(&MoveJournal {
820                source: source.meta.model_id.clone(),
821                recovery: recovery.clone(),
822            })?,
823        )?;
824        let source_transaction = source.transaction_dir()?;
825        if source_transaction.try_exists()? {
826            return Err(MemoryError("source transaction exists".into()));
827        }
828        self.mkdir(&source_transaction)?;
829        self.write_at(
830            &source_transaction.join("target"),
831            self.meta.model_id.as_bytes(),
832        )?;
833        self.write_at(&source_transaction.join("phase"), b"moving\n")?;
834        self.rename_at(&source.dir, self.home.join(".staging").join(recovery))?;
835        Ok(())
836    }
837    fn recover_move(&self, guard: &LockGuard, rollback: bool) -> Result<(), MemoryError> {
838        guard.assert_for(&Config::from_home(&self.home)?.lock)?;
839        let raw = match self.read_at(&self.transaction_dir()?.join("move.json"), 16384, true) {
840            Ok(raw) => raw,
841            Err(error) if error.kind == "absent" => return Ok(()),
842            Err(error) => return Err(error.into()),
843        };
844        let journal: MoveJournal = serde_json::from_str(&raw)?;
845        let suffix = journal
846            .recovery
847            .strip_prefix("memory-moved-")
848            .ok_or_else(|| MemoryError("invalid move recovery name".into()))?;
849        if uuid::Uuid::parse_str(suffix).is_err() {
850            return Err(MemoryError("invalid move recovery id".into()));
851        }
852        let slug = memory_slug(&journal.source, cfg!(windows))?;
853        if slug == memory_slug(&self.meta.model_id, cfg!(windows))? {
854            return Err(MemoryError("invalid move source".into()));
855        }
856        let source = self.home.join("memory").join(&slug);
857        let recovery = self.home.join(".staging").join(&journal.recovery);
858        if rollback && recovery.try_exists()? {
859            self.home_directory.subdir(self.relative(&recovery)?)?;
860            let meta: MemoryMeta =
861                serde_json::from_str(&self.read_at(&recovery.join("meta.json"), 16384, true)?)?;
862            meta.validate()?;
863            if meta.model_id != journal.source || source.try_exists()? {
864                return Err(MemoryError(
865                    "ambiguous source recovery; bytes retained".into(),
866                ));
867            }
868            self.rename_at(recovery, source)?;
869        }
870        let source_transaction = self.home.join(".staging").join(format!("memory-{slug}"));
871        if source_transaction.try_exists()? {
872            self.home_directory
873                .subdir(self.relative(&source_transaction)?)?;
874            let target = self.read_at(&source_transaction.join("target"), 8192, true)?;
875            if target != self.meta.model_id {
876                return Err(MemoryError("move recovery target changed".into()));
877            }
878            self.remove_dir_at(source_transaction)?;
879        }
880        Ok(())
881    }
882    pub async fn capture(
883        &self,
884        user: &str,
885        assistant: &str,
886        options: CaptureOptions<'_>,
887        cancel: &tokio_util::sync::CancellationToken,
888    ) -> Result<CaptureResult, MemoryError> {
889        if user.len() + assistant.len() > 8 * 1024 * 1024
890            || options.timestamp.is_empty()
891            || options.timestamp.len() > 1024
892        {
893            return Err(MemoryError("invalid capture input".into()));
894        }
895        if cancel.is_cancelled() {
896            return Err(MemoryError("cancelled".into()));
897        }
898        self.recover_if_needed()?;
899        let expected = self.files()?;
900        let mut source = load_files(&expected, &self.read_meta()?)?;
901        let mut meta = self.read_meta()?;
902        let texts = [
903            rigspark_core::reports::strip_control(user),
904            rigspark_core::reports::strip_control(assistant),
905        ];
906        let chunks: Vec<_> = texts
907            .iter()
908            .filter(|text| !text.is_empty())
909            .cloned()
910            .collect();
911        let mut embedding_skipped = None;
912        let embedding = if !options.embedding_unsupported && !chunks.is_empty() {
913            if let Some(embedder) = options.embedder {
914                let attempt = tokio::select! {biased;_=cancel.cancelled()=>return Err(MemoryError("cancelled".into())),result=tokio::time::timeout(Duration::from_secs(120),embedder.embed(&chunks,cancel))=>result};
915                // Embeddings only add recall: an embedder that cannot be reached skips the
916                // vectors but never loses the conversation. Malformed output or a changed
917                // embedding space still refuses the capture, and no vector is fabricated.
918                match attempt
919                    .map_err(|_| MemoryError("embedding timed out".into()))
920                    .and_then(|result| result)
921                {
922                    Err(error) => {
923                        embedding_skipped = Some(format!(
924                            "{} ({})",
925                            error.0,
926                            rigspark_core::reports::strip_control(embedder.model())
927                        ));
928                        None
929                    }
930                    Ok(result) => {
931                        validate_embeddings(&result, chunks.len())?;
932                        let space = EmbeddingMeta {
933                            model: embedder.model().into(),
934                            dimension: result.dimension,
935                        };
936                        if space.model.is_empty()
937                            || meta
938                                .embedding
939                                .as_ref()
940                                .is_some_and(|existing| existing != &space)
941                        {
942                            return Err(MemoryError("embedding space mismatch".into()));
943                        }
944                        Some((space, result))
945                    }
946                }
947            } else {
948                None
949            }
950        } else {
951            None
952        };
953        let before = source.turns.len();
954        for (role, content) in ["user", "assistant"].into_iter().zip(&texts) {
955            if !content.is_empty() {
956                source.turns.push(Turn {
957                    role: role.into(),
958                    content: content.clone(),
959                    ts: options.timestamp.into(),
960                });
961            }
962        }
963        let mut facts = if source.facts_present {
964            serde_json::from_str::<Facts>(&source.facts_text)?
965        } else {
966            Facts {
967                schema_version: 1,
968                facts: Vec::new(),
969            }
970        };
971        validate_facts(&facts)?;
972        let mut known: std::collections::HashSet<_> = facts
973            .facts
974            .iter()
975            .map(|fact| fact.text.to_lowercase())
976            .collect();
977        let mut added = 0;
978        for text in extract_facts(&texts[0])? {
979            if known.insert(text.to_lowercase()) {
980                facts.facts.push(Fact {
981                    text,
982                    ts: options.timestamp.into(),
983                });
984                added += 1;
985            }
986        }
987        let mut next = expected.clone();
988        next.insert("conversation.jsonl".into(), encode_lines(&source.turns)?);
989        if added > 0 || !source.facts_present {
990            next.insert("facts.json".into(), pretty(&facts)?);
991        }
992        let mut embedded = 0;
993        if options.embedding_unsupported {
994            meta.embedding = None;
995            meta.embedding_unsupported = Some(true);
996        } else if let Some((space, output)) = embedding {
997            let mut index = source.embedding.unwrap_or(SourceEmbedding {
998                meta: space.clone(),
999                chunks: Vec::new(),
1000                vectors: Vec::new(),
1001            });
1002            for (text, vector) in chunks.into_iter().zip(output.vectors) {
1003                let id = uuid::Uuid::new_v4().to_string();
1004                index.chunks.push(Chunk {
1005                    id: id.clone(),
1006                    text,
1007                    ts: options.timestamp.into(),
1008                });
1009                index.vectors.push(Vector { id, vector });
1010                embedded += 1;
1011            }
1012            meta.embedding = Some(space);
1013            meta.embedding_unsupported = None;
1014            next.insert(
1015                "embeddings/chunks.jsonl".into(),
1016                encode_lines(&index.chunks)?,
1017            );
1018            next.insert(
1019                "embeddings/vectors.jsonl".into(),
1020                encode_lines(&index.vectors)?,
1021            );
1022        }
1023        meta.validate()?;
1024        next.insert("meta.json".into(), pretty(&meta)?);
1025        load_files(&next, &meta)?;
1026        let guard = self.lock()?;
1027        if cancel.is_cancelled() {
1028            return Err(MemoryError("cancelled".into()));
1029        }
1030        self.publish(&guard, &expected, &next)?;
1031        guard.release()?;
1032        Ok(CaptureResult {
1033            turns_appended: source.turns.len() - before,
1034            facts_extracted: added,
1035            vectors_embedded: embedded,
1036            embedding_skipped,
1037        })
1038    }
1039}
1040fn validate_facts(facts: &Facts) -> Result<(), MemoryError> {
1041    if facts.schema_version != 1
1042        || facts.facts.len() > 100000
1043        || facts
1044            .facts
1045            .iter()
1046            .any(|fact| fact.text.is_empty() || fact.ts.is_empty())
1047    {
1048        return Err(MemoryError("invalid facts".into()));
1049    }
1050    Ok(())
1051}
1052fn load_files(files: &Files, meta: &MemoryMeta) -> Result<SourceMemory, MemoryError> {
1053    let turns: Vec<Turn> = jsonl(
1054        files
1055            .get("conversation.jsonl")
1056            .map(String::as_str)
1057            .unwrap_or(""),
1058    )?;
1059    if turns
1060        .iter()
1061        .any(|turn| !["user", "assistant", "system"].contains(&turn.role.as_str()))
1062    {
1063        return Err(MemoryError("invalid stored role".into()));
1064    }
1065    let embedding = if let Some(space) = &meta.embedding {
1066        let chunks: Vec<Chunk> = jsonl(
1067            files
1068                .get("embeddings/chunks.jsonl")
1069                .map(String::as_str)
1070                .unwrap_or(""),
1071        )?;
1072        let vectors: Vec<Vector> = jsonl(
1073            files
1074                .get("embeddings/vectors.jsonl")
1075                .map(String::as_str)
1076                .unwrap_or(""),
1077        )?;
1078        let ids: std::collections::HashSet<_> = chunks.iter().map(|chunk| &chunk.id).collect();
1079        let vector_ids: std::collections::HashSet<_> =
1080            vectors.iter().map(|vector| &vector.id).collect();
1081        if ids.len() != chunks.len()
1082            || vector_ids.len() != vectors.len()
1083            || ids != vector_ids
1084            || vectors.iter().any(|vector| {
1085                vector.vector.len() != space.dimension
1086                    || vector.vector.iter().any(|value| !value.is_finite())
1087            })
1088        {
1089            return Err(MemoryError("inconsistent embedding index".into()));
1090        }
1091        Some(SourceEmbedding {
1092            meta: space.clone(),
1093            chunks,
1094            vectors,
1095        })
1096    } else {
1097        None
1098    };
1099    let facts_text = files.get("facts.json").cloned().unwrap_or_default();
1100    let facts_present = files.contains_key("facts.json");
1101    Ok(SourceMemory {
1102        turns,
1103        embedding,
1104        system_prompt: files.get("system.md").cloned(),
1105        facts_text,
1106        facts_present,
1107    })
1108}
1109
1110#[async_trait::async_trait]
1111pub trait Summarizer: Send + Sync {
1112    async fn summarize(
1113        &self,
1114        turns: &[Turn],
1115        cancel: &tokio_util::sync::CancellationToken,
1116    ) -> Result<String, MemoryError>;
1117}
1118pub struct MigrationOptions<'migration> {
1119    pub context: u32,
1120    pub embedder: Option<&'migration dyn Embedder>,
1121    pub target_dimension: Option<usize>,
1122    pub summarizer: Option<&'migration dyn Summarizer>,
1123    pub embedding_unsupported: bool,
1124}
1125#[derive(Debug, Clone, Serialize)]
1126#[serde(rename_all = "camelCase")]
1127pub struct MigrationSummary {
1128    pub turns_carried: usize,
1129    pub turns_summarized: usize,
1130    pub vectors_reembedded: usize,
1131    pub strategy: String,
1132    pub embedding_strategy: String,
1133}
1134pub struct MigrationPlan {
1135    pub source: SourceMemory,
1136    pub embedding_unsupported: bool,
1137    pub summary: MigrationSummary,
1138}
1139fn token_count(text: &str) -> usize {
1140    text.encode_utf16().count().div_ceil(4)
1141}
1142fn truncate_utf16(text: &str, maximum: usize) -> String {
1143    let mut length = 0;
1144    text.chars()
1145        .take_while(|character| {
1146            length += character.len_utf16();
1147            length <= maximum
1148        })
1149        .collect()
1150}
1151pub async fn plan_migration(
1152    source: &SourceMemory,
1153    options: MigrationOptions<'_>,
1154    cancel: &tokio_util::sync::CancellationToken,
1155) -> Result<MigrationPlan, MemoryError> {
1156    if options.context == 0 || options.context > 10000000 || source.turns.len() > 100000 {
1157        return Err(MemoryError("invalid migration budget or history".into()));
1158    }
1159    if cancel.is_cancelled() {
1160        return Err(MemoryError("cancelled".into()));
1161    }
1162    let mut output = source.clone();
1163    let mut summary = MigrationSummary {
1164        turns_carried: source.turns.len(),
1165        turns_summarized: 0,
1166        vectors_reembedded: 0,
1167        strategy: "none".into(),
1168        embedding_strategy: "none".into(),
1169    };
1170    let reserved = token_count(source.system_prompt.as_deref().unwrap_or(""))
1171        + token_count(&source.facts_text);
1172    let turn_cost = source
1173        .turns
1174        .iter()
1175        .map(|turn| token_count(&turn.content))
1176        .sum::<usize>();
1177    if reserved + turn_cost > options.context as usize {
1178        let available = (options.context as usize).saturating_sub(reserved + 256);
1179        let mut running = 0;
1180        let mut kept = 0;
1181        for turn in source.turns.iter().rev() {
1182            let cost = token_count(&turn.content);
1183            if running + cost > available {
1184                break;
1185            }
1186            running += cost;
1187            kept += 1;
1188        }
1189        let overflow = source.turns.len() - kept;
1190        if overflow > 0 {
1191            let content = if let Some(summarizer) = options.summarizer {
1192                let text = tokio::select! {biased;_=cancel.cancelled()=>return Err(MemoryError("cancelled".into())),result=tokio::time::timeout(Duration::from_secs(120),summarizer.summarize(&source.turns[..overflow],cancel))=>result.map_err(|_|MemoryError("summarization timed out".into()))??};
1193                summary.strategy = "summarize".into();
1194                truncate_utf16(
1195                    &format!(
1196                        "Summary of prior conversation: {}",
1197                        rigspark_core::reports::strip_control(&text)
1198                    ),
1199                    1024,
1200                )
1201            } else {
1202                summary.strategy = "truncate".into();
1203                format!("[{overflow} earlier turns omitted during migration]")
1204            };
1205            output.turns = vec![Turn {
1206                role: "system".into(),
1207                content,
1208                ts: source.turns[0].ts.clone(),
1209            }];
1210            output.turns.extend_from_slice(&source.turns[overflow..]);
1211            summary.turns_carried = kept;
1212            summary.turns_summarized = overflow;
1213        }
1214    }
1215    if options.embedding_unsupported {
1216        output.embedding = None;
1217    } else if let Some(index) = &source.embedding {
1218        if !index.chunks.is_empty() {
1219            if let Some(embedder) = options.embedder.filter(|embedder| {
1220                embedder.model() != index.meta.model
1221                    || options.target_dimension != Some(index.meta.dimension)
1222            }) {
1223                let dimension = options
1224                    .target_dimension
1225                    .filter(|dimension| *dimension > 0 && *dimension <= 100000)
1226                    .ok_or_else(|| MemoryError("target embedding dimension required".into()))?;
1227                let texts: Vec<_> = index
1228                    .chunks
1229                    .iter()
1230                    .map(|chunk| chunk.text.clone())
1231                    .collect();
1232                let output_vectors = tokio::select! {biased;_=cancel.cancelled()=>return Err(MemoryError("cancelled".into())),result=tokio::time::timeout(Duration::from_secs(120),embedder.embed(&texts,cancel))=>result.map_err(|_|MemoryError("reembedding timed out".into()))??};
1233                validate_embeddings(&output_vectors, texts.len())?;
1234                if output_vectors.dimension != dimension {
1235                    return Err(MemoryError("reembedding dimension mismatch".into()));
1236                }
1237                let vectors = index
1238                    .chunks
1239                    .iter()
1240                    .zip(output_vectors.vectors)
1241                    .map(|(chunk, vector)| Vector {
1242                        id: chunk.id.clone(),
1243                        vector,
1244                    })
1245                    .collect();
1246                output.embedding = Some(SourceEmbedding {
1247                    meta: EmbeddingMeta {
1248                        model: embedder.model().into(),
1249                        dimension,
1250                    },
1251                    chunks: index.chunks.clone(),
1252                    vectors,
1253                });
1254                summary.embedding_strategy = "reembed".into();
1255                summary.vectors_reembedded = texts.len();
1256            } else {
1257                summary.embedding_strategy = "reuse".into();
1258            }
1259        } else {
1260            output.embedding = None;
1261        }
1262    }
1263    Ok(MigrationPlan {
1264        source: output,
1265        embedding_unsupported: options.embedding_unsupported,
1266        summary,
1267    })
1268}
1269pub struct PreparedMigration {
1270    source_dir: PathBuf,
1271    source_id: String,
1272    source_files: Files,
1273    target_id: String,
1274    prior_target: Option<Files>,
1275    plan: MigrationPlan,
1276}
1277impl PreparedMigration {
1278    pub fn summary(&self) -> &MigrationSummary {
1279        &self.plan.summary
1280    }
1281}
1282impl MemoryStore {
1283    pub async fn migrate(
1284        &self,
1285        target_id: &str,
1286        created_at: &str,
1287        options: MigrationOptions<'_>,
1288        move_source: bool,
1289        cancel: &tokio_util::sync::CancellationToken,
1290    ) -> Result<MemoryStore, MemoryError> {
1291        let prepared = self.prepare_migration(target_id, options, cancel).await?;
1292        self.commit_migration(prepared, created_at, move_source, cancel)
1293    }
1294    pub async fn prepare_migration(
1295        &self,
1296        target_id: &str,
1297        options: MigrationOptions<'_>,
1298        cancel: &tokio_util::sync::CancellationToken,
1299    ) -> Result<PreparedMigration, MemoryError> {
1300        if memory_slug(target_id, cfg!(windows))?
1301            == memory_slug(&self.meta.model_id, cfg!(windows))?
1302        {
1303            return Err(MemoryError("source and target stores must differ".into()));
1304        }
1305        self.recover_if_needed()?;
1306        let source_files = self.files()?;
1307        let source = load_files(&source_files, &self.read_meta()?)?;
1308        let target_path = self
1309            .home
1310            .join("memory")
1311            .join(memory_slug(target_id, cfg!(windows))?);
1312        let target_probe = Self {
1313            home_directory: self.home_directory.clone(),
1314            dir: target_path.clone(),
1315            home: self.home.clone(),
1316            meta: MemoryMeta {
1317                model_id: target_id.into(),
1318                ..self.meta.clone()
1319            },
1320        };
1321        target_probe.recover_if_needed()?;
1322        let prior_target = if target_path.try_exists()? {
1323            Some(Self::existing(&self.home, target_id)?.files()?)
1324        } else {
1325            None
1326        };
1327        let plan = plan_migration(&source, options, cancel).await?;
1328        Ok(PreparedMigration {
1329            source_dir: self.dir.clone(),
1330            source_id: self.meta.model_id.clone(),
1331            source_files,
1332            target_id: target_id.into(),
1333            prior_target,
1334            plan,
1335        })
1336    }
1337    pub fn commit_migration(
1338        &self,
1339        prepared: PreparedMigration,
1340        created_at: &str,
1341        move_source: bool,
1342        cancel: &tokio_util::sync::CancellationToken,
1343    ) -> Result<MemoryStore, MemoryError> {
1344        self.commit_migration_with(prepared, created_at, move_source, cancel, || Ok(()))
1345    }
1346    pub fn commit_migration_with(
1347        &self,
1348        prepared: PreparedMigration,
1349        created_at: &str,
1350        move_source: bool,
1351        cancel: &tokio_util::sync::CancellationToken,
1352        check: impl FnOnce() -> Result<(), MemoryError>,
1353    ) -> Result<MemoryStore, MemoryError> {
1354        if prepared.source_dir != self.dir || prepared.source_id != self.meta.model_id {
1355            return Err(MemoryError(
1356                "prepared migration belongs to another source".into(),
1357            ));
1358        }
1359        let PreparedMigration {
1360            source_files,
1361            target_id,
1362            prior_target,
1363            plan,
1364            ..
1365        } = prepared;
1366        let target_id = target_id.as_str();
1367        let target_path = self
1368            .home
1369            .join("memory")
1370            .join(memory_slug(target_id, cfg!(windows))?);
1371        let target_probe = Self {
1372            dir: target_path.clone(),
1373            home: self.home.clone(),
1374            home_directory: self.home_directory.clone(),
1375            meta: MemoryMeta {
1376                model_id: target_id.into(),
1377                ..self.meta.clone()
1378            },
1379        };
1380        let guard = self.lock()?;
1381        check()?;
1382        if cancel.is_cancelled() {
1383            return Err(MemoryError("cancelled".into()));
1384        }
1385        if self.files()? != source_files {
1386            return Err(MemoryError(
1387                "source memory changed during preparation".into(),
1388            ));
1389        }
1390        if target_probe.transaction_dir()?.try_exists()? {
1391            return Err(MemoryError(
1392                "target transaction changed during preparation".into(),
1393            ));
1394        }
1395        let current_target = if target_path.try_exists()? {
1396            Some(Self::existing(&self.home, target_id)?.files()?)
1397        } else {
1398            None
1399        };
1400        if current_target != prior_target {
1401            return Err(MemoryError(
1402                "target memory changed during preparation".into(),
1403            ));
1404        }
1405        let mut target = target_probe;
1406        target.meta.created_at = created_at.into();
1407        target.meta.embedding = None;
1408        target.meta.embedding_unsupported = None;
1409        let target = target.initialize()?;
1410        let expected = target.files()?;
1411        let mut meta = target.read_meta()?;
1412        meta.embedding = plan
1413            .source
1414            .embedding
1415            .as_ref()
1416            .map(|index| index.meta.clone());
1417        meta.embedding_unsupported = plan.embedding_unsupported.then_some(true);
1418        let mut next = source_files.clone();
1419        next.insert("meta.json".into(), pretty(&meta)?);
1420        next.insert(
1421            "conversation.jsonl".into(),
1422            encode_lines(&plan.source.turns)?,
1423        );
1424        if let Some(persona) = &plan.source.system_prompt {
1425            next.insert("system.md".into(), persona.clone());
1426        } else {
1427            next.remove("system.md");
1428        }
1429        if plan.source.facts_present {
1430            next.insert("facts.json".into(), plan.source.facts_text.clone());
1431        } else {
1432            next.remove("facts.json");
1433        }
1434        if let Some(index) = &plan.source.embedding {
1435            next.insert(
1436                "embeddings/chunks.jsonl".into(),
1437                encode_lines(&index.chunks)?,
1438            );
1439            next.insert(
1440                "embeddings/vectors.jsonl".into(),
1441                encode_lines(&index.vectors)?,
1442            );
1443        } else {
1444            next.remove("embeddings/chunks.jsonl");
1445            next.remove("embeddings/vectors.jsonl");
1446        }
1447        load_files(&next, &meta)?;
1448        if let Err(error) = target.publish_pending(&guard, &expected, &next) {
1449            if prior_target.is_none() && target.dir.try_exists()? && target.files()? == expected {
1450                self.remove_dir_at(&target.dir)?;
1451            }
1452            return Err(error);
1453        }
1454        let finish = (|| {
1455            if move_source {
1456                if self.files()? != source_files {
1457                    return Err(MemoryError("source changed before retirement".into()));
1458                }
1459                target.prepare_move(self, &guard)?;
1460            }
1461            target.commit_pending(&guard)
1462        })();
1463        if let Err(error) = finish {
1464            target.recover(&guard)?;
1465            if prior_target.is_none() && target.files()? == expected {
1466                self.remove_dir_at(&target.dir)?;
1467            }
1468            return Err(error);
1469        }
1470        guard.release()?;
1471        Self::existing(&self.home, target_id)
1472    }
1473}