hypersteeldb 0.5.5

//! **Learn** — the third verb, and the one that works differently on purpose.
//!
//! `ingest` and `query` are offline, deterministic and free. `learn` is none of those: it calls a language
//! model, which means credentials, network, latency and a bill. Hiding that behind a method that looks like the
//! other two would be a trap, so this module makes all four facts visible in the shape of the API.
//!
//! ```no_run
//! # #[cfg(feature = "bedrock")]
//! # async fn demo() -> Result<(), Box<dyn std::error::Error>> {
//! use steeldb::{SteelDb, learn::Teacher};
//!
//! let mut db = SteelDb::ingest(["…documents…"])?;
//!
//! // credentials are checked when the teacher is built, not when it is used
//! let teacher = Teacher::bedrock("us.anthropic.claude-sonnet-4-5-20250929-v1:0")?;
//!
//! // a proposal is returned, NOT applied
//! let proposal = teacher.propose_categories(&db).await?;
//! println!("{proposal}");
//!
//! // you decide, and the same MECE test that gates local discovery gates this too
//! let adopted = db.adopt(&proposal);
//! println!("kept {} of {}", adopted.len(), proposal.candidates.len());
//! # Ok(()) }
//! ```
//!
//! ## Why a proposal instead of a mutation
//!
//! A model suggesting categories is a suggestion, not an authority. Returning a [`Proposal`] means you can
//! print it, diff it, log it, or reject it before your vocabulary changes — and it keeps the model advisory,
//! which is the same separation the query planner has. `adopt` then applies the *same* gate that local
//! discovery uses, so a model cannot sneak in a category that a deterministic test would have rejected.
//!
//! Without a network-capable feature enabled, this module still compiles: [`Proposal`] and [`SteelDb::adopt`]
//! work with candidates from any source, so the offline path is testable.

use crate::api::SteelDb;

/// A candidate category, from wherever.
#[derive(Debug, Clone, PartialEq)]
pub struct Candidate {
    /// the category name, which becomes its query stem
    pub name: String,
    /// words that should put a document in this category
    pub words: Vec<String>,
    /// why the proposer thinks it belongs, for a human reading the diff
    pub rationale: String,
}

/// What a teacher suggests. Inert until adopted.
#[derive(Debug, Clone, Default)]
pub struct Proposal {
    pub candidates: Vec<Candidate>,
    /// what produced this, so a log entry is traceable
    pub source: String,
}

impl std::fmt::Display for Proposal {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "proposal from {} — {} candidate(s)", self.source, self.candidates.len())?;
        for c in &self.candidates {
            writeln!(f, "  {} — {}", c.name, c.rationale)?;
            writeln!(f, "    words: {}", c.words.join(", "))?;
        }
        Ok(())
    }
}

/// The outcome of adopting one candidate. Reported per candidate so a rejection is explicable.
#[derive(Debug, Clone)]
pub struct Verdict {
    pub name: String,
    pub kept: bool,
    /// the gate's own words
    pub reason: String,
    /// share of documents the candidate covers
    pub coverage: f64,
    /// how much it duplicates a category already accepted
    pub overlap: f64,
}

