supercode_interchange/

session_tree.rs

//! P5-5 (design §2 module 21 `session.tree`: "D5 in-place tree,
//! rewind-anywhere, branch summaries, entry labels"; §2.1 D-6 `session.tree →
//! core.session(tree-addressable transcript)`; §2.2 C7; §5.2 P5 row 5:
//! "loaders are already tree-aware (C7 resolution); adds in-place
//! rewind/branch/label on the native store").
//!
//! # What this is
//!
//! [`Session`](crate::session::Session) and the composition layer's session store
//! already carry a **linear** transcript — `messages: Vec<ChatMessage>` — and
//! the loaders already reconstruct MULTI-FILE tree structure on import
//! (`Session::reconstruct_tree`, the C7 resolution's "import-side preserved
//! only"). What was missing is the native, IN-PLACE tree: the ability to
//! address any turn by id, rewind the active pointer to an earlier one
//! without deleting anything, explicitly fork a new branch, attach a short
//! summary to an off-path branch, and label any node — all on supercode's
//! OWN session store (CC/PI's defining in-place-tree feature, catalog D5).
//!
//! # C7 — tree-with-linear-projection
//!
//! Conflict 7 (design §2.2): `session.tree`'s in-place DAG is structurally
//! incompatible with a strictly-linear export target (the CX rollout shape).
//! The resolution the design commits to is **core stays
//! tree-with-linear-projection**: [`SessionTree::linear_projection`] always
//! derives the active branch's message sequence deterministically by walking
//! parent pointers from the root to the active leaf — this is what
//! [`crate::session::Session::messages`] / the agent loop / exporters keep
//! consuming unchanged. A tree session with zero branches (the common case,
//! and the ONLY case before this module's operations are ever invoked) is the
//! *degenerate single-path tree*: its projection is byte-for-byte the same
//! sequence [`crate::session::Session::messages`] already held — see
//! the linear-projection regression test.
//!
//! Exporting a branched tree to a linear-only format is
//! [`SessionTree::splice_for_linear_export`]: it returns the active path
//! (spliced, exactly like today's linear export) plus a
//! [`BranchSummary`] for every OFF-path branch. Nothing is deleted by this —
//! the full tree (every node of every branch) stays intact in
//! [`SessionTree`] / its `<name>.tree.json` sidecar
//! (through the session store's explicit tree writer); the summary is an added,
//! human-readable POINTER (`BranchSummary::branch` names which branch the
//! full data still lives under), never a replacement for it (§1.13 lossless).
//!
//! # Lossless rewind (§1.13)
//!
//! [`SessionTree::rewind`] never deletes a node. Moving the active branch's
//! leaf pointer backward leaves every node — including the ones the pointer
//! used to point through — exactly where it was in the DAG. Whenever the
//! rewind actually moves the pointer off the branch's previous leaf, the OLD
//! leaf is preserved under a freshly-named sibling branch (so it stays
//! independently addressable/enumerable, not merely "still linked in but
//! orphaned from every named branch") — see
//! the rewind-preservation regression test.
//! The next turn appended after a rewind becomes a NEW child of the rewind
//! target, i.e. a sibling of whatever used to follow it — exactly "rewind =
//! fork at the rewind point" (module 21's row).
//!
//! # Off by default / byte-identical
//!
//! Nothing in this module is on any hot path. A [`SessionTree`] is only ever
//! constructed by an explicit caller (never implicitly by
//! [`crate::session::Session`] loading/saving, never by a runtime agent loop) and its sidecar
//! (`<name>.tree.json`) is only ever written by an explicit
//! an explicit session-store tree-write call — so a session that never
//! invokes any tree operation has no `.tree.json` file at all, and every
//! existing linear read/write path (`Session::to_native_jsonl`/
//! `from_native_str`, `SessionStore::save`/`load`) is untouched
//! byte-for-byte. `capabilities.session_tree.enabled` (§3.1, module 21;
//! exposed by the composition layer's `SessionTree` module switch and runtime
//! configuration flags for tree enablement, summaries, and labels, allowing a caller to
//! gate on — this module's own API has no runtime dependency on that flag
//! (a library caller can always use [`SessionTree`] directly, exactly like
//! native store forking does not gate on any capability
//! either).

use std::collections::{BTreeMap, BTreeSet};

use serde::{Deserialize, Serialize};

