quarb_compose/

lib.rs

//! Adapter composition: descend *through* a leaf into its content.
//!
//! A filesystem's `.json` file, an archive's `config.xml` entry, a
//! message's HTML part — trees of files are full of leaves whose
//! *content* is itself a tree in another notation. Composition
//! grafts that inner tree onto the outer one: wrap any adapter in
//! a [`ComposeAdapter`] and a leaf whose name or content says
//! "parse me" gains the parsed arbor as its children:
//!
//! ```text
//! /data/store.json/books/*[/price:: < 12]/title::
//!       └ outer (fs) ┘└──── inner (json) ────┘
//! ```
//!
//! The graft happens on first touch, lazily: a leaf is only read
//! and parsed when navigation actually enters it. Detection is by
//! extension (`.json`, `.xml`, `.html`/`.htm`/`.xhtml`/`.svg`,
//! `.csv`/`.tsv`), else by sniffing the content's first
//! character; a parse failure simply leaves the leaf a leaf.
//! Archive leaves (`.zip`, `.tar`, `.tar.gz`) are binary, so they
//! graft by *path* rather than content — available when the outer
//! substrate has real paths (see
//! [`ComposeAdapter::with_source_paths`]) — and the grafted
//! archive composes in turn, so one path runs filesystem → tar →
//! JSON without a seam. The
//! inner root is *identified with* the outer leaf node — the leaf
//! itself answers the inner root's children — so there is no
//! phantom node between the file and its content.
//!
//! Locators show the boundary with a bang, jar-URL style:
//! `store.json!/books/1`.

use quarb::{AstAdapter, NodeId, Value};
use std::cell::RefCell;
use std::collections::HashMap;
use std::path::PathBuf;

/// A parsed inner arbor.
enum Inner {
    Json(quarb_json::JsonAdapter),
    Xml(quarb_xml::XmlAdapter),
    Html(quarb_html::HtmlAdapter),
    Text(quarb_text::TextModel),
    Csv(quarb_csv::CsvAdapter),
    #[cfg(feature = "source")]
    Syntax(quarb_tree_sitter::TreeSitterAdapter),
    #[cfg(feature = "source")]
    Code(quarb_code::CodeModel),
    /// A grafted archive, itself composed so its own parseable
    /// entries graft in turn.
    Archive(Box<ComposeAdapter<quarb_archive::ArchiveAdapter>>),
}

impl Inner {
    fn adapter(&self) -> &dyn AstAdapter {
        match self {
            Inner::Json(a) => a,
            Inner::Xml(a) => a,
            Inner::Html(a) => a,
            Inner::Text(a) => a,
            Inner::Csv(a) => a,
            #[cfg(feature = "source")]
            Inner::Syntax(a) => a,
            #[cfg(feature = "source")]
            Inner::Code(a) => a,
            Inner::Archive(a) => &**a,
        }
    }

    fn locator(&self, node: NodeId) -> String {
        match self {
            Inner::Json(a) => a.pointer(node),
            Inner::Xml(a) => a.locator(node),
            Inner::Html(a) => a.locator(node),
            Inner::Text(a) => a.locator(node),
            Inner::Csv(a) => a.locator(node),
            #[cfg(feature = "source")]
            Inner::Syntax(a) => a.locator(node),
            #[cfg(feature = "source")]
            Inner::Code(a) => a.locator(node),
            Inner::Archive(a) => a.locator(node, |o| a.outer().locator(o)),
        }
    }
}

/// The level source-file leaves graft at: the syntax level (the
/// literal parse — the default) or the code level (identifiers
/// as names). Chosen per mount by the `code:` target prefix, and
/// inherited by nested composes (an archive inside a `code:`
/// mount grafts its source entries at the code level too) — the
/// filesystem-into-declarations namespace has no seam.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SourceGraft {
    #[default]
    Syntax,
    Code,
}

/// The level marked-up documents (`.html`, `.htm`, `.md`) graft
/// at: their DOM by default, or the text level — sections,
/// paragraphs, lists, and what the page declares about itself
/// in its head — when the mount asks for the reader's model
/// (`text:` on an archive or directory).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum DocumentGraft {
    #[default]
    Dom,
    Text,
}