impl SteelDb {
    /// Apply a proposal, keeping only what the MECE gate accepts.
    ///
    /// The gate is the same one [`SteelDb::ingest`] uses, so a model-proposed category has to earn its place on
    /// the same terms as a locally-discovered one: enough coverage, and not a near-duplicate of something
    /// already present. Candidates are judged in order, so the second of two similar suggestions is rejected
    /// against the first.
    ///
    /// Returns a verdict per candidate; the kept ones are queryable immediately.
    pub fn adopt(&mut self, proposal: &Proposal) -> Vec<Verdict> {
        let mut verdicts = Vec::new();
        for (round, cand) in proposal.candidates.iter().enumerate() {
            let c = crate::grow::Candidate {
                name: cand.name.clone(),
                parent: None,
                description: cand.rationale.clone(),
                examples: cand.words.clone(),
                worth_adding: true,
            };
            let docs = self.documents().to_vec();
            let spec = self.spec_snapshot();
            let scored = crate::grow::score_candidate_full(&spec, &docs, &c);
            let (score, dup) = match scored {
                Some((s, d)) => (Some(s), d),
                None => (None, None),
            };
            let ev = crate::grow::gate_full(&spec, &c, score.as_ref(), dup, self.min_gain(), round);
            if ev.kept {
                self.push_category(cand.name.clone(), cand.words.clone());
            }
            verdicts.push(Verdict {
                name: cand.name.clone(),
                kept: ev.kept,
                reason: ev.reason,
                coverage: ev.coverage,
                overlap: ev.maxcos,
            });
        }
        if verdicts.iter().any(|v| v.kept) {
            // the index must be rebuilt: a new category changes what every document projects to
            self.reproject();
        }
        verdicts
    }
}

/// A source of proposals.
///
/// Constructing one is where credentials are checked, so a missing configuration fails before any work is
/// queued rather than part-way through a corpus.
pub struct Teacher {
    kind: Kind,
}

enum Kind {
    /// proposals supplied by the caller — the offline path, and what the tests use
    Fixed(Proposal),
    /// any OpenAI-compatible endpoint: llama.cpp, vLLM, Ollama, LM Studio. No credentials, no bill.
    #[cfg(feature = "paddock")]
    Local { base_url: String, model: String },
    #[cfg(feature = "bedrock")]
    Bedrock { model_id: String },
}

/// Why learning could not proceed.
#[derive(Debug)]
pub enum LearnError {
    /// no credentials, or the region/model is not configured
    NotConfigured(String),
    /// the model answered, but not with something usable
    BadResponse(String),
    /// the call itself failed
    Transport(String),
}

impl std::fmt::Display for LearnError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            LearnError::NotConfigured(m) => write!(f, "not configured for learning: {m}"),
            LearnError::BadResponse(m) => write!(f, "unusable response: {m}"),
            LearnError::Transport(m) => write!(f, "call failed: {m}"),
        }
    }
}

impl std::error::Error for LearnError {}

impl Teacher {
    /// A teacher that returns a fixed proposal. Useful for tests, for replaying a recorded proposal, and for
    /// feeding in candidates from a source of your own.
    pub fn fixed(proposal: Proposal) -> Teacher {
        Teacher { kind: Kind::Fixed(proposal) }
    }

    /// A teacher backed by a **local** model behind an OpenAI-compatible endpoint.
    ///
    /// This is the preferred route. It needs no credentials, sends nothing off the machine, and costs nothing,
    /// which removes every objection to `learn` except quality. Works with llama.cpp, vLLM, LM Studio, Ollama —
    /// anything speaking `/v1/chat/completions`.
    ///
    /// **The model must support tool calling.** `learn` asks for a structured ontology, and a model without
    /// tool calling replies in prose or with nothing — measured on a local ollama, `qwen2.5:0.5b` returns
    /// `tool_calls: null` for every request, while `qwen3.5:0.8b`, `granite3-moe:3b` and `functiongemma` work.
    ///
    /// Beyond that, a small model is a reasonable choice *because* of the gate. Proposals are judged by the same
    /// deterministic MECE test as local discovery, so a weak model produces rejected candidates rather than a
    /// polluted vocabulary. The failure mode of choosing badly is wasted effort, not a wrong answer: on an
    /// eight-document corpus `qwen3.5:0.8b` proposed a category that appears nowhere in the text and one that
    /// restated an existing category, and the gate refused both.
    ///
    /// ```no_run
    /// # #[cfg(feature = "paddock")]
    /// # fn demo() -> Result<(), Box<dyn std::error::Error>> {
    /// use steeldb::learn::Teacher;
    /// // a function-calling model small enough to run on a laptop
    /// let teacher = Teacher::local("http://localhost:11434/v1", "qwen3.5:0.8b")?;
    /// # Ok(()) }
    /// ```
    #[cfg(feature = "paddock")]
    pub fn local(base_url: impl Into<String>, model: impl Into<String>) -> Result<Teacher, LearnError> {
        let base_url = base_url.into();
        if !base_url.starts_with("http") {
            return Err(LearnError::NotConfigured(format!(
                "base_url should be an http(s) endpoint, got {base_url:?}"
            )));
        }
        Ok(Teacher { kind: Kind::Local { base_url, model: model.into() } })
    }