use crate::sidecar::NativeTurn;
use crate::{ChatMessage, InterchangeError as Error, Result};

/// A tree-node id. Assigned by `SessionTree`'s monotonic allocator — a
/// counter (`"n0"`, `"n1"`, ...), not content-derived or random, so ids are
/// deterministic and trivially testable, and so two nodes can never collide.
pub type NodeId = String;

/// One addressable turn in the tree (module 21's "entry"). Carries the full
/// [`ChatMessage`] (this IS the full-fidelity source for a branched session
/// — see the module doc's "off by default" note: the plain linear transcript
/// file remains the record for an UNBRANCHED session; this sidecar only
/// exists once a tree operation actually ran), its parent/children links,
/// and an optional human/agent-set label (module 21 "entry labels").
///
/// **Lossless persistence (§1.13).** [`Self::message`] is a plain
/// [`ChatMessage`] in memory, but this type's `Serialize`/`Deserialize`
/// impls (below) are hand-written rather than derived: they route the
/// message through [`NativeTurn`] — the SAME full-fidelity wire record
/// [`crate::session::Session::to_native_jsonl_v2`] already uses to persist
/// live-appended turns — instead of `ChatMessage`'s own wire `Serialize`.
/// `ChatMessage`'s hand-rolled wire serde (`message.rs:57-79`) is deliberately
/// lossy: it OMITS `metadata` entirely (never meant to reach a provider
/// request body) and collapses `content` whenever `content_parts` is also
/// set. That lossy shape is correct for an outbound API request; it is
/// WRONG for this sidecar, which is the ONLY durable record of an off-path
/// branch's messages (a rewound-past branch has no other file backing it).
/// `NativeTurn` was built for exactly this distinction (see its module doc:
/// "the sidecar must retain what the wire serde must drop") — reusing it
/// here, rather than inventing a second parallel lossless representation,
/// keeps `TreeNode.message` byte-for-byte round-trippable: `metadata` intact,
/// `content` AND `content_parts` both intact (independently — `NativeTurn`
/// does not collapse one into the other).
#[derive(Debug, Clone)]
pub struct TreeNode {
    /// This node's id.
    pub id: NodeId,
    /// The parent node id. `None` only for the tree's root.
    pub parent: Option<NodeId>,
    /// Child node ids, in the order they were created. More than one entry
    /// here IS a branch point (multiple turns following the same parent).
    pub children: Vec<NodeId>,
    /// The turn itself.
    pub message: ChatMessage,
    /// A human/agent-set label on this node (module 21 "entry labels"),
    /// e.g. a checkpoint name or an annotation. `None` (the default) —
    /// unlabeled.
    pub label: Option<String>,
    /// Unix-ms wall-clock time this node was created.
    pub created_at_ms: i64,
}

/// The on-disk shape of a [`TreeNode`]: identical except `message` is a
/// [`NativeTurn`] rather than a plain [`ChatMessage`] — see [`TreeNode`]'s
/// doc comment for why. Private: only [`TreeNode`]'s own `Serialize`/
/// `Deserialize` impls (below) construct one.
#[derive(Serialize, Deserialize)]
struct TreeNodeWire {
    id: NodeId,
    parent: Option<NodeId>,
    #[serde(default)]
    children: Vec<NodeId>,
    message: NativeTurn,
    #[serde(default)]
    label: Option<String>,
    #[serde(default)]
    created_at_ms: i64,
}

impl From<&TreeNode> for TreeNodeWire {
    fn from(n: &TreeNode) -> Self {
        // Build the `NativeTurn` by hand rather than via its
        // `From<&ChatMessage>` impl: that impl stamps `ts` with the CURRENT
        // wall-clock time (`sidecar.rs`'s `now_rfc3339()`), which would make
        // re-saving an already-loaded, unmodified tree produce different
        // bytes each time — breaking this sidecar's save→load→save
        // byte-identity guarantee. `ts` is derived deterministically from
        // the node's own `created_at_ms` instead (and is write-only for this
        // use: `NativeTurn::into_message` discards `ts`/`supercode_turn`
        // on the way back, so no information depends on its exact value —
        // only on it being stable).
        let message = NativeTurn {
            supercode_turn: 1,
            ts: crate::sidecar::ms_to_rfc3339(n.created_at_ms),
            role: n.message.role,
            content: n.message.content.clone(),
            content_parts: n.message.content_parts.clone(),
            tool_calls: n.message.tool_calls.clone(),
            tool_call_id: n.message.tool_call_id.clone(),
            name: n.message.name.clone(),
            metadata: n.message.metadata.clone(),
        };
        TreeNodeWire {
            id: n.id.clone(),
            parent: n.parent.clone(),
            children: n.children.clone(),
            message,
            label: n.label.clone(),
            created_at_ms: n.created_at_ms,
        }
    }
}

