Skip to main content

session_core/
migration.rs

1//! Explicit, repeatable migration between Pi and Ultron sessions (`ultron/migration.ts`): [`import_pi_session`]
2//! copies a whole Pi session tree into a new native format-4 session, [`export_native_session_to_pi`] writes a native
3//! session's whole tree back as a Pi session (rollback). Nothing here reads Pi's data directory implicitly: every
4//! source path is given by the caller.
5//!
6//! Pi entry mapping (Pi entry ids are kept as native entry ids, parents are unchanged):
7//! - `message`, `compaction`, `branch_summary`, `custom` -> the native entry of the same type;
8//! - `custom_message` -> a native `message` entry with a `custom` role message;
9//! - every other Pi entry type -> a native `custom` entry `pi-session:<type>` whose data is the Pi entry without
10//!   `type`/`id`/`parentId`/`timestamp`;
11//! - at the end: the `main` tip is the Pi leaf, labels are Pi's resolved labels, the name is Pi's name, and the `main`
12//!   lane configuration carries the model and thinking level Pi resolves at the leaf;
13//! - a `context_edit` dominated by its target is baked into the target (replacement or omission); one that only some
14//!   branches carry is applied per branch on copies (`<id>~<editId>`, recorded in `ultron.pi.copyOf`);
15//! - Pi-reported usage becomes the usage ledger's imported historical root `import:pi:<piSessionId>`;
16//! - an entry the native form cannot reproduce exactly keeps its Pi original in `ultron.pi.original`.
17//!
18//! The native file is byte-for-byte what the TypeScript product writes for the same Pi file
19//! (`fixtures/migration/migration.json`).
20
21use crate::pi_view::{native_session_as_pi, native_to_pi_entry};
22use delegation::usage::{Measurement, UsageLedger, UsageOptions};
23use kernel::store::DocumentStore;
24use serde_json::{Map, Value, json};
25use session_file::{Leaf, SessionManager, SystemEnv, build_context_entries, build_session_context, entry_messages, js};
26use session_journal::ns::{BRANCH_TIP, ENTRY_LABEL, LANE_CONFIG, LANE_STATE, SESSION_NAME, USAGE_ROOT};
27use session_journal::{Clock, SessionRepo, SharedClock, SystemClock, Write};
28use std::collections::{HashMap, HashSet, VecDeque};
29use std::path::{Path, PathBuf};
30use std::sync::{Arc, Mutex, PoisonError};
31
32pub const PI_ENTRY_CUSTOM_TYPE_PREFIX: &str = "pi-session:";
33pub const PI_OMITTED_MESSAGE_CUSTOM_TYPE: &str = "pi-import:omitted-message";
34pub const PI_LEAF_MARKER_CUSTOM_TYPE: &str = "ultron:pi-leaf";
35pub const PI_ORIGINAL: &str = "ultron.pi.original";
36pub const PI_COPY_OF: &str = "ultron.pi.copyOf";
37/// Pi's `CURRENT_SESSION_VERSION`.
38const PI_SESSION_VERSION: u64 = 3;
39
40const KNOWN_PI_ENTRY_TYPES: [&str; 11] = [
41    "message",
42    "custom_message",
43    "compaction",
44    "branch_summary",
45    "custom",
46    "model_change",
47    "thinking_level_change",
48    "label",
49    "session_info",
50    "usage",
51    "context_edit",
52];
53
54pub fn pi_import_usage_root(pi_session_id: &str) -> String {
55    format!("import:pi:{pi_session_id}")
56}
57
58/// `nativeSessionIdForPiSession`: a UUID-shaped (version 8) digest of the Pi session id.
59pub fn native_session_id_for_pi_session(pi_session_id: &str) -> String {
60    let digest = jsrt::hash::sha256(format!("ultron:pi-import:{pi_session_id}"));
61    let mut bytes = [0u8; 16];
62    bytes.copy_from_slice(&digest[..16]);
63    bytes[6] = (bytes[6] & 0x0f) | 0x80;
64    bytes[8] = (bytes[8] & 0x3f) | 0x80;
65    jsrt::random::format_uuid(&bytes)
66}
67
68fn str_of<'a>(entry: &'a Value, key: &str) -> Option<&'a str> {
69    entry.get(key).and_then(Value::as_str)
70}
71
72fn id_of(entry: &Value) -> &str {
73    str_of(entry, "id").unwrap_or_default()
74}
75
76fn type_of(entry: &Value) -> &str {
77    str_of(entry, "type").unwrap_or_default()
78}
79
80/// `parseTimestamp`: `Date.parse(value)`, else `fallback`.
81fn parse_timestamp(value: Option<&Value>, fallback: i64) -> i64 {
82    value
83        .and_then(Value::as_str)
84        .and_then(jsrt::date::parse_date)
85        .unwrap_or(fallback)
86}
87
88/// Copy `key` of `from` into `out` when it is present (JavaScript drops `undefined` fields).
89fn put(out: &mut Map<String, Value>, key: &str, from: &Value) {
90    if let Some(value) = from.get(key) {
91        out.insert(key.into(), value.clone());
92    }
93}
94
95/// `applyEdit`: `None` is no edit, `Some(Null)` an omission, `Some(replacement)` a replacement.
96fn apply_edit(messages: Vec<Value>, edit: Option<&Value>) -> Vec<Value> {
97    match edit {
98        None => messages,
99        Some(Value::Null) => Vec::new(),
100        Some(replacement) => messages
101            .iter()
102            .map(|message| session_journal::context::replace_content(message, replacement.get("content")))
103            .collect(),
104    }
105}
106
107/// Parent-first order that otherwise keeps file order (`PiTree`).
108struct PiTree {
109    by_id: HashMap<String, Value>,
110    children: HashMap<String, Vec<String>>,
111}
112
113impl PiTree {
114    fn new(entries: &[Value]) -> Self {
115        let by_id: HashMap<String, Value> = entries.iter().map(|e| (id_of(e).to_string(), e.clone())).collect();
116        let mut tree = PiTree {
117            by_id,
118            children: HashMap::new(),
119        };
120        for entry in entries {
121            if let Some(parent) = tree.parent_of(entry) {
122                tree.children.entry(parent).or_default().push(id_of(entry).to_string());
123            }
124        }
125        tree
126    }
127
128    fn child_ids(&self, id: &str) -> &[String] {
129        self.children.get(id).map_or(&[], Vec::as_slice)
130    }
131
132    /// The parent as Pi's tree resolves it: missing or self parents make the entry a root.
133    fn parent_of(&self, entry: &Value) -> Option<String> {
134        let parent = str_of(entry, "parentId")?;
135        (parent != id_of(entry) && self.by_id.contains_key(parent)).then(|| parent.to_string())
136    }
137
138    /// Whether `descendant` is below `ancestor` and every leaf under `ancestor` passes through it.
139    fn dominates(&self, ancestor: &str, descendant: &str) -> bool {
140        let Some(mut current) = self.by_id.get(descendant) else {
141            return false;
142        };
143        let mut steps = 0;
144        while let Some(parent) = self.parent_of(current) {
145            if self.child_ids(&parent).len() != 1 {
146                return false;
147            }
148            if parent == ancestor {
149                return true;
150            }
151            current = &self.by_id[&parent];
152            steps += 1;
153            if steps > self.by_id.len() {
154                return false;
155            }
156        }
157        false
158    }
159
160    fn insertion_order(&self, entries: &[Value]) -> Vec<Value> {
161        let mut out = Vec::new();
162        let mut placed: HashSet<String> = HashSet::new();
163        let mut waiting: Vec<(String, Vec<Value>)> = Vec::new();
164        fn take(waiting: &mut Vec<(String, Vec<Value>)>, id: &str) -> Option<Vec<Value>> {
165            let at = waiting.iter().position(|(key, _)| key == id)?;
166            Some(waiting.remove(at).1)
167        }
168        let place = |entry: &Value,
169                     out: &mut Vec<Value>,
170                     placed: &mut HashSet<String>,
171                     waiting: &mut Vec<(String, Vec<Value>)>| {
172            let mut stack = vec![entry.clone()];
173            while let Some(next) = stack.pop() {
174                let id = id_of(&next).to_string();
175                out.push(next);
176                placed.insert(id.clone());
177                if let Some(mut children) = take(waiting, &id) {
178                    children.reverse();
179                    stack.extend(children);
180                }
181            }
182        };
183        for entry in entries {
184            if placed.contains(id_of(entry)) {
185                continue;
186            }
187            match self.parent_of(entry) {
188                Some(parent) if !placed.contains(&parent) => match waiting.iter_mut().find(|(key, _)| *key == parent) {
189                    Some((_, siblings)) => siblings.push(entry.clone()),
190                    None => waiting.push((parent, vec![entry.clone()])),
191                },
192                _ => place(entry, &mut out, &mut placed, &mut waiting),
193            }
194        }
195        // Only cycles remain; Pi cannot reach these entries from a root either.
196        let rest: Vec<Value> = waiting.iter().flat_map(|(_, children)| children.clone()).collect();
197        for entry in rest {
198            if !placed.contains(id_of(&entry)) {
199                place(&entry, &mut out, &mut placed, &mut waiting);
200            }
201        }
202        out
203    }
204}
205
206/// `remap`: point an edit's or label's `targetId` (a compaction's `firstKeptEntryId`) at its copy.
207fn remap(entry: &mut Value, mapping: &HashMap<String, String>) {
208    let kind = type_of(entry);
209    if !matches!(kind, "context_edit" | "label" | "compaction") {
210        return;
211    }
212    let field = if kind == "compaction" {
213        "firstKeptEntryId"
214    } else {
215        "targetId"
216    };
217    if let Some(next) = str_of(entry, field).and_then(|target| mapping.get(target)) {
218        entry[field] = json!(next);
219    }
220}
221
222/// `splitBranchLocalEdits`: every context edit on a message on its own path ends up dominated by its target, the
223/// path from the target to the last fork copied for the edit's branch. Returns the entries and `copyOf`.
224fn split_branch_local_edits(input: &[Value]) -> (Vec<Value>, HashMap<String, String>) {
225    let mut entries = input.to_vec();
226    let mut copy_of: HashMap<String, String> = HashMap::new();
227    let mut ids: HashSet<String> = entries.iter().map(|e| id_of(e).to_string()).collect();
228    let mut split = |edit_id: &str, entries: &mut Vec<Value>| -> bool {
229        let tree = PiTree::new(entries);
230        let Some(edit) = tree.by_id.get(edit_id) else {
231            return false;
232        };
233        let Some(target) = str_of(edit, "targetId").and_then(|t| tree.by_id.get(t)) else {
234            return false;
235        };
236        if !matches!(type_of(target), "message" | "custom_message") || tree.dominates(id_of(target), edit_id) {
237            return false;
238        }
239        // Path target .. parent(edit), oldest first; the edit must lie below its target.
240        let mut path: Vec<&Value> = Vec::new();
241        let mut parent_id = tree.parent_of(edit);
242        while let Some(id) = parent_id {
243            let parent = &tree.by_id[&id];
244            path.insert(0, parent);
245            if id_of(parent) == id_of(target) || path.len() > tree.by_id.len() {
246                break;
247            }
248            parent_id = tree.parent_of(parent);
249        }
250        if path.first().map(|e| id_of(e)) != Some(id_of(target)) {
251            return false;
252        }
253        let next = |index: usize| -> String {
254            match path.get(index + 1) {
255                Some(entry) => id_of(entry).to_string(),
256                None => edit_id.to_string(),
257            }
258        };
259        let mut fork = None;
260        for (index, entry) in path.iter().enumerate() {
261            if tree.child_ids(id_of(entry)).iter().any(|child| *child != next(index)) {
262                fork = Some(index);
263            }
264        }
265        let Some(fork) = fork else { return false };
266        let mut mapping: HashMap<String, String> = HashMap::new();
267        let mut copies: HashMap<String, Value> = HashMap::new();
268        let mut parent = target.get("parentId").cloned().unwrap_or(Value::Null);
269        let edit_base = copy_of.get(edit_id).cloned().unwrap_or_else(|| edit_id.to_string());
270        for original in &path[..=fork] {
271            let original_id = id_of(original).to_string();
272            let source = copy_of
273                .get(&original_id)
274                .cloned()
275                .unwrap_or_else(|| original_id.clone());
276            let base = format!("{source}~{edit_base}");
277            let mut id = base.clone();
278            let mut counter = 2;
279            while ids.contains(&id) {
280                id = format!("{base}~{counter}");
281                counter += 1;
282            }
283            ids.insert(id.clone());
284            mapping.insert(original_id.clone(), id.clone());
285            copy_of.insert(id.clone(), source);
286            let mut copy = (*original).clone();
287            copy["id"] = json!(id);
288            copy["parentId"] = parent;
289            copies.insert(original_id, copy);
290            parent = json!(id);
291        }
292        for copy in copies.values_mut() {
293            remap(copy, &mapping);
294        }
295        // Move the edit's branch onto the copies and redirect its references to them.
296        let head = next(fork);
297        let mut moved: HashSet<String> = HashSet::from([head.clone()]);
298        let mut queue = VecDeque::from([head.clone()]);
299        while let Some(id) = queue.pop_front() {
300            for child in tree.child_ids(&id) {
301                moved.insert(child.clone());
302                queue.push_back(child.clone());
303            }
304        }
305        let old = std::mem::take(entries);
306        for mut entry in old {
307            let id = id_of(&entry).to_string();
308            if moved.contains(&id) {
309                if id == head {
310                    entry["parentId"] = parent.clone();
311                }
312                remap(&mut entry, &mapping);
313            }
314            entries.push(entry);
315            // Each copy goes right after its original, so edit order (the later edit wins) is kept.
316            if let Some(copy) = copies.remove(&id) {
317                entries.push(copy);
318            }
319        }
320        true
321    };
322    let mut budget = 64 * (input.len() + 1);
323    let mut changed = true;
324    while changed && budget > 0 {
325        changed = false;
326        let edits: Vec<String> = entries
327            .iter()
328            .filter(|e| type_of(e) == "context_edit")
329            .map(|e| id_of(e).to_string())
330            .collect();
331        for edit in edits {
332            if budget == 0 {
333                continue;
334            }
335            if split(&edit, &mut entries) {
336                changed = true;
337                budget -= 1;
338            }
339        }
340    }
341    (entries, copy_of)
342}
343
344/// `piUsageEntries`: Pi-reported usage per entry, as Pi's session stats count it.
345fn pi_usage_entries(entries: &[&Value]) -> Vec<(i64, Value)> {
346    let mut out = Vec::new();
347    for entry in entries {
348        let usage = match type_of(entry) {
349            "usage" | "compaction" | "branch_summary" => entry.get("usage"),
350            "message" if matches!(str_of(&entry["message"], "role"), Some("assistant" | "toolResult")) => {
351                entry["message"].get("usage")
352            }
353            _ => None,
354        };
355        if let Some(usage) = usage.filter(|u| !u.is_null()) {
356            out.push((parse_timestamp(entry.get("timestamp"), 0), usage.clone()));
357        }
358    }
359    out
360}
361
362struct ImportPlan {
363    /// The replacement per message entry id, for edits that reach every leaf under the target (`None`: an edit
364    /// without a replacement field).
365    message_edits: HashMap<String, Option<Value>>,
366    unapplied_context_edits: Vec<String>,
367    tails: HashMap<String, Vec<Value>>,
368}
369
370fn plan_import(entries: &[Value], tree: &PiTree) -> ImportPlan {
371    let edits: Vec<&Value> = entries.iter().filter(|e| type_of(e) == "context_edit").collect();
372    let mut message_edits = HashMap::new();
373    let mut unapplied = Vec::new();
374    for edit in &edits {
375        let target = str_of(edit, "targetId").and_then(|t| tree.by_id.get(t));
376        let editable = target.is_some_and(|t| matches!(type_of(t), "message" | "custom_message"));
377        // Edits appear in path order along a single chain, so the later edit wins as in Pi.
378        match target {
379            Some(target) if editable && tree.dominates(id_of(target), id_of(edit)) => {
380                message_edits.insert(id_of(target).to_string(), edit.get("replacement").cloned());
381            }
382            _ => unapplied.push(id_of(edit).to_string()),
383        }
384    }
385    let mut tails = HashMap::new();
386    for compaction in entries.iter().filter(|e| type_of(e) == "compaction") {
387        let id = json!(id_of(compaction));
388        let context = build_context_entries(entries, Leaf::Id(&id));
389        let mut replacements: HashMap<String, Option<Value>> = HashMap::new();
390        for entry in &context {
391            if type_of(entry) == "context_edit" {
392                replacements.insert(
393                    str_of(entry, "targetId").unwrap_or_default().to_string(),
394                    entry.get("replacement").cloned(),
395                );
396            }
397        }
398        // Later edits of kept entries apply on every leaf below the compaction only when they dominate it.
399        for edit in &edits {
400            if tree.dominates(id_of(compaction), id_of(edit)) {
401                replacements.insert(
402                    str_of(edit, "targetId").unwrap_or_default().to_string(),
403                    edit.get("replacement").cloned(),
404                );
405            }
406        }
407        let tail: Vec<Value> = context
408            .iter()
409            .skip(1)
410            .flat_map(|entry| {
411                if type_of(entry) == "compaction" {
412                    return Vec::new();
413                }
414                let edit = replacements.get(id_of(entry)).cloned().flatten();
415                apply_edit(entry_messages(entry), edit.as_ref())
416            })
417            .collect();
418        tails.insert(id_of(compaction).to_string(), tail);
419    }
420    ImportPlan {
421        message_edits,
422        unapplied_context_edits: unapplied,
423        tails,
424    }
425}
426
427fn object(pairs: Vec<(&str, Value)>) -> Map<String, Value> {
428    pairs.into_iter().map(|(k, v)| (k.to_string(), v)).collect()
429}
430
431fn edited_message_body(message: &Value, edit: Option<&Value>) -> Map<String, Value> {
432    match edit {
433        None => object(vec![("type", json!("message")), ("message", message.clone())]),
434        Some(Value::Null) => object(vec![
435            ("type", json!("custom")),
436            ("customType", json!(PI_OMITTED_MESSAGE_CUSTOM_TYPE)),
437            ("data", json!({ "message": message })),
438        ]),
439        Some(replacement) => object(vec![
440            ("type", json!("message")),
441            (
442                "message",
443                session_journal::context::replace_content(message, replacement.get("content")),
444            ),
445        ]),
446    }
447}
448
449fn to_native_entry_body(entry: &Value, plan: &ImportPlan) -> Map<String, Value> {
450    let edit = plan.message_edits.get(id_of(entry)).cloned().flatten();
451    let mut out = Map::new();
452    match type_of(entry) {
453        "message" => return edited_message_body(&entry["message"], edit.as_ref()),
454        "custom_message" => {
455            // `createCustomMessage`.
456            let mut message = Map::new();
457            message.insert("role".into(), json!("custom"));
458            put(&mut message, "customType", entry);
459            put(&mut message, "content", entry);
460            put(&mut message, "display", entry);
461            put(&mut message, "details", entry);
462            message.insert("timestamp".into(), js::date_json(entry.get("timestamp")));
463            return edited_message_body(&Value::Object(message), edit.as_ref());
464        }
465        "compaction" => {
466            out.insert("type".into(), json!("compaction"));
467            put(&mut out, "summary", entry);
468            let tail = plan.tails.get(id_of(entry)).cloned().unwrap_or_default();
469            out.insert("retainedTail".into(), Value::Array(tail));
470            put(&mut out, "tokensBefore", entry);
471            put(&mut out, "details", entry);
472            put(&mut out, "usage", entry);
473            out.insert("fromHook".into(), from_hook(entry));
474        }
475        "branch_summary" => {
476            out.insert("type".into(), json!("branch_summary"));
477            // Pi encodes a root source as the "root" sentinel.
478            match entry.get("fromId") {
479                Some(Value::String(from)) if from == "root" => {
480                    out.insert("fromId".into(), Value::Null);
481                }
482                _ => put(&mut out, "fromId", entry),
483            }
484            put(&mut out, "summary", entry);
485            put(&mut out, "details", entry);
486            put(&mut out, "usage", entry);
487            out.insert("fromHook".into(), from_hook(entry));
488        }
489        "custom" => {
490            out.insert("type".into(), json!("custom"));
491            put(&mut out, "customType", entry);
492            put(&mut out, "data", entry);
493        }
494        other => {
495            let mut data = entry.as_object().cloned().unwrap_or_default();
496            for key in ["type", "id", "parentId", "timestamp"] {
497                data.shift_remove(key);
498            }
499            out.insert("type".into(), json!("custom"));
500            out.insert(
501                "customType".into(),
502                json!(format!("{PI_ENTRY_CUSTOM_TYPE_PREFIX}{other}")),
503            );
504            out.insert("data".into(), Value::Object(data));
505        }
506    }
507    out
508}
509
510/// `fromHook ?? false`.
511fn from_hook(entry: &Value) -> Value {
512    match entry.get("fromHook") {
513        None | Some(Value::Null) => json!(false),
514        Some(value) => value.clone(),
515    }
516}
517
518/// `reproducesPiEntry`: whether export rebuilds exactly this Pi entry from its native entry.
519fn reproduces_pi_entry(original: &Value, native: &Map<String, Value>, timestamp: i64) -> bool {
520    if native.get("type").and_then(Value::as_str) == Some("compaction") {
521        return false;
522    }
523    let mut entry = native.clone();
524    entry.insert("seq".into(), json!(0));
525    entry.insert("timestamp".into(), json!(timestamp));
526    let mut base = Map::new();
527    base.insert("id".into(), native.get("id").cloned().unwrap_or(Value::Null));
528    base.insert(
529        "parentId".into(),
530        native.get("parentId").cloned().unwrap_or(Value::Null),
531    );
532    base.insert("timestamp".into(), json!(jsrt::date::iso_string(timestamp)));
533    native_to_pi_entry(&Value::Object(entry), &base) == *original
534}
535
536/// What an import wrote (`ImportPiSessionResult`).
537#[derive(Clone, Debug, PartialEq)]
538pub struct ImportResult {
539    pub session_id: String,
540    pub path: PathBuf,
541    /// Native entries written for Pi entries (copies are not counted).
542    pub imported: usize,
543    /// Pi entries that could not be imported (always empty: every type is mapped or preserved).
544    pub skipped: Vec<(String, usize)>,
545    /// Unknown Pi entry types kept as `pi-session:<type>` custom entries, with counts, in first-seen order.
546    pub preserved: Vec<(String, usize)>,
547    pub unapplied_context_edits: Vec<String>,
548    pub branch_copies: usize,
549    /// `{root, entries, cost}` of the imported usage.
550    pub usage_root: String,
551    pub usage_entries: usize,
552    pub usage_cost: f64,
553}
554
555impl ImportResult {
556    /// The TypeScript result object.
557    pub fn to_json(&self) -> Value {
558        let counted = |items: &[(String, usize)]| -> Value {
559            items
560                .iter()
561                .map(|(kind, count)| json!({"type": kind, "count": count}))
562                .collect()
563        };
564        json!({
565            "sessionId": self.session_id,
566            "path": self.path.display().to_string(),
567            "imported": self.imported,
568            "skipped": counted(&self.skipped),
569            "preserved": counted(&self.preserved),
570            "unappliedContextEdits": self.unapplied_context_edits,
571            "branchCopies": self.branch_copies,
572            "importedUsage": {"root": self.usage_root, "entries": self.usage_entries,
573                "cost": jsrt::json::number(self.usage_cost)},
574        })
575    }
576}
577
578#[derive(Clone, Debug, PartialEq)]
579pub enum ImportError {
580    /// `PiSessionAlreadyImportedError`: nothing was written; the native copy is `session_id` at `path`.
581    AlreadyImported {
582        pi_session_id: String,
583        session_id: String,
584        path: PathBuf,
585    },
586    Failed(String),
587}
588
589impl std::fmt::Display for ImportError {
590    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
591        match self {
592            ImportError::AlreadyImported {
593                pi_session_id,
594                session_id,
595                path,
596            } => write!(
597                f,
598                "Pi session {pi_session_id} was already imported as native session {session_id}: {}",
599                path.display()
600            ),
601            ImportError::Failed(message) => f.write_str(message),
602        }
603    }
604}
605
606/// The repository clock of an import: the Pi timestamps drive `now()` (ids come from the system generator).
607struct PiClock {
608    time: Arc<Mutex<i64>>,
609}
610
611impl Clock for PiClock {
612    fn now(&mut self) -> i64 {
613        *self.time.lock().unwrap_or_else(PoisonError::into_inner)
614    }
615    fn uuidv7(&mut self, at: i64) -> String {
616        SystemClock.uuidv7(at)
617    }
618    fn next_id(&mut self) -> String {
619        SystemClock.next_id()
620    }
621}
622
623/// The usage ledger's store during an import: it starts empty and keeps what the ledger writes.
624struct Captured(Arc<Mutex<Option<Value>>>);
625
626impl DocumentStore for Captured {
627    fn read(&self) -> Result<Option<Value>, String> {
628        Ok(None)
629    }
630    fn write(&self, document: &Value) -> Result<(), String> {
631        *self.0.lock().unwrap_or_else(PoisonError::into_inner) = Some(document.clone());
632        Ok(())
633    }
634}
635
636/// Called before each commit of an import with its 1-based number; an error fails that commit (the TypeScript tests
637/// make `session.mutate` fail the same way).
638pub type CommitHook<'a> = &'a mut dyn FnMut(usize) -> Result<(), String>;
639
640/// `importPiSession`: the whole tree of the Pi session at `pi_session_path` as a new native session under
641/// `sessions_root` (entry ids, parents and timestamps kept; the `main` tip is the Pi leaf). A failed import leaves
642/// no session file behind.
643pub fn import_pi_session(pi_session_path: &Path, sessions_root: &Path) -> Result<ImportResult, ImportError> {
644    import_pi_session_with(pi_session_path, sessions_root, &mut |_| Ok(()))
645}
646
647/// [`import_pi_session`] with a hook before each commit.
648pub fn import_pi_session_with(
649    pi_session_path: &Path,
650    sessions_root: &Path,
651    hook: CommitHook<'_>,
652) -> Result<ImportResult, ImportError> {
653    let pi_path = PathBuf::from(session_journal::catalog::absolute(
654        &pi_session_path.display().to_string(),
655    ));
656    let shown = pi_path.display().to_string();
657    let file_entries = session_file::load_entries_from_file(&session_file::SystemEnv, &shown)
658        .map_err(|e| ImportError::Failed(format!("{shown}: {e}")))?;
659    let header = match file_entries.first() {
660        Some(header) if type_of(header) == "session" => header.clone(),
661        _ => {
662            return Err(ImportError::Failed(format!(
663                "Not a Pi session file (missing session header): {shown}"
664            )));
665        }
666    };
667    let cwd = str_of(&header, "cwd").unwrap_or_default().to_string();
668    // In memory: Pi's format migrations apply without rewriting the source file.
669    let manager = SessionManager::in_memory(Box::new(SystemEnv), &cwd, None, Some(file_entries))
670        .map_err(|e| ImportError::Failed(e.to_string()))?;
671    let pi_entries: Vec<Value> = manager.entries().into_iter().cloned().collect();
672    let pi_session_id = str_of(&header, "id").unwrap_or_default().to_string();
673    let session_id = native_session_id_for_pi_session(&pi_session_id);
674    let (split, copy_of) = split_branch_local_edits(&pi_entries);
675    let tree = PiTree::new(&split);
676    let plan = plan_import(&split, &tree);
677    let pi_by_id: HashMap<&str, &Value> = pi_entries.iter().map(|e| (id_of(e), e)).collect();
678
679    let now = jsrt::date::now_ms();
680    let time = Arc::new(Mutex::new(parse_timestamp(header.get("timestamp"), now)));
681    let set_time = |at: i64| *time.lock().unwrap_or_else(PoisonError::into_inner) = at;
682    let clock: SharedClock = Arc::new(Mutex::new(PiClock { time: time.clone() }));
683    let repo = SessionRepo::new(sessions_root, clock);
684    if let Some(existing) = repo.list(None).into_iter().find(|m| m.id == session_id) {
685        return Err(ImportError::AlreadyImported {
686            pi_session_id,
687            session_id,
688            path: existing.path,
689        });
690    }
691    let mut session = repo
692        .create(&cwd, Some(&session_id), None)
693        .map_err(ImportError::Failed)?;
694    let path = session.metadata().path.clone();
695    let mut commits = 0;
696    let mut commit = |session: &mut session_journal::Session, writes: &[Write]| -> Result<(), String> {
697        commits += 1;
698        hook(commits)?;
699        session.commit(writes).map(drop)
700    };
701    let mut written = || -> Result<ImportResult, String> {
702        let mut preserved: Vec<(String, usize)> = Vec::new();
703        let mut imported = 0;
704        let mut at = *time.lock().unwrap_or_else(PoisonError::into_inner);
705        for entry in tree.insertion_order(&split) {
706            let id = id_of(&entry).to_string();
707            let copied = copy_of.get(&id);
708            let kind = type_of(&entry).to_string();
709            if copied.is_none() && !KNOWN_PI_ENTRY_TYPES.contains(&kind.as_str()) {
710                match preserved.iter_mut().find(|(k, _)| *k == kind) {
711                    Some((_, count)) => *count += 1,
712                    None => preserved.push((kind, 1)),
713                }
714            }
715            at = parse_timestamp(entry.get("timestamp"), at);
716            set_time(at);
717            let mut native = to_native_entry_body(&entry, &plan);
718            native.insert("id".into(), json!(id));
719            native.insert(
720                "parentId".into(),
721                tree.parent_of(&entry).map_or(Value::Null, Value::from),
722            );
723            let mut writes = vec![Write::Entry(native.clone())];
724            match copied {
725                Some(original) => writes.push(Write::set(PI_COPY_OF, &id, json!(original))),
726                None => {
727                    // Compare with the Pi entry as written: a split may have re-parented or re-targeted this one.
728                    let original = pi_by_id.get(id.as_str()).copied().unwrap_or(&Value::Null);
729                    if !reproduces_pi_entry(original, &native, at) {
730                        writes.push(Write::set(PI_ORIGINAL, &id, original.clone()));
731                    }
732                    imported += 1;
733                }
734            }
735            commit(&mut session, &writes)?;
736        }
737
738        // Usage Pi reported, as one imported historical root of the session's usage ledger.
739        let usage_root = pi_import_usage_root(&pi_session_id);
740        let refs: Vec<&Value> = pi_entries.iter().collect();
741        let reported = pi_usage_entries(&refs);
742        if !reported.is_empty() {
743            let captured = Arc::new(Mutex::new(None));
744            let ledger = UsageLedger::new(Box::new(Captured(captured.clone())), UsageOptions::default())?;
745            let calls: Vec<(f64, Measurement, Option<String>)> = reported
746                .iter()
747                .map(|(at, usage)| {
748                    let measured = Measurement {
749                        input_tokens: usage["input"].as_f64(),
750                        output_tokens: usage["output"].as_f64(),
751                        total_tokens: usage["totalTokens"].as_f64(),
752                        cost: usage["cost"]["total"].as_f64(),
753                        wall_ms: Some(0.0),
754                    };
755                    (*at as f64, measured, None)
756                })
757                .collect();
758            ledger.import_history(&usage_root, "pi", &calls)?;
759            let document = captured.lock().unwrap_or_else(PoisonError::into_inner).take();
760            if let Some(document) = document {
761                commit(
762                    &mut session,
763                    &[Write::set(USAGE_ROOT.namespace, USAGE_ROOT.key, document)],
764                )?;
765            }
766        }
767
768        // Derived state at the Pi leaf: tip, labels, name, and the lane configuration Pi would resume with.
769        let leaf = manager
770            .leaf_id()
771            .and_then(Value::as_str)
772            .filter(|leaf| tree.by_id.contains_key(*leaf));
773        let mut writes = vec![Write::set(BRANCH_TIP, "main", leaf.map_or(Value::Null, Value::from))];
774        for entry in &pi_entries {
775            if let Some(label) = manager.label(id_of(entry)) {
776                writes.push(Write::set(ENTRY_LABEL, id_of(entry), label.clone()));
777            }
778        }
779        if let Some(name) = manager.session_name() {
780            writes.push(Write::set(SESSION_NAME, "", json!(name)));
781        }
782        let context = manager.build_session_context();
783        if let Some(model) = &context.model {
784            let mut configuration = Map::new();
785            configuration.insert(
786                "model".into(),
787                json!({"provider": model["provider"], "modelId": model["modelId"]}),
788            );
789            if let Some(level) = &context.thinking_level {
790                configuration.insert("thinkingLevel".into(), level.clone());
791            }
792            // Tools are not recorded by Pi; the host activates its own tool set when it opens the lane.
793            configuration.insert("activeToolNames".into(), json!([]));
794            writes.push(Write::set(LANE_CONFIG, "main", Value::Object(configuration)));
795            writes.push(Write::set(
796                LANE_STATE,
797                "main",
798                json!({"currentOperationId": null, "lastOperationId": null, "inbox": []}),
799            ));
800        }
801        commit(&mut session, &writes)?;
802        let cost = reported.iter().fold(0.0, |total, (_, usage)| {
803            total + usage["cost"]["total"].as_f64().unwrap_or(0.0)
804        });
805        Ok(ImportResult {
806            session_id: session_id.clone(),
807            path: path.clone(),
808            imported,
809            skipped: Vec::new(),
810            preserved,
811            unapplied_context_edits: plan.unapplied_context_edits.clone(),
812            branch_copies: copy_of.len(),
813            usage_root,
814            usage_entries: reported.len(),
815            usage_cost: cost,
816        })
817    };
818    let result = written();
819    drop(session);
820    result.map_err(|error| {
821        // Never leave a partial import behind: it would block a retry.
822        let _ = std::fs::remove_file(&path);
823        ImportError::Failed(error)
824    })
825}
826
827/// What an export wrote (`ExportNativeSessionToPiResult`).
828#[derive(Clone, Debug, PartialEq)]
829pub struct ExportResult {
830    pub session_id: String,
831    pub path: PathBuf,
832    /// Pi entries written (without the header).
833    pub entries: usize,
834}
835
836/// `piLabelsOf`: the labels Pi's label entries resolve to, in first-set order.
837fn pi_labels_of(entries: &[Value]) -> Vec<(String, String)> {
838    let mut labels: Vec<(String, String)> = Vec::new();
839    for entry in entries.iter().filter(|e| type_of(e) == "label") {
840        let target = str_of(entry, "targetId").unwrap_or_default().to_string();
841        let label = entry
842            .get("label")
843            .filter(|l| jsrt::value::truthy(Some(l)))
844            .and_then(Value::as_str);
845        match label {
846            Some(label) => match labels.iter_mut().find(|(t, _)| *t == target) {
847                Some((_, existing)) => *existing = label.to_string(),
848                None => labels.push((target, label.to_string())),
849            },
850            None => labels.retain(|(t, _)| *t != target),
851        }
852    }
853    labels
854}
855
856/// `piNameOf`: the last `session_info` entry's trimmed name.
857fn pi_name_of(entries: &[Value]) -> Option<String> {
858    let entry = entries.iter().rev().find(|e| type_of(e) == "session_info")?;
859    entry
860        .get("name")
861        .and_then(Value::as_str)
862        .map(jsrt::string::trim)
863        .filter(|name| !name.is_empty())
864        .map(str::to_string)
865}
866
867/// `exportNativeSessionToPi`: the native session at `session_path` (in `<sessionsRoot>/<cwd-dir>/`) written whole
868/// as a Pi session at `output_path`, which must not exist. Pi resumes at its last entry, the native `main` tip;
869/// labels, the name, and the `main` lane's model and thinking level that differ from what the entries say are
870/// appended after it.
871pub fn export_native_session_to_pi(session_path: &Path, output_path: &Path) -> Result<ExportResult, String> {
872    let path = PathBuf::from(session_journal::catalog::absolute(&session_path.display().to_string()));
873    let root = path.parent().and_then(Path::parent).unwrap_or(Path::new("/"));
874    let repo = SessionRepo::new(root, SystemClock::shared());
875    let metadata = repo
876        .list(None)
877        .into_iter()
878        .find(|m| m.path == path)
879        .ok_or_else(|| format!("Not a native session in its session directory: {}", path.display()))?;
880    let session = repo.open(&metadata)?;
881    let converted = native_session_as_pi(&session, true);
882    let state = session.state();
883    let natives = state.entries();
884    let native_ids: HashSet<&str> = natives.iter().map(id_of).collect();
885    let mut entries = converted.entries;
886    let mut ids: HashSet<String> = entries.iter().map(|e| id_of(e).to_string()).collect();
887    let newest = natives
888        .iter()
889        .filter_map(|e| e["timestamp"].as_i64())
890        .fold(metadata.created_at, i64::max);
891    let mut stamp = json!(jsrt::date::iso_string(newest));
892    let mut leaf: Option<String> = entries.last().map(|e| id_of(e).to_string());
893    let mut append = |entries: &mut Vec<Value>, leaf: &mut Option<String>, stamp: &Value, entry: Value, kind: &str| {
894        let mut id = format!("ultron-{kind}");
895        let mut counter = 1;
896        while ids.contains(&id) {
897            id = format!("ultron-{kind}-{counter}");
898            counter += 1;
899        }
900        ids.insert(id.clone());
901        let mut out = entry.as_object().cloned().unwrap_or_default();
902        out.insert("id".into(), json!(id));
903        out.insert("parentId".into(), leaf.clone().map_or(Value::Null, Value::from));
904        out.insert("timestamp".into(), stamp.clone());
905        entries.push(Value::Object(out));
906        *leaf = Some(id);
907    };
908
909    // Pi resumes at its last entry: make that the native main tip.
910    if let Some(tip) = &converted.tip_id
911        && converted.leaf_id != leaf
912    {
913        if natives.iter().any(|e| str_of(e, "parentId") == Some(tip.as_str())) {
914            leaf = converted.leaf_id.clone();
915            append(
916                &mut entries,
917                &mut leaf,
918                &stamp,
919                json!({"type": "custom", "customType": PI_LEAF_MARKER_CUSTOM_TYPE}),
920                "leaf",
921            );
922        } else {
923            let items = converted.tip_items;
924            let moved: HashSet<String> = items.iter().map(|item| id_of(item).to_string()).collect();
925            entries.retain(|e| !moved.contains(id_of(e)));
926            entries.extend(items);
927            leaf = converted.leaf_id.clone();
928        }
929    }
930    if let Some(found) = entries.iter().find(|e| Some(id_of(e)) == leaf.as_deref()) {
931        stamp = found["timestamp"].clone();
932    }
933
934    // Labels set natively after import (or never recorded as Pi entries).
935    let pi_labels = pi_labels_of(&entries);
936    let native_labels: Vec<(String, String)> = state
937        .scan_values(ENTRY_LABEL, "")
938        .into_iter()
939        .filter_map(|v| v.value.as_str().map(|l| (v.key.clone(), l.to_string())))
940        .collect();
941    let mut targets: Vec<String> = pi_labels.iter().map(|(t, _)| t.clone()).collect();
942    for (target, _) in &native_labels {
943        if !targets.contains(target) {
944            targets.push(target.clone());
945        }
946    }
947    for target in targets {
948        let label = native_labels.iter().find(|(t, _)| *t == target).map(|(_, l)| l.clone());
949        let pi = pi_labels.iter().find(|(t, _)| *t == target).map(|(_, l)| l.clone());
950        if pi == label || !native_ids.contains(target.as_str()) {
951            continue;
952        }
953        let mut entry = json!({"type": "label", "targetId": target});
954        if let Some(label) = label {
955            entry["label"] = json!(label);
956        }
957        append(&mut entries, &mut leaf, &stamp, entry, "label");
958    }
959    let name = session.name();
960    if pi_name_of(&entries) != name {
961        append(
962            &mut entries,
963            &mut leaf,
964            &stamp,
965            json!({"type": "session_info", "name": name.unwrap_or_default()}),
966            "name",
967        );
968    }
969
970    if let Some(configuration) = session.value(LANE_CONFIG, "main").cloned() {
971        let leaf_value = leaf.clone().map(Value::from);
972        let resolved = build_session_context(
973            &entries,
974            match &leaf_value {
975                Some(id) => Leaf::Id(id),
976                None => Leaf::Root,
977            },
978        );
979        let model = &configuration["model"];
980        let resolved_model = resolved.model.clone().unwrap_or(Value::Null);
981        if resolved_model.get("provider") != model.get("provider")
982            || resolved_model.get("modelId") != model.get("modelId")
983        {
984            let mut entry = json!({"type": "model_change"});
985            for (key, value) in model.as_object().into_iter().flatten() {
986                entry[key] = value.clone();
987            }
988            append(&mut entries, &mut leaf, &stamp, entry, "model");
989        }
990        if resolved.thinking_level.as_ref() != configuration.get("thinkingLevel") {
991            let mut entry = json!({"type": "thinking_level_change"});
992            if let Some(level) = configuration.get("thinkingLevel") {
993                entry["thinkingLevel"] = level.clone();
994            }
995            append(&mut entries, &mut leaf, &stamp, entry, "thinking");
996        }
997    }
998
999    let header = json!({
1000        "type": "session", "version": PI_SESSION_VERSION, "id": metadata.id,
1001        "timestamp": jsrt::date::iso_string(metadata.created_at), "cwd": metadata.cwd,
1002    });
1003    let output = PathBuf::from(session_journal::catalog::absolute(&output_path.display().to_string()));
1004    if let Some(parent) = output.parent() {
1005        std::fs::create_dir_all(parent).map_err(|e| format!("{}: {e}", parent.display()))?;
1006    }
1007    let mut content = String::new();
1008    for line in std::iter::once(&header).chain(entries.iter()) {
1009        content.push_str(&serde_json::to_string(line).map_err(|e| e.to_string())?);
1010        content.push('\n');
1011    }
1012    use std::io::Write as _;
1013    use std::os::unix::fs::OpenOptionsExt;
1014    let mut file = std::fs::OpenOptions::new()
1015        .write(true)
1016        .create_new(true)
1017        .mode(0o600)
1018        .open(&output)
1019        .map_err(|e| export_open_error(&e, &output))?;
1020    file.write_all(content.as_bytes())
1021        .map_err(|e| format!("{}: {e}", output.display()))?;
1022    Ok(ExportResult {
1023        session_id: metadata.id.clone(),
1024        path: output,
1025        entries: entries.len(),
1026    })
1027}
1028
1029/// Node's `open(..., "wx")` error text.
1030fn export_open_error(error: &std::io::Error, path: &Path) -> String {
1031    if error.kind() == std::io::ErrorKind::AlreadyExists {
1032        return format!("EEXIST: file already exists, open '{}'", path.display());
1033    }
1034    format!("{error}: open '{}'", path.display())
1035}