    /// A teacher backed by a model served by Ollama on the default port.
    ///
    /// Shorthand for [`Teacher::local`] against `http://localhost:11434/v1`.
    #[cfg(feature = "paddock")]
    pub fn ollama(model: impl Into<String>) -> Result<Teacher, LearnError> {
        Teacher::local("http://localhost:11434/v1", model)
    }

    /// A teacher backed by Amazon Bedrock.
    ///
    /// Requires AWS credentials resolvable by the standard chain (environment, profile, or instance role) and
    /// `AWS_REGION`. Checked here so the failure is immediate and names what is missing.
    ///
    /// This costs money per call. The amount is small for vocabulary proposal — one request over a sample of
    /// documents — but it is a real charge and worth saying out loud.
    #[cfg(feature = "bedrock")]
    pub fn bedrock(model_id: impl Into<String>) -> Result<Teacher, LearnError> {
        if std::env::var("AWS_REGION").is_err() && std::env::var("AWS_DEFAULT_REGION").is_err() {
            return Err(LearnError::NotConfigured(
                "set AWS_REGION (or AWS_DEFAULT_REGION) to the region hosting the model".into(),
            ));
        }
        Ok(Teacher { kind: Kind::Bedrock { model_id: model_id.into() } })
    }

    /// Ask for categories the local discovery may have missed.
    ///
    /// Returns a [`Proposal`]; nothing changes until you [`SteelDb::adopt`] it.
    pub async fn propose_categories(&self, db: &SteelDb) -> Result<Proposal, LearnError> {
        // only the network paths read the corpus; without them this is deliberately unused
        let _ = db;
        match &self.kind {
            Kind::Fixed(p) => Ok(p.clone()),
            #[cfg(feature = "paddock")]
            Kind::Local { base_url, model } => {
                let cfg = crate::agent::config::ProviderConfig::Paddock {
                    base_url: base_url.clone(),
                    model: model.clone(),
                    api_key: None,
                };
                Self::propose_via(cfg, db).await
            }
            #[cfg(feature = "bedrock")]
            Kind::Bedrock { model_id } => {
                let cfg = crate::agent::config::ProviderConfig::Bedrock {
                    model_id: model_id.clone(),
                    region: std::env::var("AWS_REGION").ok(),
                };
                Self::propose_via(cfg, db).await
            }
        }
    }

    /// The shared path: whichever provider, the prompt, parsing and shaping are identical. Only the transport
    /// differs, which is what lets a local 270M model and a hosted frontier model be swapped freely.
    #[cfg(any(feature = "paddock", feature = "bedrock"))]
    async fn propose_via(
        cfg: crate::agent::config::ProviderConfig,
        db: &SteelDb,
    ) -> Result<Proposal, LearnError> {
        // label the proposal by its transport, so a logged proposal says which model produced it
        let label = match &cfg {
            #[cfg(feature = "paddock")]
            crate::agent::config::ProviderConfig::Paddock { model, .. } => format!("local:{model}"),
            #[cfg(feature = "bedrock")]
            crate::agent::config::ProviderConfig::Bedrock { model_id, .. } => format!("bedrock:{model_id}"),
            _ => "model".to_string(),
        };
        let provider = cfg.build().await.map_err(LearnError::Transport)?;
        let sample: Vec<String> = db.documents().iter().take(48).cloned().collect();
        let spec = crate::vocabulary::propose(provider.as_ref(), "documents", &sample)
            .await
            .map_err(LearnError::BadResponse)?;
        Ok(Proposal {
            source: label,
            candidates: spec
                .entity_facets
                .into_iter()
                .map(|f| Candidate { name: f.name, words: f.examples, rationale: f.description })
                .collect(),
        })
    }