impl From<TreeNodeWire> for TreeNode {
    fn from(w: TreeNodeWire) -> Self {
        TreeNode {
            id: w.id,
            parent: w.parent,
            children: w.children,
            message: w.message.into_message(),
            label: w.label,
            created_at_ms: w.created_at_ms,
        }
    }
}

impl Serialize for TreeNode {
    fn serialize<S: serde::Serializer>(&self, ser: S) -> std::result::Result<S::Ok, S::Error> {
        TreeNodeWire::from(self).serialize(ser)
    }
}

impl<'de> Deserialize<'de> for TreeNode {
    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> std::result::Result<Self, D::Error> {
        TreeNodeWire::deserialize(de).map(TreeNode::from)
    }
}

/// A branch-carried summary (module 21 "branch summaries", the C7
/// lossy→sidecar-backed path): a short human-readable digest of a branch,
/// paired with the pointer back to the full branch data (`branch`, a key
/// into [`SessionTree::branches`] — the full nodes never move or get
/// deleted, so this is always resolvable back to the source, §1.13).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BranchSummary {
    /// The short summary text.
    pub summary: String,
    /// The node id this summary was generated as-of (normally the branch's
    /// leaf at generation time).
    pub node_id: NodeId,
    /// Which branch (a key into [`SessionTree::branches`]) this summary
    /// describes — the recoverability pointer: the full branch is still
    /// right there, keyed by this name, never dropped.
    pub branch: String,
    /// Which model produced this summary, if generated via
    /// [`BranchSummarizer`] (mirrors `reduce/summarize.rs`'s
    /// `SpanSummary::model_id`). `None` for a caller-provided summary text.
    #[serde(default)]
    pub model_id: Option<String>,
    /// Unix-ms wall-clock time the summary was generated.
    #[serde(default)]
    pub created_at_ms: i64,
}

/// A named pointer into the tree: `leaf` is the node this branch currently
/// ends at (its "current-leaf pointer", module 21's phrase). `None` only for
/// a brand-new, still-empty tree's implicit branch before any node exists.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Branch {
    /// The branch's name (unique within [`SessionTree::branches`]).
    pub name: String,
    /// The node this branch currently points at (its leaf/current position).
    pub leaf: Option<NodeId>,
    /// An attached summary (module 21 "branch summaries"), set by
    /// [`SessionTree::summarize_branch`]/[`SessionTree::summarize_branch_with`].
    /// `None` — the overwhelmingly common case (a branch nobody has
    /// summarized, e.g. the active one).
    #[serde(default)]
    pub summary: Option<BranchSummary>,
    /// Unix-ms wall-clock time this branch was created.
    #[serde(default)]
    pub created_at_ms: i64,
}

/// The default/active branch name for a session that has never explicitly
/// branched — the degenerate single-path tree's one branch.
pub const MAIN_BRANCH: &str = "main";

/// The native in-place conversation tree (module 21). See the module doc
/// comment for the full design (C7 tree-with-linear-projection, lossless
/// rewind, branch summaries).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionTree {
    /// Every node in the tree, keyed by id. A [`BTreeMap`] (not a
    /// [`std::collections::HashMap`]) so iteration/serialization order is
    /// deterministic — load-bearing for the lossless round-trip tests
    /// (`assert_eq!` on two independently-loaded trees must not flake on
    /// hash-iteration order).
    pub nodes: BTreeMap<NodeId, TreeNode>,
    /// The tree's single root node id. `None` only for a brand-new, empty
    /// tree.
    pub root: Option<NodeId>,
    /// Every branch, keyed by name. Always has at least [`MAIN_BRANCH`] once
    /// [`SessionTree::new`]/[`SessionTree::from_linear`] have run.
    pub branches: BTreeMap<String, Branch>,
    /// The currently-active branch name — a key into [`Self::branches`].
    pub active_branch: String,
    /// The next id [`Self::alloc_id`] will hand out.
    #[serde(default)]
    next_id: u64,
}