/// Names [`quarb_archive::ArchiveAdapter::open`] can take: the
/// zip family, tar, and gzip (`.gz` alone included — the open
/// checks magic bytes, and a failure leaves the leaf a leaf).
fn archive_name(name: &str) -> bool {
    let ext = name.rsplit('.').next().unwrap_or("").to_ascii_lowercase();
    matches!(ext.as_str(), "zip" | "tar" | "tgz" | "gz")
}

/// Parse `content` by `name`'s extension, else by sniffing.
fn parse_inner(name: &str, content: &str, graft: SourceGraft, doc: DocumentGraft) -> Option<Inner> {
    #[cfg(not(feature = "source"))]
    let _ = graft;
    let ext = name.rsplit('.').next().unwrap_or("").to_ascii_lowercase();
    match ext.as_str() {
        "json" => {
            return quarb_json::JsonAdapter::parse(content)
                .ok()
                .map(Inner::Json);
        }
        "jsonl" | "ndjson" => {
            return quarb_json::JsonAdapter::parse_lines(content)
                .ok()
                .map(Inner::Json);
        }
        "xml" | "svg" | "xhtml" => {
            return quarb_xml::XmlAdapter::parse(content).ok().map(Inner::Xml);
        }
        "html" | "htm" => {
            return Some(match doc {
                DocumentGraft::Dom => Inner::Html(quarb_html::HtmlAdapter::parse(content)),
                DocumentGraft::Text => Inner::Text(quarb_text_html::parse(content)),
            });
        }
        "yaml" | "yml" => return quarb_yaml::parse(content).ok().map(Inner::Json),
        "toml" => return quarb_toml::parse(content).ok().map(Inner::Json),
        "md" | "markdown" => {
            return Some(match doc {
                DocumentGraft::Dom => Inner::Html(quarb_markdown::parse(content)),
                DocumentGraft::Text => Inner::Text(quarb_text_markdown::parse(content)),
            });
        }
        // Plain text grafts at the text level (blank-line
        // paragraphs); html/md keep their DOM-level graft.
        "txt" => return Some(Inner::Text(quarb_text::TextModel::parse_plain(content))),
        "csv" => return quarb_csv::CsvAdapter::parse(content).ok().map(Inner::Csv),
        "tsv" => {
            return quarb_csv::CsvAdapter::parse_with_delimiter(content, b'\t')
                .ok()
                .map(Inner::Csv);
        }
        #[cfg(feature = "source")]
        ext if quarb_tree_sitter::supported(ext) => {
            return match graft {
                SourceGraft::Syntax => quarb_tree_sitter::TreeSitterAdapter::parse(content, ext)
                    .ok()
                    .map(Inner::Syntax),
                SourceGraft::Code => quarb_code::CodeModel::parse(content, ext)
                    .ok()
                    .map(Inner::Code),
            };
        }
        _ => {}
    }
    // Content sniff for extensionless names.
    let t = content.trim_start();
    if t.starts_with('{') || t.starts_with('[') {
        return quarb_json::JsonAdapter::parse(content)
            .ok()
            .map(Inner::Json);
    }
    if t.starts_with("<?xml") {
        return quarb_xml::XmlAdapter::parse(content).ok().map(Inner::Xml);
    }
    None
}

/// One graft: an inner arbor mounted at an outer leaf.
struct Graft {
    outer: NodeId,
    inner: Inner,
}

/// Grafted node ids carry this tag bit; the rest indexes the intern
/// table. The bit sits at the top of the 56-bit id window that
/// `MountAdapter` leaves an inner adapter — it reserves the high byte
/// (bits 56–63) for the mount index — so a grafted id survives being
/// packed into a mount and still round-trips. It must stay below bit
/// 56 for that reason; the top bit (1 << 63) collided with the mount
/// byte. Outer adapters use small sequential indices, far below this
/// bit, so a set bit 55 unambiguously marks a graft.
const GRAFT_BIT: u64 = 1 << 55;

/// Any adapter, with parseable leaf content grafted as subtrees.
/// A host's reader for a document leaf: the path in, its text-level
/// model out, or `None` to leave the leaf to the default grafting.
pub type DocumentReader = std::rc::Rc<dyn Fn(&std::path::Path) -> Option<quarb_text::TextModel>>;

