Commit B is a substantial architectural migration (REST endpoints to a unified RPC batch API, introducing room-scoped state, rewriting reducer/thread indexing, CLI restructuring, and updating extensive integration/grant tests) that changes the project's core API surface and permission model. Commit A is a well-scoped, tested algorithmic refinement to pair-selection heuristics in one file, valuable but far narrower in scope and impact than B's system-wide restructuring.
constitution · epochs · watch · epoch 3
comparison
c_2722a3195825 (tommy-mor) vs c_2595b6007624 (tommy-mor)
download prompt · raw event · cmp_0b4a0d392df6c0
council reasoning
B lands a foundational redesign: rooms as the permission/scope boundary separate from forum thread tags, a unified batch RPC surface replacing many REST handlers, and matching reducer/event/CLI/test updates—structure the project keeps building on. A is a precise, well-tested pair-priority improvement (attach isolates before isolate–isolate, then zip adjacent ranks) but is incremental product logic on an existing mechanism, so it carries less lasting architectural weight than B despite B’s larger mechanical migration surface.
Side B performs a substantial architectural migration: it replaces many individual REST endpoints with a unified RPC API, refactors the CLI to use it, introduces room-scoped operations and room/thread separation in events and the reducer, and updates tests and data structures throughout to support the new model. Side A is a well-targeted improvement to pair selection heuristics—adding smarter bridge prioritization, rank-based refinement ordering, and corresponding tests—but its impact is confined to one algorithm, whereas Side B establishes a broader, lasting platform redesign.
sides
A — c_2722a3195825 (tommy-mor)
message
[5db58b98] Improve vote pair selection for spanning trees and rank refinement. Prefer attaching unranked items to established components before comparing isolates, then zip down adjacent rank-centrality pairs once the pool is fully connected, skipping pairs that already have votes. Co-authored-by: Cursor <cursoragent@cursor.com>
diff preview
diff --git a/server/src/pair.rs b/server/src/pair.rs
index 54b5d2417e9dba04ed8df422156e274c2b2f76b2..c14de4b0502c8b5a17cddf3746077739d56e03e0 100644
--- a/server/src/pair.rs
+++ b/server/src/pair.rs
@@ -3,13 +3,21 @@
//! Pair selection prefers **bridge** votes — comparisons between items in
//! different connected components of the voted-pairs graph — so the pool
//! merges into one ranking group before refining within it.
+//!
+//! Among unvoted bridges, prefer merging established voted components, then
+//! attaching a never-voted child to an established component, and only then
+//! comparing two never-voted children (so the voted graph grows as one tree).
+//!
+//! Once every pool child sits in one voted component, refinement **zips** down
+//! the rank-centrality order: prefer 1 vs 2, then 2 vs 3, and so on, skipping
+//! pairs that already have a vote.
use rand::seq::SliceRandom;
use std::collections::{HashMap, HashSet};
use crate::{
path_types::ItemId,
- ranking::connected_components_from_voted_pairs,
+ ranking::{connected_components_from_voted_pairs, ranked_items},
reducer::{GlobalTree, GroupState},
};
@@ -28,36 +36,77 @@ fn pair_is_voted(group: &GroupState, a: &ItemId, b: &ItemId) -> bool {
group.voted_pairs.contains(&(i, j))
}
-/// Component id per pool item: voted-pairs graph components plus one id per
-/// never-voted child.
-fn component_ids(group: &GroupState, pool: &[ItemId]) -> HashMap<ItemId, usize> {
+/// Voted-pairs layout for pool items: component id per item plus which ids are
+/// multi-node voted components (ranked groups in the UI).
+struct ComponentLayout {
+ ids: HashMap<ItemId, usize>,
+ established: HashSet<usize>,
+}
+
+fn component_layout(group: &GroupState, pool: &[ItemId]) -> ComponentLayout {
let n = group.idx_to_item.len();
let (comps, isolates) =
connected_components_from_voted_pairs(n, group.voted_pairs.iter().copied());
- let mut out: HashMap<ItemId, usize> = HashMap::new();
+ let mut established = HashSet::new();
+ let mut ids: HashMap<ItemId, usize> = HashMap::new();
for (comp_idx, comp) in comps.iter().enumerate() {
+ if comp.len() >= 2 {
+ established.insert(comp_idx);
+ }
for &idx in comp {
if idx < n {
- out.insert(group.idx_to_item[idx].clone(), comp_idx);
+ ids.insert(group.idx_to_item[idx].clone(), comp_idx);
}
}
}
let mut next = comps.len();
for &idx in &isolates {
if idx < n {
- out.insert(group.idx_to_item[idx].clone(), next);
+ ids.insert(group.idx_to_item[idx].clone(), next);
next += 1;
}
}
for item in pool {
- out.entry(item.clone()).or_insert_with(|| {
+ ids.entry(item.clone()).or_insert_with(|| {
let id = next;
next += 1;
id
});
}
- out
+ ComponentLayout { ids, established }
+}
+
+/// Every pool child shares one multi-node voted component (spanning tree phase done).
+fn pool_fully_connected(layout: &ComponentLayout, pool: &[ItemId]) -> bool {
+ if pool.len() < 2 {
+ return false;
+ }
+ let mut comp_id = None;
+ for item in pool {
+ let Some(id) = layout.ids.get(item) else {
+ return false;
+ };
+ if !layout.established.contains(id) {
+ return false;
+ }
+ match comp_id {
+ None => comp_id = Some(*id),
+ Some(expected) if expected == *id => {}
+ _ => return false,
+ }
+ }
+ comp_id.is_some()
+}
+
+/// Pool children that appear in `group`, sorted best rank first.
+fn ranked_pool_order(group: &GroupState, pool: &[ItemId]) -> Vec<ItemId> {
+ let pool_set: HashSet<_> = pool.iter().collect();
+ ranked_items(group)
+ .into_iter()
+ .map(|r| r.item)
+ .filter(|id| pool_set.contains(id))
+ .collect()
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
@@ -72,19 +121,108 @@ enum PairPriority {
WithinVoted = 3,
}
-fn pair_priority(
+/// Tie-break among unvoted bridge pairs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+enum BridgeSubPriority {
+ /// Both endpoints lie in established (multi-node) voted components.
+ MergeEstablished = 0,
+ /// One established component member and one never-voted child.
+ AttachIsolate = 1,
+ /// Two never-voted children (separate singleton components).
+ IsolatePair = 2,
+}
+
+/// Tie-break among within-component pairs once the pool is one connected group.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+struct WithinSubPriority {
+ /// 1 = adjacent ranks (i vs i+1); larger = farther apart in the order.
+ rank_gap: usize,
+ /// min rank index of the two — zip from the top (1 vs 2 before 2 vs 3).
+ zip_index: usize,
+}
+
+const WITHIN_SUB_WORST: WithinSubPriority = WithinSubPriority {
+ rank_gap: usize::MAX,
+ zip_index: usize::MAX,
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+struct PairSortKey {
+ priority: PairPriority,
+ bridge_sub: BridgeSubPriority,
+ within_sub: WithinSubPriority,
+}
+
+fn item_in_established(layout: &ComponentLayout, item: &ItemId) -> bool {
+ layout
+ .ids
+ .get(item)
+ .is_some_and(|id| layout.established.contains(id))
+}
+
+fn bridge_sub_priority(layout: &ComponentLayout, a: &ItemId, b: &ItemId) -> BridgeSubPriority {
+ let a_est = item_in_established(layout, a);
+ let b_est = item_in_established(layout, b);
+ match (a_est, b_est) {
+ (true, true) => BridgeSubPriority::MergeEstablished,
+ (true, false) | (false, true) => BridgeSubPriority::AttachIsolate,
+ (false, false) => BridgeSubPriority::IsolatePair,
+ }
+}
+
+fn within_sub_priority(
+ group: &GroupState,
+ pool: &[ItemId],
+ layout: &ComponentLayout,
+ a: &ItemId,
+ b: &ItemId,
+) -> WithinSubPriority {
+ if !pool_fully_connected(layout, pool) {
+ return WITHIN_SUB_WORST;
+ }
+ let order = ranked_pool_order(group, pool);
+ let (Some(i), Some(j)) = (order.iter().position(|x| x == a), order.iter().position(|x| x == b))
+ else {
+ return WITHIN_SUB_WORST;
+ };
+ WithinSubPriority {
+ rank_gap: i.abs_diff(j),
+ zip_index: i.min(j),
+ }
+}
+
+fn pair_sort_key(
group: &GroupState,
- components: &HashMap<ItemId, usize>,
+ pool: &[ItemId],
+ layout: &ComponentLayout,
a: &ItemId,
b: &ItemId,
-) -> PairPriority {
+) -> PairSortKey {
let voted = pair_is_voted(group, a, b);
- let bridge = components.get(a) != components.get(b);
- match (bridge, voted) {
+ let bridge = layout.ids.get(a) != layout.ids.get(b);
+ let priority = match (bridge, voted) {
(true, false) => PairPriority::BridgeUnvoted,
(false, false) => PairPriority::WithinUnvoted,
(true, true) => PairPriority::BridgeVoted,
(false, true) => PairPriority::WithinVoted,
+ };
+ let bridge_sub = if priority == PairPriority::BridgeUnvoted {
+ bridge_sub_priority(layout, a, b)
+ } else {
+ BridgeSubPriority::MergeEstablished
+ };
+ let within_sub = if matches!(
+ priority,
+ PairPriority::WithinUnvoted | PairPriority::WithinVoted
+ ) {
+ within_sub_priority(group, pool, layout, a, b)
+ } else {
+ WITHIN_SUB_WORST
+ };
+ PairSortKey {
+ priority,
+ bridge_sub,
+ within_sub,
}
}
@@ -109,9 +247,12 @@ fn candidate_pairs(pool: &[ItemId], exclude: Option<(&ItemId, &ItemId)>) -> Vec<
/// Pick the next pair to vote on within `pool`.
///
-/// 1. Prefer unvoted **bridge** pairs (connect separate ranking components).
-/// 2. Then unvoted within-component pairs (refinement).
-/// 3. Then already-voted pairs (re-compare).
+/// 1. Prefer unvoted **bridge** pairs (connect separate ranking components),
+/// with sub-priority: merge established components, attach an isolate to
+/// established, then compare two isolates.
+/// 2. Then unvoted within-component pairs; when the pool is one connected group,
+/// prefer adjacent ranks (1 vs 2, 2 vs 3, …) in order, skipping voted pairs.
+/// 3. Then already-voted pairs (re-compare), with the same zip ordering.
pub fn suggest_next_pair_in_pool(
group: &GroupState,
pool: &[ItemId],
@@ -121,15 +262,15 @@ pub fn suggest_next_pair_in_pool(
if candidates.is_empty() {
return None;
}
- let components = component_ids(group, pool);
+ let layout = component_layout(group, pool);
let best = candidates
.iter()
- .map(|(a, b)| (pair_priority(group, &components, a, b), (a, b)))
- .min_by_key(|(p, _)| *p)?
+ .map(|(a, b)| (pair_sort_key(group, pool, &layout, a, b), (a, b)))
+ .min_by_key(|(k, _)| *k)?
.0;
let best_pairs: Vec<(ItemId, ItemId)> = candidates
.into_iter()
- .filter(|(a, b)| pair_priority(group, &components, a, b) == best)
+ .filter(|(a, b)| pair_sort_key(group, pool, &layout, a, b) == best)
.collect();
best_pairs.choose(&mut rand::thread_rng()).cloned()
}
@@ -303,6 +444,38 @@ mod tests {
assert!(from_ab && from_cd, "expected bridge pair, got {:?}", chosen);
}
+ #[test]
+ fn suggest_prefers_attach_over_isolate_pair_among_many_unranked() {
+ let parent = ItemId::parse("reddit.com/r/rust").unwrap();
+ let mut tree = seed_children(
+ &parent,
+ &[
+ "reddit.com/r/rust/a",
+ "reddit.com/r/rust/b",
+ "reddit.com/r/rust/c",
+ "reddit.com/r/rust/d",
+ "reddit.com/r/rust/e",
+ ],
+ );
+ let ab =
+ VoteData::from_recorded(1, "reddit.com/r/rust/a", "reddit.com/r/rust/b", 2, 1).unwrap();
+ tree.apply_vote(&parent, ab);
+ let group = tree.get(&parent).unwrap().local_ranking.clone();
+ let pool = children_of(&tree, &parent);
+ let pair = suggest_next_pair_in_pool(&group, &pool, None).unwrap();
+ let chosen = pair_set(&pair);
+ let from_ab =
+ chosen.contains("reddit.com/r/rust/a") || chosen.contains("reddit.com/r/rust/b");
+ let from_cde = chosen.contains("reddit.com/r/rust/c")
+ || chosen.contains("reddit.com/r/rust/d")
+ || chosen.contains("reddit.com/r/rust/e");
+ assert!(
+ from_ab && from_cde,
+ "expected ranked+unranked attach, got {:?}",
+ chosen
+ );
+ }
+
#[test]
fn suggest_connects_isolate_to_existing_component() {
let parent = ItemId::parse("reddit.com/r/rust").unwrap();
@@ -325,6 +498,65 @@ mod tests {
assert!(chosen.contains("reddit.com/r/rust/a") || chosen.contains("reddit.com/r/rust/b"));
}
+ #[test]
+ fn suggest_zips_adjacent_ranks_when_tree_complete() {
+ let parent = ItemId::parse("reddit.com/r/rust").unwrap();
+ let mut tree = seed_children(
+ &parent,
+ &[
+ "reddit.com/r/rust/a",
+ "reddit.com/r/rust/b",
+ "reddit.com/r/rust/c",
+ ],
+ );
+ // Star at a connects all three; b-c is the only unvoted adjacent pair left.
+ for (a, b, l, r) in [
+ ("reddit.com/r/rust/a", "reddit.com/r/rust/b", 3, 1),
+ ("reddit.com/r/rust/a", "reddit.com/r/rust/c", 2, 1),
+ ] {
+ let v = VoteData::from_recorded(1, a, b, l, r).unwrap();
+ tree.apply_vote(&parent, v);
+ }
+ let group = tree.get(&parent).unwrap().local_ranking.clone();
+ let pool = children_of(&tree, &parent);
+ let pair = suggest_next_pair_in_pool(&group, &pool, None).unwrap();
+ let chosen = pair_set(&pair);
+ // a-b and a-c voted;
… preview truncated; 1,687 characters omittedB — c_2595b6007624 (tommy-mor)
message
[96b6da05] rpc + reducer changes first pass
diff preview
diff --git a/cli/src/main.rs b/cli/src/main.rs
index 630c5dea1f78c0ec9bc53e6b96234a0dc75bb705..8d0442959f4332bafe499a2a8cdf364731a06871 100644
--- a/cli/src/main.rs
+++ b/cli/src/main.rs
@@ -21,8 +21,9 @@ struct Cli {
cmd: Option<Command>,
}
+/// Commands scoped to a room (`public` or `shortid/slug`).
#[derive(Subcommand, Debug)]
-enum Command {
+enum ScopedCmd {
/// Browse the garden (ontology) — light mode, ranked by votes
Garden {
#[command(subcommand)]
@@ -174,6 +175,23 @@ enum Command {
#[arg(long)]
json: bool,
},
+}
+
+#[derive(Subcommand, Debug)]
+enum Command {
+ /// Public site (same as room `public`)
+ Public {
+ #[command(subcommand)]
+ sub: ScopedCmd,
+ },
+ /// Private room id (`shortid/slug` from `room create`)
+ Private {
+ /// Room id, e.g. `a1b2c3d/my-project`
+ #[arg(value_name = "ROOM_ID")]
+ room: String,
+ #[command(subcommand)]
+ sub: ScopedCmd,
+ },
/// Show all activity since you last posted (global feed)
///
@@ -628,6 +646,37 @@ fn http_client() -> Result<reqwest::Client> {
.build()?)
}
+async fn send_rpc(
+ client: &reqwest::Client,
+ base: &str,
+ bearer: Option<&str>,
+ commands: Vec<RpcCommand>,
+) -> Result<RpcBatchResponse> {
+ let url = format!("{}/api/v0/rpc", base.trim_end_matches('/'));
+ let mut req = client.post(url).json(&RpcBatch(commands));
+ if let Some(b) = bearer {
+ req = req.header("Authorization", format!("Bearer {}", b));
+ }
+ let resp = req.send().await?;
+ let status = resp.status();
+ let text = resp.text().await.unwrap_or_default();
+ if !status.is_success() {
+ return Err(anyhow!("rpc HTTP {}: {}", status, text.trim()));
+ }
+ serde_json::from_str(&text).map_err(|e| anyhow!("rpc response: {e}"))
+}
+
+fn rpc_line_ok(line: &RpcLine) -> Result<&RpcResult> {
+ if !line.ok {
+ let mut m = line.error.clone().unwrap_or_else(|| "rpc error".into());
+ if let Some(h) = &line.hint {
+ m.push_str(&format!("\nhint: {h}"));
+ }
+ return Err(anyhow!(m));
+ }
+ line.result.as_ref().ok_or_else(|| anyhow!("rpc missing result"))
+}
+
/// Normalize ontology path for API. Accepts path with or without ~/ (shell expands ~ to $HOME).
/// Returns a bare slug path (e.g. `languages/python`) with no leading `/` or `~/`.
/// Call `ontology_path_for_api_query` before sending `item=` / `parent=` params so the server
@@ -729,231 +778,262 @@ fn write_secret_file(name: &str, contents: &str) -> Result<()> {
Ok(())
}
-#[tokio::main]
-async fn main() -> Result<()> {
- let Cli { cmd, server } = Cli::parse();
-
- // If no command provided, print the guide
- let Some(cmd) = cmd else {
- print!("{}", include_str!("../GUIDE.sorter"));
- return Ok(());
- };
-
- let base = server.trim_end_matches('/');
-
- match cmd {
- Command::Healthz { json } => {
- let client = http_client()?;
- let url = format!("{base}/healthz");
- let body = client.get(url).send().await?.text().await?;
- if json {
- // Wrap plain text response in a JSON object
- println!("{}", serde_json::json!({ "ok": true, "body": body.trim() }));
- } else {
- println!("{body}");
- }
- }
-
- Command::Search { query, json } => {
- let client = http_client()?;
- let url = format!("{base}/api/v0/search?q={}", urlencoding::encode(&query));
- let resp: slug_types::SearchResponse = expect_json(client.get(url).send().await?).await?;
- if json {
- println!("{}", serde_json::to_string_pretty(&resp)?);
- } else {
- if !resp.items.is_empty() {
- println!("items ({})", resp.items.len());
- for item in &resp.items {
- print!(" {}", item.path);
- if let Some(body) = &item.body {
- let first_line = body.lines().next().unwrap_or("").trim();
- if !first_line.is_empty() {
- print!(" {}", first_line);
+async fn run_scoped(base: &str, room: &str, sub: ScopedCmd) -> Result<()> {
+ let room = room.trim();
+ let client = http_client()?;
+ match sub {
+ ScopedCmd::Garden { sub } => match sub {
+ GardenCmd::Tree { json } => {
+ let batch = send_rpc(&client, base, None, vec![RpcCommand::GetLeaves { room: room.to_string() }]).await?;
+ match rpc_line_ok(&batch.results[0])? {
+ RpcResult::Leaves(resp) => {
+ if json {
+ println!("{}", serde_json::to_string_pretty(&resp)?);
+ } else {
+ for p in &resp.paths {
+ println!("~/{}", p);
}
}
- println!();
- }
- }
- if !resp.threads.is_empty() {
- if !resp.items.is_empty() { println!(); }
- println!("threads ({})", resp.threads.len());
- let now_ms = std::time::SystemTime::now()
- .duration_since(std::time::UNIX_EPOCH)
- .unwrap_or_default()
- .as_millis() as i64;
- for t in &resp.threads {
- println!(" {} {}n {}", t.tag, t.post_count, slug_types::timeago::timeago(now_ms, t.last_activity));
- }
- }
- if !resp.posts.is_empty() {
- if !resp.items.is_empty() || !resp.threads.is_empty() { println!(); }
- println!("posts ({})", resp.posts.len());
- let now_ms = std::time::SystemTime::now()
- .duration_since(std::time::UNIX_EPOCH)
- .unwrap_or_default()
- .as_millis() as i64;
- for p in &resp.posts {
- let first_line = p.snippet.lines().next().unwrap_or("").trim();
- println!(" {} · {} {}", p.thread, slug_types::timeago::timeago(now_ms, p.ts), first_line);
- }
- }
- if resp.items.is_empty() && resp.threads.is_empty() && resp.posts.is_empty() {
- println!("no results");
- }
- }
- }
-
- Command::Garden { sub } => match sub {
- GardenCmd::Tree { json } => {
- let client = http_client()?;
- let url = format!("{base}/api/v0/leaves");
- let builder = client.get(url);
- let resp: LeavesResponse = expect_json(builder.send().await?).await?;
- if json {
- println!("{}", serde_json::to_string_pretty(&resp)?);
- } else {
- for p in &resp.paths {
- println!("~/{}", p);
}
+ _ => return Err(anyhow!("unexpected RPC result")),
}
}
-
GardenCmd::Body { path, json, full } => {
let path = normalize_ontology_path_input(&path).map_err(anyhow::Error::msg)?;
let item_q = ontology_path_for_api_query(&path);
- let client = http_client()?;
- let mut url = format!("{base}/api/v0/item?item={}", urlencoding::encode(&item_q));
- if full {
- url.push_str("&full=true");
- }
- let builder = client.get(url);
- let resp: ItemResponse = expect_json(builder.send().await?).await?;
- if json {
- println!("{}", serde_json::to_string_pretty(&resp)?);
- } else {
- print_item_response(&resp);
+ let batch = send_rpc(
+ &client,
+ base,
+ None,
+ vec![RpcCommand::GetGardenItem {
+ room: room.to_string(),
+ item_path: item_q,
+ full: Some(full),
+ }],
+ )
+ .await?;
+ match rpc_line_ok(&batch.results[0])? {
+ RpcResult::GardenItem(resp) => {
+ if json {
+ println!("{}", serde_json::to_string_pretty(&resp)?);
+ } else {
+ print_item_response(&resp);
+ }
+ }
+ _ => return Err(anyhow!("unexpected RPC result")),
}
}
-
GardenCmd::Children { paths, depth, json } => {
let paths: Vec<String> = paths
.iter()
.map(|p| normalize_ontology_path_input(p).map_err(anyhow::Error::msg))
.collect::<Result<Vec<_>>>()?;
- let client = http_client()?;
let parent_param = paths
.iter()
.map(|p| ontology_path_for_api_query(p))
.collect::<Vec<_>>()
.join(",");
- let mut url = format!("{base}/api/v0/rank?parent={}", urlencoding::encode(&parent_param));
- if let Some(d) = depth {
- url.push_str(&format!("&depth={d}"));
- }
- let builder = client.get(url);
- let resp: RankResponse = expect_json(builder.send().await?).await?;
-
- if json {
- println!("{}", serde_json::to_string_pretty(&resp)?);
- } else {
- print_rank_response(&resp);
+ let batch = send_rpc(
+ &client,
+ base,
+ None,
+ vec![RpcCommand::GetGardenRank {
+ room: room.to_string(),
+ parent_path: parent_param,
+ depth,
+ offset: None,
+ limit: None,
+ percent: None,
+ }],
+ )
+ .await?;
+ match rpc_line_ok(&batch.results[0])? {
+ RpcResult::GardenRank(resp) => {
+ if json {
+ println!("{}", serde_json::to_string_pretty(&resp)?);
+ } else {
+ print_rank_response(&resp);
+ }
+ }
+ _ => return Err(anyhow!("unexpected RPC result")),
}
}
-
GardenCmd::Pair { path, json } => {
let path = normalize_ontology_path_input(&path).map_err(anyhow::Error::msg)?;
let parent_q = ontology_path_for_api_query(&path);
- let client = http_client()?;
- let url = format!("{base}/api/v0/pair?parent={}", urlencoding::encode(&parent_q));
- let builder = client.get(url);
- let resp: PairResponse = expect_json(builder.send().await?).await?;
- if json {
- println!("{}", serde_json::to_string_pretty(&resp)?);
- } else {
- print_pair_response(&resp);
+ let batch = send_rpc(
+ &client,
+ base,
+ None,
+ vec![RpcCommand::GetPair {
+ room: room.to_string(),
+ parent_path: parent_q,
+ }]
… preview truncated; 237,234 characters omittedHardlinks — judgments / attempts / prompt
judgments
attempts
Prompt text is loaded only by the download route.