impl Default for SessionTree {
    fn default() -> Self {
        Self::new()
    }
}

impl SessionTree {
    /// A brand-new, empty tree: no nodes, one branch ([`MAIN_BRANCH`]) with
    /// no leaf yet, active.
    pub fn new() -> Self {
        let mut branches = BTreeMap::new();
        branches.insert(
            MAIN_BRANCH.to_string(),
            Branch {
                name: MAIN_BRANCH.to_string(),
                leaf: None,
                summary: None,
                created_at_ms: 0,
            },
        );
        SessionTree {
            nodes: BTreeMap::new(),
            root: None,
            branches,
            active_branch: MAIN_BRANCH.to_string(),
            next_id: 0,
        }
    }

    /// Build a tree from an existing LINEAR message sequence — the
    /// degenerate single-path tree (C7): each message becomes a node,
    /// chained to the previous one, with [`MAIN_BRANCH`]'s leaf ending at the
    /// last message. [`Self::linear_projection`] on the result is
    /// byte-for-byte `messages` (see
    /// the linear-projection regression test) —
    /// this is the bridge a caller uses to materialize a tree lazily out of
    /// an ordinary [`crate::session::Session::messages`], the FIRST time a
    /// tree operation (rewind/branch/label) is actually invoked on it.
    /// `created_at_ms` is stamped on every synthesized node (a single
    /// timestamp for the whole import, since the source linear messages
    /// carry no per-turn timestamp of their own).
    pub fn from_linear(messages: &[ChatMessage], created_at_ms: i64) -> Self {
        let mut tree = Self::new();
        for m in messages {
            tree.append_message(m.clone(), created_at_ms);
        }
        tree
    }

    /// Allocate a fresh, never-before-used node id. Collision-checked against
    /// [`Self::nodes`] rather than blindly trusting [`Self::next_id`]: a
    /// sidecar hand-edited (or written by an older/different process) can
    /// deserialize with `next_id` behind the actual highest-used id — most
    /// simply, `#[serde(default)]` on `next_id` means a sidecar that omits
    /// the field entirely loads as `next_id: 0`, and the very next append
    /// would otherwise hand out `"n0"` again and [`std::collections::BTreeMap::insert`]
    /// would SILENTLY REPLACE the existing root. Looping past any id that's
    /// already occupied makes that impossible regardless of how `next_id`
    /// got out of sync with the actual node set.
    fn alloc_id(&mut self) -> NodeId {
        loop {
            let id = format!("n{}", self.next_id);
            self.next_id += 1;
            if !self.nodes.contains_key(&id) {
                return id;
            }
        }
    }

    /// Look up a node by id.
    pub fn node(&self, id: &str) -> Option<&TreeNode> {
        self.nodes.get(id)
    }

    fn require_node(&self, id: &str) -> Result<&TreeNode> {
        self.nodes
            .get(id)
            .ok_or_else(|| Error::Other(format!("session tree has no node `{id}`")))
    }

    fn require_branch(&self, name: &str) -> Result<&Branch> {
        self.branches
            .get(name)
            .ok_or_else(|| Error::Other(format!("session tree has no branch `{name}`")))
    }

    /// Append a new turn as a child of the ACTIVE branch's current leaf
    /// (ordinary turn continuation — the tree's analog of pushing onto
    /// [`crate::session::Session::messages`]). Returns the new node's id.
    /// This is the only way [`Self::root`] is ever set (on the very first
    /// node the whole tree ever gets).
    pub fn append_message(&mut self, message: ChatMessage, created_at_ms: i64) -> NodeId {
        let parent = self
            .branches
            .get(&self.active_branch)
            .and_then(|b| b.leaf.clone());
        let id = self.alloc_id();
        self.nodes.insert(
            id.clone(),
            TreeNode {
                id: id.clone(),
                parent: parent.clone(),
                children: Vec::new(),
                message,
                label: None,
                created_at_ms,
            },
        );
        match &parent {
            Some(p) => {
                if let Some(pn) = self.nodes.get_mut(p) {
                    pn.children.push(id.clone());
                }
            }
            None => self.root = Some(id.clone()),
        }
        if let Some(b) = self.branches.get_mut(&self.active_branch) {
            b.leaf = Some(id.clone());
        }
        id
    }

