//! The ancestry renderer: the per-elite mermaid diagram, drawn from ONE `LineageFacts` walker
//! (split out of `reporting` by AGENTS.md rule 19).
use super::*;
impl CoreEngine {
/// The `## Ancestry` section of ONE champion's markdown file (`champion-<hash>-<fitness>.md`): the same
/// recorded lineage the stop card draws, as a mermaid `graph TB` a doc viewer renders.
pub(crate) fn lineage_markdown(&self, root: &str, root_role: &str) -> String {
let mut tree = LineageTree::new(self);
let has_parents = tree
.facts(root)
.map(|f| !f.parents.is_empty())
.unwrap_or(false);
let (diagram, cut) = tree.mermaid(root, root_role);
let mut prose = if has_parents {
"Read downward: an arrow goes from a parent to the child it made (`p1`/`p2` are the crossover slots), so this net sits at the bottom. **Gold** is this net, **blue** an ancestor still live at stop, **grey** one that was culled (the number after `†` is the clock it was culled at). `Δfit` on an arrow is the child's fit minus that parent's, signed so `+` means the child scored better. Edges are each net's recorded `created_from`; a culled parent's numbers come from its `nets/<hash>.json` tombstone."
.to_string()
} else {
"No recorded parents: this net entered as a founder — a random draw, an inherited `seed:` blueprint, or the initial batch — so its ancestry is the single box below."
.to_string()
};
if cut {
prose.push_str(&format!(
" The walk stops at {LINEAGE_MD_MAX_DEPTH} generations / {LINEAGE_MD_NODE_BUDGET} nets; each ancestor's own `nets/<hash>.json` still carries the next step back."
));
}
format!("## Ancestry\n\n{prose}\n\n{diagram}")
}
}
/// The three paints a lineage box can wear.
#[derive(Clone, Copy)]
struct LineagePaint {
fill: &'static str,
stroke: &'static str,
ink: &'static str,
width: &'static str,
}
/// The net the file is about (`champion-<hash>-<fitness>.md`).
const FOCUS: LineagePaint = LineagePaint {
fill: "#fff3cf",
stroke: "#8a5a00",
ink: "#2b1d00",
width: "2.5px",
};
/// An ancestor still live when the run stopped.
const LIVE: LineagePaint = LineagePaint {
fill: "#e6f1fb",
stroke: "#2f6fa8",
ink: "#0d2538",
width: "1.5px",
};
/// An ancestor that was culled (its `†clock` says
const CULLED: LineagePaint = LineagePaint {
fill: "#ededed",
stroke: "#5f5f5f",
ink: "#1f1f1f",
width: "1.5px",
};
/// How many generations the elite files' mermaid diagram walks.
const LINEAGE_MD_MAX_DEPTH: usize = 6;
/// The most nodes one elite diagram may name. Beyond this the walk stops
/// markdown says so, rather than shipping a 500-node graph in a per-net file.
const LINEAGE_MD_NODE_BUDGET: usize = 150;
/// The hashes named by a lineage string — `crossover-one-point:parents=<h1>,<h2>[+mut]`
/// `clone:parents=<h1>` — as the parent list, oldest first.
pub(super) fn lineage_parents(created_from: Option<&str>) -> Vec<String> {
let Some(raw) = created_from else {
return Vec::new();
};
// `+mut` is a flag ON the child (crossover, then mutated), not part of a parent id.
let head = raw.strip_suffix("+mut").unwrap_or(raw);
let Some((_, parents)) = head.split_once(":parents=") else {
return Vec::new();
};
parents
.split(',')
.map(str::trim)
.filter(|p| !p.is_empty())
.map(str::to_string)
.collect()
}
/// The first 8 hex of a hash — the width every other stop-time identity prints
pub(super) fn short_hash(hash: &str) -> String {
hash[..8.min(hash.len())].to_string()
}
/// One node's mermaid label: identity, origin, fit, and what happened to it (the root
/// says `ELITE`; an ancestor says `live` or the clock it was culled
pub(super) fn mermaid_node_label(
hash: &str,
facts: Option<&LineageFacts>,
root_role: Option<&str>,
) -> String {
let Some(facts) = facts else {
return short_hash(hash);
};
let mut parts = vec![
short_hash(hash),
origin_cell(facts.origin.as_deref(), facts.born),
];
if let Some(fit) = facts.fit {
parts.push(format!("fit {}", fmt_cell(fit)));
}
// The root says what the FILE says it is (`CHAMPION` in `champion-<hash>.md`) — one
// renderer, so the role stays the caller's.
if let Some(role) = root_role {
parts.push(role.to_string());
} else if facts.alive {
parts.push("live".to_string());
} else if let Some(clock) = facts.culled_at {
parts.push(format!("†{clock}"));
}
parts.join("<br/>")
}
/// One net's ancestry facts, whether it is LIVE or a culled tombstone.
#[derive(Clone, Debug)]
pub(super) struct LineageFacts {
/// The recorded lineage string (`created_from`), kept verbatim for [`origin_cell`].
origin: Option<String>,
/// Clock it entered the population.
born: usize,
/// The ranking value (risk-adjusted fit); `None` when it never measured.
fit: Option<f32>,
alive: bool,
culled_at: Option<usize>,
/// Parent hashes named by `created_from` (empty = a root).
parents: Vec<String>,
}
/// The ancestry card's one walker: resolve a hash (live memory first, then the tombstone
/// on disk), draw it, then recurse into its parents.
pub(super) struct LineageTree<'a> {
engine: &'a CoreEngine,
/// Resolved facts per hash — a shared ancestor is read from disk at most once.
cache: std::collections::HashMap<String, Option<LineageFacts>>,
}
impl<'a> LineageTree<'a> {
fn new(engine: &'a CoreEngine) -> Self {
Self {
engine,
cache: std::collections::HashMap::new(),
}
}
/// One net's facts: the live state first (a parent may still be alive),
/// `nets/<hash>.json` tombstone a cull leaves behind.
fn facts(&mut self, hash: &str) -> Option<LineageFacts> {
if let Some(hit) = self.cache.get(hash) {
return hit.clone();
}
let engine = self.engine;
let facts = if let Some(state) = engine.state.net(hash) {
Some(LineageFacts {
origin: state.created_from.clone(),
born: state.entered_at_step,
fit: engine.smoothed_fitness_of(hash),
alive: true,
culled_at: None,
parents: lineage_parents(state.created_from.as_deref()),
})
} else {
match crate::state::load_net_state(&engine.run_dir, hash) {
Ok(state) => Some(LineageFacts {
origin: state.created_from.clone(),
born: state.entered_at_step,
// A legacy tombstone may predate `final_risk_score`; the window mean
// then the only level it recorded, so it is read as the fit.
fit: state
.final_risk_score
.filter(|v| v.is_finite())
.or_else(|| state.final_fitness_mean.filter(|v| v.is_finite())),
alive: state.is_alive,
culled_at: state.culled_at_step,
parents: lineage_parents(state.created_from.as_deref()),
}),
Err(_) => None,
}
};
self.cache.insert(hash.to_string(), facts.clone());
facts
}
/// This net's ancestry as a mermaid `graph TB`: parents at the TOP, the net at the BOTTOM, one
/// arrow per parent → child edge.
fn mermaid(&mut self, root: &str, root_role: &str) -> (String, bool) {
let mut nodes: Vec<String> = Vec::new();
let mut edges: Vec<(String, String, usize, usize)> = Vec::new();
let mut seen: std::collections::HashSet<String> = std::collections::HashSet::new();
let mut stack: Vec<(String, usize)> = vec![(root.to_string(), 0)];
let mut cut = false;
while let Some((hash, depth)) = stack.pop() {
if !seen.insert(hash.clone()) {
continue;
}
if nodes.len() >= LINEAGE_MD_NODE_BUDGET {
cut = true;
break;
}
nodes.push(hash.clone());
let Some(facts) = self.facts(&hash) else {
continue;
};
if facts.parents.is_empty() {
continue;
}
if depth >= LINEAGE_MD_MAX_DEPTH {
cut = true;
continue;
}
let n = facts.parents.len();
for (i, parent) in facts.parents.iter().enumerate() {
edges.push((parent.clone(), hash.clone(), i + 1, n));
stack.push((parent.clone(), depth + 1));
}
}
let known: std::collections::HashSet<String> = nodes.iter().cloned().collect();
let direction = self.engine.fitness.direction();
let adjusted = |v: f32| match direction {
crate::utils::fitness::Direction::Maximize => v,
crate::utils::fitness::Direction::Minimize => -v,
};
// ── Contrast: every box is LIGHT, every label states its own near-black ink ──
// diagram shipped twice before with a readable-on-paper palette that a real viewer
let mut out = String::from("```mermaid\n");
// Front matter, not an `%%{init}%%` directive: Mermaid 12 defaults to the ELK layout, whose wires are rounded right angles, and directives are ignored at the default…
out.push_str(
"---\nconfig:\n layout: dagre\n theme: base\n themeVariables:\n background: \"#ffffff\"\n primaryColor: \"#e6f1fb\"\n primaryTextColor: \"#0d2538\"\n primaryBorderColor: \"#2f6fa8\"\n lineColor: \"#3d6b96\"\n textColor: \"#0d2538\"\n edgeLabelBackground: \"#ffffff\"\n fontSize: \"14px\"\n flowchart:\n htmlLabels: true\n curve: basis\n---\n",
);
out.push_str("graph TB\n");
// Classes first, so a viewer that only reads classes never sees an unstyled box.
for (name, paint) in [("focus", FOCUS), ("live", LIVE), ("culled", CULLED)] {
out.push_str(&format!(
" classDef {name} fill:{},stroke:{},stroke-width:{},color:{}\n",
paint.fill, paint.stroke, paint.width, paint.ink
));
}
for hash in &nodes {
let facts = self.facts(hash);
let is_root = hash == root;
// A tombstone is grey; everything else on the walk is a live ancestor.
let (paint, class) = if is_root {
(FOCUS, "focus")
} else if facts.as_ref().map(|f| !f.alive).unwrap_or(false) {
(CULLED, "culled")
} else {
(LIVE, "live")
};
let label = mermaid_node_label(hash, facts.as_ref(), is_root.then_some(root_role));
let id = short_hash(hash);
// Single quotes inside the span: the label itself is double-quoted mermaid.
out.push_str(&format!(
" n_{id}[\"<span style='color:{}'>{label}</span>\"]\n",
paint.ink
));
out.push_str(&format!(
" style n_{id} fill:{},stroke:{},stroke-width:{},color:{}\n",
paint.fill, paint.stroke, paint.width, paint.ink
));
out.push_str(&format!(" class n_{id} {class}\n"));
}
for (parent, child, slot, n) in &edges {
// A parent beyond the node budget was never declared: drop the edge
// cut instead of letting mermaid invent a blank node
if !known.contains(parent) || !known.contains(child) {
cut = true;
continue;
}
let parent_facts = self.facts(parent);
let child_facts = self.facts(child);
let mut label = if *n == 1 {
"p".to_string()
} else {
format!("p{slot}")
};
if let (Some(parent_facts), Some(child_facts)) = (parent_facts, child_facts) {
if let (Some(parent_fit), Some(child_fit)) = (parent_facts.fit, child_facts.fit) {
let gain = adjusted(child_fit) - adjusted(parent_fit);
label.push_str(&format!(
" · Δfit {}{}",
if gain >= 0.0 { "+" } else { "−" },
fmt_cell(gain.abs())
));
}
}
out.push_str(&format!(
" n_{} -->|\"{}\"| n_{}\n",
short_hash(parent),
label,
short_hash(child)
));
}
out.push_str("```\n");
(out, cut)
}
}