pub struct ComposeAdapter<A: AstAdapter> {
    outer: A,
    grafts: RefCell<Vec<Graft>>,
    /// Outer leaf → its graft index (`None`: probed, not
    /// parseable).
    probed: RefCell<HashMap<NodeId, Option<usize>>>,
    /// (graft, inner id) → interned composite id, and the reverse.
    interned: RefCell<HashMap<(usize, NodeId), NodeId>>,
    reverse: RefCell<Vec<(usize, NodeId)>>,
    /// Maps an outer leaf to a filesystem path, when the outer
    /// substrate has one. Enables archive grafts, which are
    /// binary and open by path rather than parsing from text.
    source_path: Option<fn(&A, NodeId) -> Option<PathBuf>>,
    /// The level source-file leaves graft at.
    source_graft: SourceGraft,
    /// The level marked-up documents graft at.
    document_graft: DocumentGraft,
    /// Maps an outer leaf to the URL its document is served
    /// from, so a text-level graft joins relative references
    /// against it and `-->` can land on a sibling document.
    document_url: Option<fn(&A, NodeId) -> Option<String>>,
    /// URL → outer leaf, built on first `document_by_ref`.
    urls: RefCell<Option<HashMap<String, NodeId>>>,
    /// The host's own reading of a document leaf, by path: when it
    /// answers, its model is the graft (a corpus reading with its
    /// tokens, a format this crate does not parse); when it
    /// declines, the leaf grafts as it otherwise would.
    document_reader: Option<DocumentReader>,
}

impl<A: AstAdapter> ComposeAdapter<A> {
    pub fn new(outer: A) -> Self {
        ComposeAdapter {
            outer,
            grafts: RefCell::new(Vec::new()),
            probed: RefCell::new(HashMap::new()),
            interned: RefCell::new(HashMap::new()),
            reverse: RefCell::new(Vec::new()),
            source_path: None,
            source_graft: SourceGraft::default(),
            document_graft: DocumentGraft::default(),
            document_url: None,
            urls: RefCell::new(None),
            document_reader: None,
        }
    }

    /// Hand document leaves to the host's reader first
    /// (builder-style); needs the outer leaves' paths
    /// ([`with_source_paths`](Self::with_source_paths)).
    pub fn with_document_reader(mut self, reader: DocumentReader) -> Self {
        self.document_reader = Some(reader);
        self
    }

    /// Declare where each outer leaf's document is served from
    /// (builder-style): a text-level graft joins its relative
    /// references against that URL, and `-->` from any graft
    /// lands on the leaf holding the referenced document (its
    /// fragment's bearer when named) without a host registration.
    pub fn with_document_urls(mut self, document_url: fn(&A, NodeId) -> Option<String>) -> Self {
        self.document_url = Some(document_url);
        self
    }

    /// The outer leaf serving `url` (fragment-stripped), from the
    /// declared URLs; the whole outer tree is walked once.
    fn leaf_by_url(&self, url: &str) -> Option<NodeId> {
        let f = self.document_url?;
        if self.urls.borrow().is_none() {
            let mut map = HashMap::new();
            let mut stack = vec![self.outer.root()];
            while let Some(n) = stack.pop() {
                let kids = self.outer.children(n);
                if kids.is_empty() {
                    if let Some(u) = f(&self.outer, n) {
                        map.entry(u.split('#').next().unwrap_or(&u).to_string())
                            .or_insert(n);
                    }
                } else {
                    stack.extend(kids);
                }
            }
            *self.urls.borrow_mut() = Some(map);
        }
        self.urls.borrow().as_ref()?.get(url).copied()
    }

    /// Choose the level source-file leaves graft at
    /// (builder-style; the default is the syntax level).
    pub fn with_source_graft(mut self, graft: SourceGraft) -> Self {
        self.source_graft = graft;
        self
    }

    /// Choose the level marked-up documents graft at
    /// (builder-style; the default is the DOM).
    pub fn with_document_graft(mut self, graft: DocumentGraft) -> Self {
        self.document_graft = graft;
        self
    }