    /// A branch name derived from `base` that doesn't collide with any
    /// existing branch — `base`, or `base-2`, `base-3`, ... the first free
    /// one. Used by [`Self::rewind`] (to auto-name the preserved sibling) and
    /// by [`Self::branch`] when the caller passes no explicit name.
    fn fresh_branch_name(&self, base: &str) -> String {
        if !self.branches.contains_key(base) {
            return base.to_string();
        }
        let mut n = 2u64;
        loop {
            let candidate = format!("{base}-{n}");
            if !self.branches.contains_key(&candidate) {
                return candidate;
            }
            n += 1;
        }
    }

    /// Rewind-anywhere (module 21): move the ACTIVE branch's current-leaf
    /// pointer back to `node_id`. `node_id` must already exist in the tree —
    /// an unknown id is an error, never silently ignored or treated as a
    /// no-op (the "never corrupt/dangling" requirement).
    ///
    /// **Lossless.** No node is ever deleted by this. If the active branch's
    /// leaf was pointing somewhere other than `node_id` before the call, that
    /// OLD leaf — and therefore the whole path back to (but not past) the
    /// nearest still-referenced ancestor — is preserved under a fresh
    /// sibling branch name (using the internal fresh-name allocator) so it stays
    /// independently addressable, not merely still-linked-in-but-unnamed.
    /// Returns that sibling branch's name, or `None` if the rewind was a
    /// no-op (`node_id` was already the active leaf, or the branch had no
    /// leaf yet).
    ///
    /// The next [`Self::append_message`] after a rewind creates a NEW child
    /// of `node_id` — a sibling of whatever child used to follow it, exactly
    /// "rewind = fork at the rewind point."
    pub fn rewind(&mut self, node_id: &str, timestamp_ms: i64) -> Result<Option<String>> {
        self.require_node(node_id)?;
        let old_leaf = self
            .branches
            .get(&self.active_branch)
            .and_then(|b| b.leaf.clone());
        let preserved = match &old_leaf {
            Some(old) if old != node_id => {
                let name = self.fresh_branch_name(&format!("{}-rewound", self.active_branch));
                self.branches.insert(
                    name.clone(),
                    Branch {
                        name: name.clone(),
                        leaf: Some(old.clone()),
                        summary: None,
                        created_at_ms: timestamp_ms,
                    },
                );
                Some(name)
            }
            _ => None,
        };
        if let Some(b) = self.branches.get_mut(&self.active_branch) {
            b.leaf = Some(node_id.to_string());
        }
        Ok(preserved)
    }

    /// Explicit branch (module 21): fork the conversation at `from_node`,
    /// creating a NEW branch (named `name`, or an auto-generated
    /// `"branch-N"` if `None`) whose leaf starts at `from_node`, and switch
    /// the active branch to it. Errors if `from_node` doesn't exist, or if
    /// `name` is `Some` and already taken (an explicit name collision is a
    /// caller mistake worth surfacing, unlike [`Self::rewind`]'s
    /// auto-generated names which always self-disambiguate).
    pub fn branch(
        &mut self,
        from_node: &str,
        name: Option<String>,
        timestamp_ms: i64,
    ) -> Result<String> {
        self.require_node(from_node)?;
        let name = match name {
            Some(n) => {
                if self.branches.contains_key(&n) {
                    return Err(Error::Other(format!(
                        "session tree already has a branch named `{n}`"
                    )));
                }
                n
            }
            None => self.fresh_branch_name("branch"),
        };
        self.branches.insert(
            name.clone(),
            Branch {
                name: name.clone(),
                leaf: Some(from_node.to_string()),
                summary: None,
                created_at_ms: timestamp_ms,
            },
        );
        self.active_branch = name.clone();
        Ok(name)
    }

    /// Switch the active branch to an already-existing one. Errors if `name`
    /// doesn't name a branch (no silent fallback to `main`).
    pub fn switch_branch(&mut self, name: &str) -> Result<()> {
        self.require_branch(name)?;
        self.active_branch = name.to_string();
        Ok(())
    }