    /// **Curate a raw spec into canonical facet types.** The judgment half of neural discovery.
    ///
    /// The tagger and the transport solver do the mechanical work: they find typed spans and group them. What
    /// comes out is a list of raw entity-value clusters, and a cluster label is a VALUE. The reference's own
    /// committed spec has raw clusters named `missile`, `bo`, `guidance control`, `ph`, `ge`; its finished
    /// ontology reads `weapon-platform`, `control-system`, with those terms demoted to examples. The step
    /// between the two is this one, and skipping it puts `ph` in the index as a retrieval dimension.
    ///
    /// Three things are asked of the model, following the reference's curator exactly:
    ///
    /// * **merge** synonymous or overlapping clusters into one facet TYPE — a short lowercase slug naming a kind
    ///   of thing, not one of its values;
    /// * **drop** clusters that are boilerplate, noise, or too generic to be a facet;
    /// * name each surviving facet, listing the raw cluster terms it absorbs as its examples.
    ///
    /// This is judgment, not arithmetic, which is why it is a model call and not a formula — and why what comes
    /// back is a [`Proposal`] that still faces the MECE gate in [`SteelDb::adopt`] before anything is indexed.
    #[cfg(all(feature = "onnx", feature = "embed", any(feature = "paddock", feature = "bedrock")))]
    pub async fn curate(
        &self,
        raw: &crate::tagger_discover::RawSpec,
    ) -> Result<Proposal, LearnError> {
        use crate::agent::types::Msg;

        let cfg = self.provider_config()?;
        let label = match &cfg {
            #[cfg(feature = "paddock")]
            crate::agent::config::ProviderConfig::Paddock { model, .. } => format!("curate:local:{model}"),
            #[cfg(feature = "bedrock")]
            crate::agent::config::ProviderConfig::Bedrock { model_id, .. } => format!("curate:bedrock:{model_id}"),
            _ => "curate".to_string(),
        };
        let provider = cfg.build().await.map_err(LearnError::Transport)?;

        let ents = raw
            .entity_clusters
            .iter()
            .map(|c| format!("{}: {}", c.label, c.terms.join(", ")))
            .collect::<Vec<_>>()
            .join("\n");
        let rels = raw
            .relation_clusters
            .iter()
            .map(|c| format!("{}: {}", c.label, c.terms.join(", ")))
            .collect::<Vec<_>>()
            .join("\n");
        let prompt = format!("RAW ENTITY-VALUE CLUSTERS:\n{ents}\n\nRAW RELATION CLUSTERS:\n{rels}");

        let schema = curation_schema();
        let v = provider
            .chat_json(CURATE_SYSTEM, &[Msg::user_text(prompt)], &schema, "curate")
            .await
            .map_err(LearnError::Transport)?
            .ok_or_else(|| {
                LearnError::BadResponse(
                    "the model produced no curated ontology; curation needs structured output".into(),
                )
            })?;

        let facets = v.get("entity_facets").and_then(|f| f.as_array()).cloned().unwrap_or_default();
        let candidates: Vec<Candidate> = facets
            .iter()
            .filter_map(|f| {
                let name = crate::projector::slug(f.get("name")?.as_str()?);
                if name.is_empty() {
                    return None;
                }
                let words: Vec<String> = f
                    .get("examples")
                    .and_then(|e| e.as_array())
                    .map(|a| a.iter().filter_map(|x| x.as_str().map(str::to_string)).collect())
                    .unwrap_or_default();
                let rationale =
                    f.get("description").and_then(|d| d.as_str()).unwrap_or("").to_string();
                Some(Candidate { name, words, rationale })
            })
            .collect();
        Ok(Proposal { source: label, candidates })
    }