    /// Like [`new`](Self::new), with a hook mapping outer leaves
    /// to filesystem paths, so archive leaves (`.zip`,
    /// `.tar[.gz]`) graft too. The grafted archive composes in
    /// turn: its own parseable entries graft, and one path walks
    /// filesystem → archive → document.
    pub fn with_source_paths(outer: A, source_path: fn(&A, NodeId) -> Option<PathBuf>) -> Self {
        ComposeAdapter {
            source_path: Some(source_path),
            ..Self::new(outer)
        }
    }

    /// The wrapped adapter (for outer-specific calls).
    pub fn outer(&self) -> &A {
        &self.outer
    }

    /// A combined locator: `outer_locator(leaf)!inner-path` for
    /// grafted nodes.
    pub fn locator(&self, node: NodeId, outer_locator: impl Fn(NodeId) -> String) -> String {
        match self.split(node) {
            None => outer_locator(node),
            Some((g, inner)) => {
                let grafts = self.grafts.borrow();
                let graft = &grafts[g];
                format!(
                    "{}!{}",
                    outer_locator(graft.outer),
                    graft.inner.locator(inner)
                )
            }
        }
    }

    /// Decode a composite id.
    /// The graft's fill for a node inside a grafted document: the
    /// outer leaf's provenance (the file's path and mtime) with the
    /// mtime re-labelled as the source rung, and the node's path
    /// inside the document.
    fn graft_fill(&self, outer_leaf: NodeId, inner_path: String) -> quarb::Provenance {
        let mut fill = self.outer.provenance(outer_leaf).as_source_rung();
        fill.path = Some(inner_path);
        fill
    }

    fn split(&self, node: NodeId) -> Option<(usize, NodeId)> {
        if node.0 & GRAFT_BIT == 0 {
            return None;
        }
        self.reverse
            .borrow()
            .get((node.0 & !GRAFT_BIT) as usize)
            .copied()
    }

    fn intern(&self, graft: usize, inner: NodeId) -> NodeId {
        if let Some(&id) = self.interned.borrow().get(&(graft, inner)) {
            return id;
        }
        let mut rev = self.reverse.borrow_mut();
        let id = NodeId(GRAFT_BIT | rev.len() as u64);
        rev.push((graft, inner));
        self.interned.borrow_mut().insert((graft, inner), id);
        id
    }

    /// The graft at an outer leaf, probing (read + parse) on first
    /// touch. Only childless outer nodes with text content are
    /// candidates.
    fn graft_at(&self, node: NodeId) -> Option<usize> {
        if let Some(&g) = self.probed.borrow().get(&node) {
            return g;
        }
        let g = (|| {
            if !self.outer.children(node).is_empty() {
                return None;
            }
            let name = self.outer.name(node)?;
            if archive_name(&name)
                && let Some(path_of) = self.source_path
                && let Some(path) = path_of(&self.outer, node)
                && let Ok(a) = quarb_archive::ArchiveAdapter::open(&path)
            {
                let inner = Inner::Archive(Box::new(
                    ComposeAdapter::new(a)
                        .with_source_graft(self.source_graft)
                        .with_document_graft(self.document_graft),
                ));
                let mut grafts = self.grafts.borrow_mut();
                grafts.push(Graft { outer: node, inner });
                return Some(grafts.len() - 1);
            }
            if let Some(read) = &self.document_reader
                && let Some(path_of) = self.source_path
                && let Some(path) = path_of(&self.outer, node)
                && let Some(model) = read(&path)
            {
                let mut grafts = self.grafts.borrow_mut();
                grafts.push(Graft {
                    outer: node,
                    inner: Inner::Text(model),
                });
                return Some(grafts.len() - 1);
            }
            let content = match self.outer.default_value(node)? {
                Value::Str(s) => s,
                _ => return None,
            };
            let mut inner = parse_inner(&name, &content, self.source_graft, self.document_graft)?;
            if let (Inner::Text(model), Some(f)) = (&mut inner, self.document_url)
                && let Some(u) = f(&self.outer, node)
            {
                model.set_document_url(&u);
            }
            let mut grafts = self.grafts.borrow_mut();
            grafts.push(Graft { outer: node, inner });
            Some(grafts.len() - 1)
        })();
        self.probed.borrow_mut().insert(node, g);
        g
    }