    /// Label (module 21 "entry labels") a node — a human/agent annotation,
    /// persisted on the node itself (so it round-trips with the rest of the
    /// tree, §1.13). Errors if `node_id` doesn't exist.
    pub fn label(&mut self, node_id: &str, label: impl Into<String>) -> Result<()> {
        let node = self
            .nodes
            .get_mut(node_id)
            .ok_or_else(|| Error::Other(format!("session tree has no node `{node_id}`")))?;
        node.label = Some(label.into());
        Ok(())
    }

    /// Clear a node's label, if any. Errors if `node_id` doesn't exist (same
    /// existence-checking posture as [`Self::label`]).
    pub fn clear_label(&mut self, node_id: &str) -> Result<()> {
        let node = self
            .nodes
            .get_mut(node_id)
            .ok_or_else(|| Error::Other(format!("session tree has no node `{node_id}`")))?;
        node.label = None;
        Ok(())
    }

    /// The linear projection of the ACTIVE branch (C7): walk from the root to
    /// the active branch's leaf via parent pointers, returning the messages
    /// in root→leaf order. This is what any linear consumer (the agent loop,
    /// an exporter) must see. `Vec::new()` for an empty tree (no leaf yet).
    ///
    /// **Fail-closed.** This is a thin `self.active_branch`-bound wrapper
    /// around [`Self::linear_projection_of`] and propagates its `Err`
    /// (a missing active branch, a cycle, a dangling leaf) rather than
    /// masking it to an empty `Vec` — a structurally-corrupt tree must ERROR,
    /// never silently look like a session with zero messages. (An earlier
    /// version of this method used `.unwrap_or_default()` here, which let a
    /// corrupt-but-valid-JSON `.tree.json` sidecar pass [`Self::linear_projection`]
    /// straight through to [`crate::session::Session::apply_session_tree`]
    /// and silently EMPTY [`crate::session::Session::messages`] — see that
    /// method's doc comment.)
    pub fn linear_projection(&self) -> Result<Vec<ChatMessage>> {
        self.linear_projection_of(&self.active_branch)
    }

    /// The linear projection of any named branch (not just the active one) —
    /// the general form [`Self::linear_projection`] is built on. Errors if
    /// `branch` doesn't exist; returns `Ok(Vec::new())` for a branch with no
    /// leaf yet (a fresh, still-empty tree's `main`).
    ///
    /// Defensively cycle-guarded: a malformed/hand-edited tree with a parent
    /// cycle returns an error instead of looping forever — this ties into
    /// the "a rewind to a nonexistent node is an error, not corruption"
    /// requirement's sibling guarantee (no API in this module can ever
    /// CREATE a cycle — [`Self::append_message`]'s parent is always the
    /// pre-existing leaf, [`Self::rewind`]/[`Self::branch`] only ever move a
    /// leaf POINTER to an existing node, never rewrite a `parent` link — but
    /// a tree loaded from a hand-edited or corrupted `.tree.json` sidecar
    /// could still contain one, and this must not hang or panic on it).
    pub fn linear_projection_of(&self, branch: &str) -> Result<Vec<ChatMessage>> {
        let b = self.require_branch(branch)?;
        let Some(mut cursor) = b.leaf.clone() else {
            return Ok(Vec::new());
        };
        let mut chain = Vec::new();
        let mut visited = BTreeSet::new();
        loop {
            if !visited.insert(cursor.clone()) {
                return Err(Error::Other(format!(
                    "session tree branch `{branch}` contains a cycle at node `{cursor}`"
                )));
            }
            let node = self.require_node(&cursor)?;
            chain.push(node.message.clone());
            match &node.parent {
                Some(p) => cursor = p.clone(),
                None => break,
            }
        }
        chain.reverse();
        Ok(chain)
    }

    /// BP-8 (catalog:151): the NODE IDS along the active branch, root-first
    /// — the id-level twin of [`Self::linear_projection`], which returns the
    /// same nodes' messages. A caller that knows a conversation POSITION
    /// (an index into the linear view) needs this to name the node at that
    /// position, which is what "move the leaf anywhere" requires. Same
    /// cycle guard and same fail-closed posture as the projection.
    pub fn active_path(&self) -> Result<Vec<NodeId>> {
        self.path_of(&self.active_branch)
    }