    /// The provider configuration behind this teacher, shared by `propose_categories` and `curate`.
    #[cfg(all(feature = "onnx", feature = "embed", any(feature = "paddock", feature = "bedrock")))]
    fn provider_config(&self) -> Result<crate::agent::config::ProviderConfig, LearnError> {
        match &self.kind {
            #[cfg(feature = "paddock")]
            Kind::Local { base_url, model } => Ok(crate::agent::config::ProviderConfig::Paddock {
                base_url: base_url.clone(),
                model: model.clone(),
                api_key: None,
            }),
            #[cfg(feature = "bedrock")]
            Kind::Bedrock { model_id } => Ok(crate::agent::config::ProviderConfig::Bedrock {
                model_id: model_id.clone(),
                region: std::env::var("AWS_REGION").ok(),
            }),
            Kind::Fixed(_) => Err(LearnError::NotConfigured(
                "a fixed teacher has no model to curate with".into(),
            )),
        }
    }
}

/// The curator's brief, following the reference's `curate.ts` system prompt.
#[cfg(all(feature = "onnx", feature = "embed", any(feature = "paddock", feature = "bedrock")))]
const CURATE_SYSTEM: &str = "You curate a DISCOVERED ontology into a clean, MECE facet schema for a \
directed-hypergraph bitset index. You get raw ENTITY-VALUE clusters (each a name plus example terms) and \
RELATION clusters.\n\
\n\
Every fact is stored as a PATH: `facet/value`. So the facet name is the KIND and the cluster terms are its \
VALUES. Before you accept a name, write the path out and read it:\n\
  network-generation/6g      GOOD - a kind, then one of its values\n\
  6g/6g                      WRONG - that is a value naming itself\n\
  cost-attribute/low-cost    GOOD\n\
  cost-effective/low-cost    WRONG - `cost-effective` is a value of some attribute\n\
  platform/uav               GOOD\n\
If the name you chose could itself appear on the RIGHT of the slash, it is a value: abstract it up to the kind it \
belongs to and use that instead. This is the single most common mistake — fix it before answering.\n\
\n\
Rules:\n\
- A facet name is a NOUN naming a kind of thing (platform, sensing-modality, vehicle-type, application-domain). \
Never a verb (translate, deliver), never an adjective (cost-effective, high-speed), never a bare instance (6g, \
new-south, monash).\n\
- MERGE synonymous or overlapping clusters into one type: optical/thermal/quantum becomes sensing-modality; \
payload/uav becomes platform. Set `examples` to the raw cluster terms the type absorbs, copied verbatim.\n\
- MUTUALLY EXCLUSIVE: each raw cluster belongs to exactly ONE facet. If two of your facets could both claim a \
cluster, they are the same facet — merge them. Do not emit both a general and a narrower version of the same \
kind.\n\
- COLLECTIVELY EXHAUSTIVE: every raw cluster is either absorbed by a facet or listed in `dropped`. Nothing is \
left unaccounted for.\n\
- DROP clusters that are boilerplate, noise, or too generic to be a facet: statement, benefits, project, \
ultimately, consensus, outcomes. A facet that would match nearly every document discriminates nothing.\n\
- Prefer FEWER, broader facets. Six well-separated kinds beat twelve overlapping ones.\n\
\n\
Be decisive. Do not invent content that is not present in the clusters.";

