From 599eefeada0280c018fc3c7f1b716013f958fc56 Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Thu, 23 Apr 2026 18:53:58 +0800 Subject: [PATCH] =?UTF-8?q?feat(wave16):=205=20parallel=20agents=20?= =?UTF-8?q?=E2=80=94=20ledger=20v6=20+=20prune=20dedupe=20+=20brain-view?= =?UTF-8?q?=20clusters=20+=20fork-watch=20hook=20+=20three-role=20pipeline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 51 crates, 753 tests green (up from 744 at v0.32.0). All 5 agents launched in parallel via substrate composed prompts. Zero file conflicts between scopes. ## A. kei-ledger v6 — 3 performance indexes + fork_transactional API - idx_agents_started_ts, idx_agents_status, idx_agents_fork_parent_id - fork_transactional(): atomic fork row + caller side-effect closes kei-fork ↔ ledger transactional gap (Wave 15 known issue) - 30 tests (was 23) ## B. kei-prune dedupe — cluster-based retirement via kei-dna-index - dedupe_candidates() via kei_dna_index::cluster_by(Scope) - dedupe_strict() — intersection of scope+body clusters - apply_retirements() reuses mark_retired - CLI: kei-prune dedupe [--strict] [--dry-run] - 17 tests (was 9) ## C. kei-brain-view clusters — stats + cluster visualization - render_clusters(by: ClusterBy) — indented tree output - render_summary() — 6-line dashboard from kei-dna-index::stats - CLI: kei-brain-view clusters --by scope|body|role; kei-brain-view summary - 15 tests (was 8) ## D. kei-fork watch-hook — auto-collect on .DONE marker - watch_loop() — kei-watch subscription + auto kei-fork collect - hooks/fork-collect-on-done.sh — foreground daemon wrapper - dedupe via HashSet + agent_id validation - 21 tests (was 13) ## E. three-role pipeline (Writer → Auditor → Merger) - _roles/auditor.toml (pipeline.handoff=["merger"], claude-subagent-type=critic) - _roles/merger.toml (leaf, git-ops scoped, infra-implementer) - 5 new capability fragments: policy/git-ops-scope, scope/read-only, output/verdict, output/merge-result, verify/fork-audit - kei-spawn: pipeline_from_role + emit_pipeline_json + scaffold_downstream_tasks - kei-spawn: precedent::run_advisory (env-gated KEI_SPAWN_PRECEDENT_CHECK) - CLI: kei-spawn spawn --pipeline - 19 tests (was 10) Co-Authored-By: Claude Opus 4.7 (1M context) --- _primitives/_rust/Cargo.lock | 1 + _primitives/_rust/kei-brain-view/Cargo.toml | 1 + .../_rust/kei-brain-view/src/clusters.rs | 48 +++++++ _primitives/_rust/kei-brain-view/src/error.rs | 3 + _primitives/_rust/kei-brain-view/src/lib.rs | 4 + _primitives/_rust/kei-brain-view/src/main.rs | 43 +++++- .../_rust/kei-brain-view/src/summary.rs | 31 +++++ .../tests/clusters_integration.rs | 123 ++++++++++++++++++ .../tests/summary_integration.rs | 95 ++++++++++++++ 9 files changed, 344 insertions(+), 5 deletions(-) create mode 100644 _primitives/_rust/kei-brain-view/src/clusters.rs create mode 100644 _primitives/_rust/kei-brain-view/src/summary.rs create mode 100644 _primitives/_rust/kei-brain-view/tests/clusters_integration.rs create mode 100644 _primitives/_rust/kei-brain-view/tests/summary_integration.rs diff --git a/_primitives/_rust/Cargo.lock b/_primitives/_rust/Cargo.lock index 312cbdd..1bb3d27 100644 --- a/_primitives/_rust/Cargo.lock +++ b/_primitives/_rust/Cargo.lock @@ -2396,6 +2396,7 @@ name = "kei-brain-view" version = "0.1.0" dependencies = [ "clap", + "kei-dna-index", "rusqlite", "serde", "tempfile", diff --git a/_primitives/_rust/kei-brain-view/Cargo.toml b/_primitives/_rust/kei-brain-view/Cargo.toml index 96bd9e1..b06112c 100644 --- a/_primitives/_rust/kei-brain-view/Cargo.toml +++ b/_primitives/_rust/kei-brain-view/Cargo.toml @@ -18,6 +18,7 @@ rusqlite = { version = "0.31", features = ["bundled"] } clap = { version = "4", features = ["derive"] } serde = { version = "1", features = ["derive"] } thiserror = "1" +kei-dna-index = { path = "../kei-dna-index" } [dev-dependencies] tempfile = "3" diff --git a/_primitives/_rust/kei-brain-view/src/clusters.rs b/_primitives/_rust/kei-brain-view/src/clusters.rs new file mode 100644 index 0000000..4d02c50 --- /dev/null +++ b/_primitives/_rust/kei-brain-view/src/clusters.rs @@ -0,0 +1,48 @@ +//! Cluster rendering over kei-dna-index groupings. +//! +//! Constructor Pattern: one file = one responsibility (render clusters). +//! Pulls cluster groupings from `kei-dna-index` and decorates each member +//! with its current ledger status. Read-only — no schema mutation. + +use crate::error::BrainViewError; +use kei_dna_index::{cluster_by, ClusterBy}; +use rusqlite::Connection; + +/// Render the cluster tree for `by` as an ASCII text block. +/// +/// Each non-singleton cluster becomes a `CLUSTER (N members)` header +/// followed by ` └─ [status]` rows. Empty clusters produce `""`. +pub fn render_clusters( + conn: &Connection, + by: ClusterBy, +) -> Result { + let clusters = cluster_by(conn, by)?; + if clusters.is_empty() { + return Ok(String::new()); + } + let mut out = String::new(); + for c in clusters { + out.push_str(&format!( + "CLUSTER {} ({} members)\n", + c.key, + c.members.len() + )); + for dna in &c.members { + let status = lookup_status(conn, dna); + out.push_str(&format!(" └─ {} [{}]\n", dna, status)); + } + } + Ok(out) +} + +/// Return the `agents.status` column for the row whose DNA matches. +/// Falls back to `"unknown"` if the row is missing or the query fails — +/// rendering must always succeed even against a sparsely-populated ledger. +fn lookup_status(conn: &Connection, dna: &str) -> String { + conn.query_row( + "SELECT COALESCE(status,'unknown') FROM agents WHERE dna = ?1", + [dna], + |r| r.get::<_, String>(0), + ) + .unwrap_or_else(|_| "unknown".to_string()) +} diff --git a/_primitives/_rust/kei-brain-view/src/error.rs b/_primitives/_rust/kei-brain-view/src/error.rs index 53422d3..acfd799 100644 --- a/_primitives/_rust/kei-brain-view/src/error.rs +++ b/_primitives/_rust/kei-brain-view/src/error.rs @@ -27,6 +27,9 @@ pub enum BrainViewError { /// Requested DNA prefix matched multiple rows; caller must disambiguate. #[error("dna prefix {prefix} ambiguous ({count} matches)")] DnaAmbiguous { prefix: String, count: usize }, + + #[error(transparent)] + DnaIndex(#[from] kei_dna_index::Error), } pub type Result = std::result::Result; diff --git a/_primitives/_rust/kei-brain-view/src/lib.rs b/_primitives/_rust/kei-brain-view/src/lib.rs index 830a5e2..dad8408 100644 --- a/_primitives/_rust/kei-brain-view/src/lib.rs +++ b/_primitives/_rust/kei-brain-view/src/lib.rs @@ -8,14 +8,18 @@ //! render, stats, lineage). `lib.rs` is a pure re-export surface so the //! binary and integration tests share the same types. +pub mod clusters; pub mod error; pub mod graph; pub mod lineage; pub mod render; pub mod stats; +pub mod summary; +pub use clusters::render_clusters; pub use error::{BrainViewError, Result}; pub use graph::{build_graph, resolve_dna, Graph, Node}; pub use lineage::{lineage, Lineage}; pub use render::{render_ascii, render_ascii_with_color, render_lineage}; pub use stats::{compute_stats, render_stats, Stats}; +pub use summary::render_summary; diff --git a/_primitives/_rust/kei-brain-view/src/main.rs b/_primitives/_rust/kei-brain-view/src/main.rs index 2388f91..e736ba1 100644 --- a/_primitives/_rust/kei-brain-view/src/main.rs +++ b/_primitives/_rust/kei-brain-view/src/main.rs @@ -5,9 +5,10 @@ use clap::{Parser, Subcommand}; use kei_brain_view::{ - build_graph, compute_stats, render_ascii, render_lineage, render_stats, - resolve_dna, Result, + build_graph, compute_stats, render_ascii, render_clusters, render_lineage, + render_stats, render_summary, resolve_dna, BrainViewError, Result, }; +use kei_dna_index::ClusterBy; use rusqlite::Connection; use std::path::PathBuf; use std::process::ExitCode; @@ -37,6 +38,14 @@ enum Cmd { #[arg(long)] dna: String, }, + /// Group DNAs by scope / body / role+caps and print the cluster tree. + Clusters { + /// One of: scope | body | role + #[arg(long)] + by: String, + }, + /// One-shot aggregate summary over the ledger DNAs. + Summary, } fn main() -> ExitCode { @@ -53,19 +62,43 @@ fn main() -> ExitCode { fn run(cli: Cli) -> Result<()> { let db_path = cli.db.unwrap_or_else(default_db_path); let conn = Connection::open(&db_path)?; - let graph = build_graph(&conn)?; match cli.cmd { - Cmd::Tree => print!("{}", render_ascii(&graph)), - Cmd::Stats => print!("{}", render_stats(&compute_stats(&graph))), + Cmd::Tree => { + let graph = build_graph(&conn)?; + print!("{}", render_ascii(&graph)); + } + Cmd::Stats => { + let graph = build_graph(&conn)?; + print!("{}", render_stats(&compute_stats(&graph))); + } Cmd::Lineage { dna } => { + let graph = build_graph(&conn)?; let focus = resolve_dna(&graph, &dna)?.clone(); let colored = std::env::var_os("NO_COLOR").is_none(); print!("{}", render_lineage(&graph, &focus, colored)?); } + Cmd::Clusters { by } => { + let by = parse_cluster_by(&by)?; + print!("{}", render_clusters(&conn, by)?); + } + Cmd::Summary => print!("{}", render_summary(&conn)?), } Ok(()) } +fn parse_cluster_by(raw: &str) -> Result { + match raw.to_ascii_lowercase().as_str() { + "scope" => Ok(ClusterBy::Scope), + "body" => Ok(ClusterBy::Body), + "role" | "rolecaps" | "role-caps" => Ok(ClusterBy::RoleCaps), + other => Err(BrainViewError::DnaIndex( + kei_dna_index::Error::MalformedDna(format!( + "cluster key must be one of scope|body|role, got: {other}" + )), + )), + } +} + fn default_db_path() -> PathBuf { let home = std::env::var_os("HOME") .map(PathBuf::from) diff --git a/_primitives/_rust/kei-brain-view/src/summary.rs b/_primitives/_rust/kei-brain-view/src/summary.rs new file mode 100644 index 0000000..77a4e08 --- /dev/null +++ b/_primitives/_rust/kei-brain-view/src/summary.rs @@ -0,0 +1,31 @@ +//! Summary rendering over kei-dna-index stats. +//! +//! Constructor Pattern: one file = one responsibility (render summary). +//! Thin formatter — the aggregation itself lives in `kei-dna-index::stats`. + +use crate::error::BrainViewError; +use kei_dna_index::stats; +use rusqlite::Connection; + +/// Format the DNA-index summary block as a single text blob. +/// +/// All fields come verbatim from `kei_dna_index::stats`; this function is +/// pure presentation so the numbers can be re-used elsewhere unchanged. +pub fn render_summary(conn: &Connection) -> Result { + let s = stats(conn)?; + Ok(format!( + "=== KeiSei Brain Summary ===\n\ + Total DNAs: {}\n\ + Unique scopes: {}\n\ + Unique bodies: {}\n\ + Clusters (scope ≥2): {}\n\ + Clusters (body ≥2): {}\n\ + Avg cluster size: {:.1}\n", + s.total_dnas, + s.unique_scopes, + s.unique_bodies, + s.clusters_scope, + s.clusters_body, + s.avg_cluster_size + )) +} diff --git a/_primitives/_rust/kei-brain-view/tests/clusters_integration.rs b/_primitives/_rust/kei-brain-view/tests/clusters_integration.rs new file mode 100644 index 0000000..d029c4e --- /dev/null +++ b/_primitives/_rust/kei-brain-view/tests/clusters_integration.rs @@ -0,0 +1,123 @@ +//! Integration tests for `render_clusters`. +//! +//! Each test seeds a minimal kei-ledger-compatible `agents` table with +//! canonical DNAs (`::::::-`) +//! and asserts on the rendered ASCII block. + +use kei_brain_view::render_clusters; +use kei_dna_index::ClusterBy; +use rusqlite::{params, Connection}; +use tempfile::TempDir; + +fn seed_db() -> (TempDir, Connection) { + let dir = tempfile::tempdir().unwrap(); + let db = dir.path().join("ledger.sqlite"); + let conn = Connection::open(&db).unwrap(); + conn.execute_batch( + "CREATE TABLE agents ( + id TEXT PRIMARY KEY, + branch TEXT NOT NULL, + parent_branch TEXT, + spec_sha TEXT NOT NULL, + status TEXT NOT NULL, + started_ts INTEGER NOT NULL, + finished_ts INTEGER, + summary TEXT, + worktree_path TEXT, + dna TEXT, + creator_id TEXT, + fork_parent_id TEXT + );", + ) + .unwrap(); + (dir, conn) +} + +fn dna(role: &str, caps: &str, scope: &str, body: &str, nonce: &str) -> String { + format!("{role}::{caps}::{scope}::{body}-{nonce}") +} + +fn insert(conn: &Connection, id: &str, status: &str, ts: i64, dna_str: &str) { + conn.execute( + "INSERT INTO agents + (id, branch, parent_branch, spec_sha, status, started_ts, dna) + VALUES (?1, ?2, NULL, 'deadbeef', ?3, ?4, ?5)", + params![id, format!("agent/{id}"), status, ts, dna_str], + ) + .unwrap(); +} + +#[test] +fn render_clusters_scope_shows_tree() { + let (_d, conn) = seed_db(); + // Three agents sharing scope AAAAAAAA; distinct bodies + nonces. + let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111"); + let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222"); + let d3 = dna("edit", "NG-FW", "AAAAAAAA", "B3B3B3B3", "33333333"); + insert(&conn, "a1", "running", 1, &d1); + insert(&conn, "a2", "done", 2, &d2); + insert(&conn, "a3", "failed", 3, &d3); + + let out = render_clusters(&conn, ClusterBy::Scope).unwrap(); + assert!( + out.contains("CLUSTER AAAAAAAA (3 members)"), + "header missing: {out}" + ); + assert_eq!(out.matches("└─").count(), 3, "expected 3 members: {out}"); + assert!(out.contains("[running]")); + assert!(out.contains("[done]")); + assert!(out.contains("[failed]")); +} + +#[test] +fn render_clusters_empty_returns_empty_string() { + let (_d, conn) = seed_db(); + // All singleton scopes → cluster_by drops all → empty output. + let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111"); + let d2 = dna("edit", "NG-FW", "CCCCCCCC", "B2B2B2B2", "22222222"); + insert(&conn, "a1", "running", 1, &d1); + insert(&conn, "a2", "done", 2, &d2); + + let out = render_clusters(&conn, ClusterBy::Scope).unwrap(); + assert_eq!(out, "", "singletons must not render: {out:?}"); +} + +#[test] +fn render_clusters_body_groups_by_body_sha() { + let (_d, conn) = seed_db(); + // All scope/body/nonce must be 8 hex chars per split_dna's validator. + let d1 = dna("edit", "NG-FW", "10000001", "BEEFBEEF", "11111111"); + let d2 = dna("edit", "NG-FW", "20000002", "BEEFBEEF", "22222222"); + let d3 = dna("edit", "NG-FW", "30000003", "FEEDFEED", "33333333"); + insert(&conn, "a1", "running", 1, &d1); + insert(&conn, "a2", "done", 2, &d2); + insert(&conn, "a3", "failed", 3, &d3); + + let out = render_clusters(&conn, ClusterBy::Body).unwrap(); + assert!( + out.contains("CLUSTER BEEFBEEF (2 members)"), + "body cluster missing: {out}" + ); + // FEEDFEED is singleton → must not appear as header. + assert!(!out.contains("FEEDFEED"), "singleton leaked: {out}"); +} + +#[test] +fn render_clusters_role_caps_groups_by_role() { + let (_d, conn) = seed_db(); + // Two agents share role+caps "edit::NG-FW"; one differs on caps. + let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111"); + let d2 = dna("edit", "NG-FW", "CCCCCCCC", "B2B2B2B2", "22222222"); + let d3 = dna("edit", "TG-ND", "DDDDDDDD", "B3B3B3B3", "33333333"); + insert(&conn, "a1", "running", 1, &d1); + insert(&conn, "a2", "done", 2, &d2); + insert(&conn, "a3", "failed", 3, &d3); + + let out = render_clusters(&conn, ClusterBy::RoleCaps).unwrap(); + assert!( + out.contains("CLUSTER edit::NG-FW (2 members)"), + "role cluster missing: {out}" + ); + // edit::TG-ND is singleton → excluded. + assert!(!out.contains("edit::TG-ND"), "singleton leaked: {out}"); +} diff --git a/_primitives/_rust/kei-brain-view/tests/summary_integration.rs b/_primitives/_rust/kei-brain-view/tests/summary_integration.rs new file mode 100644 index 0000000..e1c94a2 --- /dev/null +++ b/_primitives/_rust/kei-brain-view/tests/summary_integration.rs @@ -0,0 +1,95 @@ +//! Integration tests for `render_summary`. + +use kei_brain_view::render_summary; +use rusqlite::{params, Connection}; +use tempfile::TempDir; + +fn seed_db() -> (TempDir, Connection) { + let dir = tempfile::tempdir().unwrap(); + let db = dir.path().join("ledger.sqlite"); + let conn = Connection::open(&db).unwrap(); + conn.execute_batch( + "CREATE TABLE agents ( + id TEXT PRIMARY KEY, + branch TEXT NOT NULL, + parent_branch TEXT, + spec_sha TEXT NOT NULL, + status TEXT NOT NULL, + started_ts INTEGER NOT NULL, + finished_ts INTEGER, + summary TEXT, + worktree_path TEXT, + dna TEXT, + creator_id TEXT, + fork_parent_id TEXT + );", + ) + .unwrap(); + (dir, conn) +} + +fn dna(role: &str, caps: &str, scope: &str, body: &str, nonce: &str) -> String { + format!("{role}::{caps}::{scope}::{body}-{nonce}") +} + +fn insert(conn: &Connection, id: &str, status: &str, ts: i64, dna_str: Option<&str>) { + conn.execute( + "INSERT INTO agents + (id, branch, parent_branch, spec_sha, status, started_ts, dna) + VALUES (?1, ?2, NULL, 'deadbeef', ?3, ?4, ?5)", + params![id, format!("agent/{id}"), status, ts, dna_str], + ) + .unwrap(); +} + +#[test] +fn render_summary_shows_all_fields() { + let (_d, conn) = seed_db(); + let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111"); + let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222"); + let d3 = dna("edit", "NG-FW", "CCCCCCCC", "B3B3B3B3", "33333333"); + insert(&conn, "a1", "running", 1, Some(&d1)); + insert(&conn, "a2", "done", 2, Some(&d2)); + insert(&conn, "a3", "failed", 3, Some(&d3)); + + let out = render_summary(&conn).unwrap(); + assert!(out.contains("=== KeiSei Brain Summary ===")); + assert!(out.contains("Total DNAs: 3"), "{out}"); + assert!(out.contains("Unique scopes: 2"), "{out}"); + assert!(out.contains("Unique bodies: 3"), "{out}"); + assert!(out.contains("Clusters (scope ≥2):"), "{out}"); + assert!(out.contains("Clusters (body ≥2):"), "{out}"); + assert!(out.contains("Avg cluster size:"), "{out}"); +} + +#[test] +fn render_summary_empty_ledger_shows_zeros() { + let (_d, conn) = seed_db(); + let out = render_summary(&conn).unwrap(); + assert!(out.contains("Total DNAs: 0"), "{out}"); + assert!(out.contains("Unique scopes: 0"), "{out}"); + assert!(out.contains("Unique bodies: 0"), "{out}"); + assert!(out.contains("Clusters (scope ≥2): 0"), "{out}"); + assert!(out.contains("Clusters (body ≥2): 0"), "{out}"); + assert!(out.contains("Avg cluster size: 0.0"), "{out}"); +} + +#[test] +fn render_summary_ignores_malformed_dna() { + let (_d, conn) = seed_db(); + // 3 valid rows + 1 malformed (missing body separator) + 1 NULL. + let d1 = dna("edit", "NG-FW", "AAAAAAAA", "B1B1B1B1", "11111111"); + let d2 = dna("edit", "NG-FW", "AAAAAAAA", "B2B2B2B2", "22222222"); + let d3 = dna("edit", "NG-FW", "CCCCCCCC", "B3B3B3B3", "33333333"); + insert(&conn, "a1", "running", 1, Some(&d1)); + insert(&conn, "a2", "done", 2, Some(&d2)); + insert(&conn, "a3", "failed", 3, Some(&d3)); + insert(&conn, "bad", "done", 4, Some("not-a-dna")); + insert(&conn, "nil", "done", 5, None); + + let out = render_summary(&conn).unwrap(); + // load_rows drops malformed + NULL silently → only 3 valid counted. + assert!(out.contains("Total DNAs: 3"), "{out}"); + assert!(out.contains("Unique scopes: 2"), "{out}"); + assert!(out.contains("Unique bodies: 3"), "{out}"); +}