    /// [`Self::active_path`] for any named branch.
    pub fn path_of(&self, branch: &str) -> Result<Vec<NodeId>> {
        let b = self.require_branch(branch)?;
        let Some(mut cursor) = b.leaf.clone() else {
            return Ok(Vec::new());
        };
        let mut chain = Vec::new();
        let mut visited = BTreeSet::new();
        loop {
            if !visited.insert(cursor.clone()) {
                return Err(Error::Other(format!(
                    "session tree branch `{branch}` contains a cycle at node `{cursor}`"
                )));
            }
            let node = self.require_node(&cursor)?;
            chain.push(cursor.clone());
            match &node.parent {
                Some(p) => cursor = p.clone(),
                None => break,
            }
        }
        chain.reverse();
        Ok(chain)
    }

    /// Whether this tree has actually branched (more than just the implicit
    /// [`MAIN_BRANCH`]) — i.e. it is no longer the degenerate single-path
    /// case. A caller can use this to decide whether a `.tree.json` sidecar
    /// is even worth persisting (a never-branched tree is exactly the
    /// pre-existing linear session, byte for byte, so the C7 default-off
    /// posture never requires writing one).
    pub fn has_branches(&self) -> bool {
        self.branches.len() > 1
    }

    /// Attach a caller-provided summary to `branch` directly (module 21
    /// "branch summaries"). `node_id` records which node the summary is
    /// as-of (the branch's current leaf, normally); `model_id` is `None` for
    /// a caller-provided (not model-generated) summary. Errors if `branch`
    /// doesn't exist.
    ///
    /// Errors if `branch` has no leaf yet (a brand-new, still-empty branch) —
    /// a leafless branch has no node to summarize *as-of*, and recording a
    /// [`BranchSummary::node_id`] of `""` would be a pointer to a node that
    /// doesn't exist (F4: never fabricate a dangling pointer).
    pub fn summarize_branch(
        &mut self,
        branch: &str,
        summary: impl Into<String>,
        model_id: Option<String>,
        timestamp_ms: i64,
    ) -> Result<()> {
        let leaf = self.require_branch(branch)?.leaf.clone().ok_or_else(|| {
            Error::Other(format!(
                "session tree branch `{branch}` has no leaf yet — nothing to summarize"
            ))
        })?;
        let b = self
            .branches
            .get_mut(branch)
            .expect("just checked via require_branch");
        b.summary = Some(BranchSummary {
            summary: summary.into(),
            node_id: leaf,
            branch: branch.to_string(),
            model_id,
            created_at_ms: timestamp_ms,
        });
        Ok(())
    }

    /// Render a branch's linear projection into plain text (one line per
    /// turn, `role: content`) — the input a [`BranchSummarizer`] side-call
    /// summarizes, mirroring `reduce/summarize.rs`'s `render_span_text`
    /// shape.
    pub fn render_branch_text(&self, branch: &str) -> Result<String> {
        let messages = self.linear_projection_of(branch)?;
        let mut out = String::new();
        for m in &messages {
            let role = match m.role {
                crate::message::Role::System => "system",
                crate::message::Role::User => "user",
                crate::message::Role::Assistant => "assistant",
                crate::message::Role::Tool => "tool",
            };
            out.push_str(role);
            out.push_str(": ");
            out.push_str(m.content.as_deref().unwrap_or(""));
            out.push('\n');
        }
        Ok(out)
    }

    /// Summarize `branch` via a small-model side-call (D-9, the mechanism
    /// an optional caller-supplied branch summarizer
    /// also uses): renders the branch's text
    /// ([`Self::render_branch_text`]) and calls `summarizer`. **Never fails
    /// the caller** — mirroring `reduce/summarize.rs`'s "never blocks, never
    /// fails the pass" posture: if `summarizer` errors (a timeout, a
    /// provider error, budget exhaustion — whatever it models), this falls
    /// back to a deterministic stub summary (`"[N turns, unsummarized]"`)
    /// rather than propagating the error, so a C7 export can always
    /// complete. Errors only if `branch` itself doesn't exist.
    pub fn summarize_branch_with(
        &mut self,
        branch: &str,
        summarizer: &dyn BranchSummarizer,
        timestamp_ms: i64,
    ) -> Result<()> {
        let text = self.render_branch_text(branch)?;
        let turn_count = self.linear_projection_of(branch)?.len();
        match summarizer.summarize(&text) {
            Ok(summary) => {
                self.summarize_branch(
                    branch,
                    summary,
                    Some(summarizer.model_id().to_string()),
                    timestamp_ms,
                )?;
            }
            Err(_) => {
                self.summarize_branch(
                    branch,
                    format!("[{turn_count} turn(s), unsummarized]"),
                    None,
                    timestamp_ms,
                )?;
            }
        }
        Ok(())
    }