    /// Map an inner node up: the inner root becomes the outer
    /// leaf.
    fn wrap(&self, graft: usize, inner: NodeId) -> NodeId {
        let grafts = self.grafts.borrow();
        if inner == grafts[graft].inner.adapter().root() {
            grafts[graft].outer
        } else {
            drop(grafts);
            self.intern(graft, inner)
        }
    }
}

impl<A: AstAdapter> AstAdapter for ComposeAdapter<A> {
    fn root(&self) -> NodeId {
        self.outer.root()
    }

    fn children(&self, node: NodeId) -> Vec<NodeId> {
        match self.split(node) {
            Some((g, inner)) => {
                let ids: Vec<NodeId> = {
                    let grafts = self.grafts.borrow();
                    grafts[g].inner.adapter().children(inner)
                };
                ids.into_iter().map(|c| self.wrap(g, c)).collect()
            }
            None => {
                let outer = self.outer.children(node);
                if !outer.is_empty() {
                    return outer;
                }
                match self.graft_at(node) {
                    Some(g) => {
                        let ids: Vec<NodeId> = {
                            let grafts = self.grafts.borrow();
                            let a = grafts[g].inner.adapter();
                            a.children(a.root())
                        };
                        ids.into_iter().map(|c| self.wrap(g, c)).collect()
                    }
                    None => Vec::new(),
                }
            }
        }
    }