/// Bounded schema for curation. Every array has a `maxItems`: constraining a small model's decoding is not
/// enough on its own, because an unbounded array lets it run into the token limit and return
/// grammatically-valid but truncated JSON.
#[cfg(all(feature = "onnx", feature = "embed", any(feature = "paddock", feature = "bedrock")))]
fn curation_schema() -> serde_json::Value {
    serde_json::json!({
        "type": "object",
        "additionalProperties": false,
        "properties": {
            // 8 facets of 6 examples, not 12 of 12. The looser bound let a small model emit 144 long example
            // phrases and run past even a 4096-token budget, returning `finish_reason: length` with nothing
            // usable. The bound also agrees with the prompt, which asks for FEWER, broader facets — a schema
            // that permits what the instructions discourage is just an invitation to ignore them.
            "entity_facets": { "type": "array", "minItems": 1, "maxItems": 8,
              "items": { "type": "object", "additionalProperties": false, "properties": {
                "name": {"type": "string"},
                "description": {"type": "string"},
                "examples": {"type": "array", "maxItems": 6, "items": {"type": "string"}}
              }, "required": ["name", "description", "examples"] } },
            "relation_facets": { "type": "array", "maxItems": 8,
              "items": { "type": "object", "additionalProperties": false, "properties": {
                "name": {"type": "string"}, "head": {"type": "string"}, "tail": {"type": "string"}
              }, "required": ["name", "head", "tail"] } },
            "dropped": { "type": "array", "maxItems": 24, "items": {"type": "string"} }
        },
        "required": ["entity_facets", "dropped"]
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    fn docs() -> Vec<String> {
        [
            "Morty Shade defeated Wallace Gale at Ecruteak City during the Indigo Invitational in 2025.",
            "Bea Strike defeated Iris Draco at Ecruteak City during the Indigo Invitational in 2025.",
            "A habitat survey recorded Aggron near Sootopolis City at an elevation of 1082 m.",
            "A habitat survey recorded Salamence near Sootopolis City at an elevation of 2369 m.",
            "Milotic is not permitted in Series 1 play for the 2025 season.",
        ]
        .iter()
        .map(|s| s.to_string())
        .collect()
    }

    #[test]
    fn a_proposal_changes_nothing_until_adopted() {
        let db = SteelDb::ingest(docs()).unwrap();
        let before = db.categories().len();
        let _p = Proposal {
            source: "test".into(),
            candidates: vec![Candidate {
                name: "trainer".into(),
                words: vec!["defeated".into(), "Shade".into()],
                rationale: "people who compete".into(),
            }],
        };
        // holding a proposal must not alter the database
        assert_eq!(db.categories().len(), before);
    }

    #[test]
    fn a_fixed_teacher_needs_no_credentials() {
        // deliberately driven without an async runtime: the offline path must not require tokio, which is an
        // optional dependency, so the default build can still test learning end to end
        let db = SteelDb::ingest(docs()).unwrap();
        let p = Proposal {
            source: "fixed".into(),
            candidates: vec![Candidate {
                name: "ruling".into(),
                words: vec!["permitted".into(), "Series".into(), "season".into()],
                rationale: "competition rules".into(),
            }],
        };
        let teacher = Teacher::fixed(p.clone());
        let got = block_on(teacher.propose_categories(&db)).unwrap();
        assert_eq!(got.candidates, p.candidates);
    }

    /// Drive a future to completion without a runtime. Sound here because the fixed teacher never yields.
    fn block_on<F: std::future::Future>(mut fut: F) -> F::Output {
        use std::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
        fn noop(_: *const ()) {}
        fn clone(p: *const ()) -> RawWaker {
            RawWaker::new(p, &VTABLE)
        }
        static VTABLE: RawWakerVTable = RawWakerVTable::new(clone, noop, noop, noop);
        let waker = unsafe { Waker::from_raw(RawWaker::new(std::ptr::null(), &VTABLE)) };
        let mut cx = Context::from_waker(&waker);
        let mut fut = unsafe { std::pin::Pin::new_unchecked(&mut fut) };
        loop {
            match fut.as_mut().poll(&mut cx) {
                Poll::Ready(v) => return v,
                Poll::Pending => panic!("the fixed teacher must not yield"),
            }
        }
    }

    #[test]
    fn adoption_reports_a_verdict_per_candidate_and_can_reject() {
        let mut db = SteelDb::ingest(docs()).unwrap();
        let proposal = Proposal {
            source: "test".into(),
            candidates: vec![
                Candidate {
                    name: "ruling".into(),
                    words: vec!["permitted".into(), "Series".into()],
                    rationale: "rules".into(),
                },
                // deliberately a near-duplicate of the first, judged after it
                Candidate {
                    name: "ruling2".into(),
                    words: vec!["permitted".into(), "Series".into()],
                    rationale: "the same thing again".into(),
                },
            ],
        };
        let verdicts = db.adopt(&proposal);
        assert_eq!(verdicts.len(), 2, "one verdict per candidate");
        for v in &verdicts {
            assert!(!v.reason.is_empty(), "a rejection must be explicable: {v:?}");
        }
        // the gate is the point: a model cannot add what a deterministic test would refuse
        assert!(
            !verdicts[1].kept || verdicts[1].overlap < 0.99,
            "an exact duplicate should not be adopted unexamined: {:?}",
            verdicts[1]
        );
    }

    #[test]
    fn an_adopted_category_becomes_queryable() {
        let mut db = SteelDb::ingest(docs()).unwrap();
        let proposal = Proposal {
            source: "test".into(),
            candidates: vec![Candidate {
                name: "ruling".into(),
                words: vec!["permitted".into(), "season".into(), "Series".into()],
                rationale: "rules".into(),
            }],
        };
        let verdicts = db.adopt(&proposal);
        if verdicts[0].kept {
            let answer = db.query("ruling/*").expect("an adopted category must be queryable");
            assert!(!answer.is_empty(), "and must actually match documents");
        }
    }

    #[test]
    fn proposals_display_for_review_before_adoption() {
        let p = Proposal {
            source: "bedrock:test".into(),
            candidates: vec![Candidate {
                name: "trainer".into(),
                words: vec!["defeated".into()],
                rationale: "competitors".into(),
            }],
        };
        let shown = p.to_string();
        assert!(shown.contains("bedrock:test"), "{shown}");
        assert!(shown.contains("trainer"), "{shown}");
        assert!(shown.contains("competitors"), "the rationale must be reviewable: {shown}");
    }

    #[test]
    fn an_adopted_category_survives_into_an_artefact_and_is_followed_on_reload() {
        // The whole point of pairing `learn` with artefacts: the expensive, non-deterministic step runs once,
        // and every run afterwards is offline and identical. That only holds if what a teacher contributed is
        // actually written to the files that `ingest` follows — otherwise `learn` is a change you lose.
        let docs = docs();
        let mut db = SteelDb::ingest(docs.clone()).unwrap();
        let before: Vec<String> = db.categories().iter().map(|c| c.name.to_string()).collect();

        let proposal = Proposal {
            source: "test".into(),
            candidates: vec![Candidate {
                name: "ruling".into(),
                words: vec!["permitted".into(), "season".into(), "Series".into()],
                rationale: "competition rules".into(),
            }],
        };
        let verdicts = db.adopt(&proposal);
        if !verdicts[0].kept {
            // the gate is allowed to reject; there is then nothing to persist and nothing to assert
            return;
        }
        assert!(
            !before.contains(&"ruling".to_string()) && db.askable().contains(&"ruling/*".to_string()),
            "adoption should have added the category"
        );
        let expected = db.query("ruling/*").expect("adopted category must be queryable").len();

        let dir = std::env::temp_dir().join(format!("hsdb_learn_artifact_{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        db.save(&dir).expect("save");

        // a fresh process, no teacher, no network: the reload must follow what learning produced
        let reloaded = SteelDb::ingest_using(docs, &dir).expect("reload");
        assert!(
            reloaded.askable().contains(&"ruling/*".to_string()),
            "the adopted category must come back: {:?}",
            reloaded.askable()
        );
        assert_eq!(
            reloaded.query("ruling/*").expect("still queryable").len(),
            expected,
            "and answer identically without the teacher"
        );
        assert_eq!(db.tags(), reloaded.tags(), "tag for tag");
        let _ = std::fs::remove_dir_all(&dir);
    }
}