    /// C7 export mechanism: splice the ACTIVE branch's messages (exactly
    /// [`Self::linear_projection`] — what a strictly-linear export target,
    /// e.g. the CX rollout shape, can represent) plus a [`BranchSummary`]
    /// for every OFF-path branch (every branch other than the active one).
    /// An off-path branch that already carries a [`Branch::summary`] reuses
    /// it as-is; one that doesn't gets a fresh deterministic stub summary
    /// (`"[N turn(s), unsummarized]"`) — this method takes `&self` (read
    /// only) precisely so it never needs a live [`BranchSummarizer`] side-call
    /// inline; a caller wanting model-generated summaries should call
    /// [`Self::summarize_branch_with`] on each off-path branch FIRST, then
    /// call this. Nothing here mutates or drops any node — see the module
    /// doc's "Lossless rewind" / C7 sections: the full multi-branch
    /// [`SessionTree`] (this method's `&self` receiver) remains the
    /// recoverable source of truth regardless of what the caller does with
    /// the returned linear messages.
    ///
    /// **Fail-closed** on the active path, same posture as
    /// [`Self::linear_projection`]: a corrupt active branch errors instead of
    /// silently exporting an empty transcript (F2). Off-path branches are
    /// summarized best-effort (see [`Self::summarize_branch_with`]'s "never
    /// blocks" contract) — a corrupt OFF-path branch does not fail the whole
    /// export, but never claims false turn-count precision either; see
    /// [`BranchSummary`]'s construction below.
    pub fn splice_for_linear_export(&self) -> Result<(Vec<ChatMessage>, Vec<BranchSummary>)> {
        let active = self.linear_projection()?;
        let mut summaries = Vec::new();
        for (name, b) in &self.branches {
            if name == &self.active_branch {
                continue;
            }
            if let Some(s) = &b.summary {
                summaries.push(s.clone());
            } else {
                // F4: don't mask a corrupt/leafless off-path branch behind a
                // deterministic-looking "[0 turn(s)]" stub — that reads as
                // "an empty conversation" when the real state is "this
                // branch's data couldn't be read." Surface the real state in
                // the summary text instead (never errors the whole export
                // over ONE off-path branch — same "never blocks" posture as
                // `Self::summarize_branch_with`), and stamp the branch's own
                // `created_at_ms` rather than a placeholder `0`.
                let (summary_text, node_id) = match &b.leaf {
                    None => (
                        format!("[branch `{name}` has no leaf yet — nothing to summarize]"),
                        String::new(),
                    ),
                    Some(leaf) => match self.linear_projection_of(name) {
                        Ok(msgs) => (
                            format!("[{} turn(s), unsummarized]", msgs.len()),
                            leaf.clone(),
                        ),
                        Err(e) => (
                            format!("[branch `{name}` could not be read, unsummarized: {e}]"),
                            leaf.clone(),
                        ),
                    },
                };
                summaries.push(BranchSummary {
                    summary: summary_text,
                    node_id,
                    branch: name.clone(),
                    model_id: None,
                    created_at_ms: b.created_at_ms,
                });
            }
        }
        Ok((active, summaries))
    }
}

/// Injectable branch-summarization side-call (D-9), the module-21 analog of
/// a caller-supplied branch summarizer
/// — same shape, deliberately: a real implementation calls out to a cheap
/// model; tests inject a deterministic fake. See
/// [`SessionTree::summarize_branch_with`]'s doc comment for the "never
/// blocks, never fails the caller" contract this trait's `Err` feeds into.
pub trait BranchSummarizer {
    /// Summarize `branch_text` (the rendering [`SessionTree::render_branch_text`]
    /// produces) into a short paragraph. `Err` means the caller falls back to
    /// a deterministic stub — see
    /// [`SessionTree::summarize_branch_with`].
    fn summarize(&self, branch_text: &str) -> Result<String>;

    /// Identifier of the model behind this summarizer (recorded on
    /// [`BranchSummary::model_id`]).
    fn model_id(&self) -> &str;
}