    fn name(&self, node: NodeId) -> Option<String> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().name(inner),
            None => self.outer.name(node),
        }
    }

    fn parent(&self, node: NodeId) -> Option<NodeId> {
        match self.split(node) {
            Some((g, inner)) => {
                let p = self.grafts.borrow()[g].inner.adapter().parent(inner)?;
                Some(self.wrap(g, p))
            }
            None => self.outer.parent(node),
        }
    }

    fn child_host(&self, node: NodeId) -> NodeId {
        match self.split(node) {
            Some((g, inner)) => {
                let h = self.grafts.borrow()[g].inner.adapter().child_host(inner);
                self.wrap(g, h)
            }
            None => self.outer.child_host(node),
        }
    }

    fn properties(&self, node: NodeId) -> Vec<(String, Value)> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().properties(inner),
            None => self.outer.properties(node),
        }
    }

    /// The outer tree's non-tree nodes, then each graft's (the
    /// grafts already read).
    fn non_tree_nodes(&self) -> Vec<NodeId> {
        let mut out = self.outer.non_tree_nodes();
        let grafts = self.grafts.borrow();
        for (g, graft) in grafts.iter().enumerate() {
            out.extend(
                graft
                    .inner
                    .adapter()
                    .non_tree_nodes()
                    .into_iter()
                    .map(|n| self.wrap(g, n)),
            );
        }
        out
    }

    /// A written name reaches a node by the owning adapter's rule
    /// (its aliases included).
    fn answers_to(&self, node: NodeId, name: &str) -> bool {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .answers_to(inner, name),
            None => self.outer.answers_to(node, name),
        }
    }

    /// The graft root IS the outer leaf, so the leaf wears the
    /// grafted document's own traits too — a page's declared tags
    /// on the file that holds it.
    fn traits(&self, node: NodeId) -> Vec<String> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().traits(inner),
            None => {
                let mut out = self.outer.traits(node);
                if let Some(g) = self.graft_at(node) {
                    let grafts = self.grafts.borrow();
                    let a = grafts[g].inner.adapter();
                    for t in a.traits(a.root()) {
                        if !out.contains(&t) {
                            out.push(t);
                        }
                    }
                }
                out
            }
        }
    }

    fn property(&self, node: NodeId, name: &str) -> Option<Value> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .property(inner, name),
            // The graft root IS the outer leaf, so a property the
            // outer can't answer falls through to the grafted
            // document's root — `::key` dual exposure works *at*
            // the graft, not only one level in.
            None => self.outer.property(node, name).or_else(|| {
                let g = self.graft_at(node)?;
                let grafts = self.grafts.borrow();
                let a = grafts[g].inner.adapter();
                a.property(a.root(), name)
            }),
        }
    }

    fn default_value(&self, node: NodeId) -> Option<Value> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().default_value(inner),
            None => self.outer.default_value(node),
        }
    }

    fn metadata(&self, node: NodeId, key: &str) -> Option<Value> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().metadata(inner, key),
            // Like properties: what the outer cannot answer, the
            // grafted document's root may (`::::"og:type"` on the
            // file that holds the page).
            None => self.outer.metadata(node, key).or_else(|| {
                let g = self.graft_at(node)?;
                let grafts = self.grafts.borrow();
                let a = grafts[g].inner.adapter();
                a.metadata(a.root(), key)
            }),
        }
    }

    /// A graft's own aliases are not merged: a node either belongs
    /// to the outer document or to a graft, and the alias list is
    /// consulted only after the owning adapter's `property` misses.
    fn aliased_metadata(&self, node: NodeId) -> &'static [&'static str] {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .aliased_metadata(inner),
            None => self.outer.aliased_metadata(node),
        }
    }

    /// A graft is a provenance layer: the grafted document's own
    /// components win, and the outer *leaf* it was parsed from fills
    /// the rest (with an fs outer: the file's path and mtime). The
    /// jar-style composite locator is deliberately not the source —
    /// `?src` names a document, and the intra-document address is
    /// dpid's job.
    fn provenance(&self, node: NodeId) -> quarb::Provenance {
        match self.split(node) {
            Some((g, inner)) => {
                // Clone what we need out of the borrow before calling
                // into `self.outer` (which may re-enter the graft
                // tables).
                let (inner_prov, outer_leaf, inner_path) = {
                    let grafts = self.grafts.borrow();
                    let a = grafts[g].inner.adapter();
                    (
                        a.provenance(inner),
                        grafts[g].outer,
                        quarb::name_path(a, inner),
                    )
                };
                inner_prov.or(self.graft_fill(outer_leaf, inner_path))
            }
            None => self.outer.provenance(node),
        }
    }
    /// The same layering, entry by entry.
    fn provenance_list(&self, node: NodeId) -> quarb::ProvenanceList {
        match self.split(node) {
            Some((g, inner)) => {
                let (inner_list, outer_leaf, inner_path) = {
                    let grafts = self.grafts.borrow();
                    let a = grafts[g].inner.adapter();
                    (
                        a.provenance_list(inner),
                        grafts[g].outer,
                        quarb::name_path(a, inner),
                    )
                };
                inner_list.or(self.graft_fill(outer_leaf, inner_path))
            }
            None => self.outer.provenance_list(node),
        }
    }

    fn resolve(&self, node: NodeId, property: &str, hint: Option<&str>) -> Option<NodeId> {
        match self.split(node) {
            Some((g, inner)) => {
                let t = self.grafts.borrow()[g]
                    .inner
                    .adapter()
                    .resolve(inner, property, hint)?;
                Some(self.wrap(g, t))
            }
            None => self.outer.resolve(node, property, hint),
        }
    }

    /// A trait test reaches the graft — and, on the outer leaf,
    /// the graft's root, as `traits` does.
    fn has_trait(&self, node: NodeId, name: &str) -> bool {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .has_trait(inner, name),
            None => {
                self.outer.has_trait(node, name)
                    || self.graft_at(node).is_some_and(|g| {
                        let grafts = self.grafts.borrow();
                        let a = grafts[g].inner.adapter();
                        a.has_trait(a.root(), name)
                    })
            }
        }
    }

    fn ref_property(&self, node: NodeId) -> Option<String> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g].inner.adapter().ref_property(inner),
            None => self.outer.ref_property(node),
        }
    }

    /// A graft's external references (a text-level ref leaving
    /// its document) come through; an outer leaf's own do too.
    fn external_ref(&self, node: NodeId, property: &str, hint: Option<&str>) -> Option<String> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .external_ref(inner, property, hint),
            None => self.outer.external_ref(node, property, hint),
        }
    }

    fn ref_label(&self, node: NodeId, property: &str) -> Option<String> {
        match self.split(node) {
            Some((g, inner)) => self.grafts.borrow()[g]
                .inner
                .adapter()
                .ref_label(inner, property),
            None => self.outer.ref_label(node, property),
        }
    }

    /// A fragment lands inside the document: on an outer leaf
    /// that holds a graft, inside that graft.
    fn resolve_fragment(&self, node: NodeId, fragment: &str) -> Option<NodeId> {
        match self.split(node) {
            Some((g, inner)) => {
                let t = self.grafts.borrow()[g]
                    .inner
                    .adapter()
                    .resolve_fragment(inner, fragment)?;
                Some(self.wrap(g, t))
            }
            None => match self.graft_at(node) {
                Some(g) => {
                    let t = {
                        let grafts = self.grafts.borrow();
                        let a = grafts[g].inner.adapter();
                        a.resolve_fragment(a.root(), fragment)?
                    };
                    Some(self.wrap(g, t))
                }
                None => self.outer.resolve_fragment(node, fragment),
            },
        }
    }

    /// The leaf serving a URL, from the declared document URLs;
    /// else whatever the outer answers.
    fn document_by_ref(&self, id: &str) -> Option<NodeId> {
        if let Some(leaf) = self.leaf_by_url(id) {
            // The graft is parsed here so a fragment can land.
            let _ = self.graft_at(leaf);
            return Some(leaf);
        }
        self.outer.document_by_ref(id)
    }

    /// A reverse index answers on one side of the boundary only:
    /// inside a graft, or on the outer tree when no graft could
    /// hold a referrer (the outer's answer cannot see grafts).
    fn reverse_resolve(
        &self,
        node: NodeId,
        property: Option<&str>,
        hint: Option<&str>,
    ) -> Option<Vec<NodeId>> {
        match self.split(node) {
            Some((g, inner)) => {
                let v = self.grafts.borrow()[g]
                    .inner
                    .adapter()
                    .reverse_resolve(inner, property, hint)?;
                Some(v.into_iter().map(|t| self.wrap(g, t)).collect())
            }
            None => None,
        }
    }

    /// Inside a graft the graft's index answers; on the outer tree
    /// a name may also live inside grafts, so the walk stays.
    fn descendants_named(&self, node: NodeId, name: &str) -> Option<Vec<(NodeId, usize)>> {
        let (g, inner) = self.split(node)?;
        let v = self.grafts.borrow()[g]
            .inner
            .adapter()
            .descendants_named(inner, name)?;
        Some(v.into_iter().map(|(t, d)| (self.wrap(g, t), d)).collect())
    }

    fn prefetch_links(&self, nodes: &[NodeId], dir: quarb::LinkDir) {
        let outer: Vec<NodeId> = nodes
            .iter()
            .copied()
            .filter(|n| self.split(*n).is_none())
            .collect();
        if !outer.is_empty() {
            self.outer.prefetch_links(&outer, dir);
        }
    }

    fn links(&self, node: NodeId) -> Vec<(String, NodeId)> {
        match self.split(node) {
            Some((g, inner)) => {
                let ls: Vec<(String, NodeId)> = {
                    let grafts = self.grafts.borrow();
                    grafts[g].inner.adapter().links(inner)
                };
                ls.into_iter().map(|(l, n)| (l, self.wrap(g, n))).collect()
            }
            None => self.outer.links(node),
        }
    }

    fn backlinks(&self, node: NodeId) -> Vec<(String, NodeId)> {
        match self.split(node) {
            Some((g, inner)) => {
                let ls: Vec<(String, NodeId)> = {
                    let grafts = self.grafts.borrow();
                    grafts[g].inner.adapter().backlinks(inner)
                };
                ls.into_iter().map(|(l, n)| (l, self.wrap(g, n))).collect()
            }
            None => self.outer.backlinks(node),
        }
    }

    fn link_property(
        &self,
        source: NodeId,
        label: &str,
        target: NodeId,
        name: &str,
    ) -> Option<Value> {
        // An edge lives on one side of the graft boundary: both
        // endpoints are inner (same graft) or both outer.
        match (self.split(source), self.split(target)) {
            (Some((g, src)), Some((gt, tgt))) if g == gt => self.grafts.borrow()[g]
                .inner
                .adapter()
                .link_property(src, label, tgt, name),
            (None, None) => self.outer.link_property(source, label, target, name),
            _ => None,
        }
    }
}