Side A performs a genuine architectural improvement, moving path/URL canonicalization and room-aware href construction into a shared slug-types crate with correct-by-construction newtypes (GardenItemUrl, ForumThreadUrl, TildeOntologyPath), eliminating duplicated string-based helpers and reducing future room-prefixing bugs across the whole API surface. Side B is a solid, more localized fix (faster scan avoiding full replay, better error detail, new compile --ingest debug feature) but its impact is confined to the sorterc devtool rather than the core server's type safety and correctness guarantees.
constitution · epochs · watch · epoch 3
comparison
c_5e9a63e9d276 (tommy-mor) vs c_6209cd238b3f (tommy-mor)
download prompt · raw event · cmp_8ebd65d166b7b2
council reasoning
A centralizes canonicalization and room-aware href rules into shared slug-types newtypes (GardenItemUrl, ForumThreadUrl, TildeOntologyPath) and threads those through API/DTOs and RPC, replacing ad-hoc string helpers with lasting, correct-by-construction path identity. B’s sorterc work is real and useful (fast parse-only scan, richer parse_error output, compile --ingest), but it is localized tooling rather than core domain structure.
Side A makes a lasting architectural improvement by moving canonical path normalization and URL construction into a shared `types::paths` module, replacing ad hoc string helpers with typed wrappers (`GardenItemUrl`, `ForumThreadUrl`, `TildeOntologyPath`) across the API and shared data structures. This centralizes path identity, reduces duplication, and makes many RPC/JSON interfaces correct-by-construction, whereas Side B mainly improves offline tooling with faster log scanning, richer parse errors, and a useful `compile --ingest` workflow but does not affect the project's core data model as broadly.
sides
A — c_5e9a63e9d276 (tommy-mor)
message
[a888d56c] refactor: centralize path identity in slug-types Move canonicalization and CanonicalItemUrl into types::paths with GardenItemUrl, ForumThreadUrl, and TildeOntologyPath for JSON hrefs. Server canonical_path and path_types re-export slug-types; RPC and validation build hrefs via those types instead of string helpers. Made-with: Cursor
diff preview
diff --git a/server/src/api/helpers.rs b/server/src/api/helpers.rs
index 9b71491e9f9efc44a2a4beba09be8f64bd2ff2ee..03b3e77911ccd662bec8635345dafe2593cf242e 100644
--- a/server/src/api/helpers.rs
+++ b/server/src/api/helpers.rs
@@ -4,12 +4,12 @@ use axum::{
Json,
};
use sha2::{Digest, Sha256};
+use slug_types::paths::{CanonicalItemUrl, GardenItemUrl};
use slug_types::*;
use std::collections::HashMap;
use crate::{
canonical_path::canonicalize_item,
- path_types::CanonicalItemUrl,
ranking::connected_components_from_voted_pairs,
};
@@ -30,64 +30,6 @@ pub fn now_ms() -> i64 {
t.as_millis() as i64
}
-/// Serialize a canonical item for JSON: absolute URLs stay as-is; bare paths get a `/` prefix.
-pub fn item_path_for_api(item: &str) -> String {
- if item.starts_with("http://") || item.starts_with("https://") {
- item.to_string()
- } else {
- format!("/{}", item)
- }
-}
-
-/// Same as [`item_path_for_api`], but for private rooms ontology items are prefixed with
-/// `/r/{short}/{slug}` so the URL matches the web app (`/r/…/~/…` routes).
-pub fn item_path_for_api_in_room(item: &str, room_wire: &str) -> String {
- let room = room_wire.trim();
- if room.is_empty() || room == "public" {
- return item_path_for_api(item);
- }
- let Some((short, slug)) = room.split_once('/') else {
- return item_path_for_api(item);
- };
- if short.is_empty() || slug.is_empty() {
- return item_path_for_api(item);
- }
- let Some(c) = CanonicalItemUrl::parse(item) else {
- return item_path_for_api(item);
- };
- let root = CanonicalItemUrl::ontology_root();
- let item_norm = c.as_str().trim_end_matches('/');
- let root_norm = root.as_str().trim_end_matches('/');
- if let Some(tail) = c.tilde_tail() {
- return if tail.is_empty() {
- format!("https://slug.social/r/{short}/{slug}/~")
- } else {
- format!("https://slug.social/r/{short}/{slug}/~/{}", tail)
- };
- }
- if item_norm == root_norm {
- return format!("https://slug.social/r/{short}/{slug}/~");
- }
- item_path_for_api(item)
-}
-
-/// Absolute thread URL for forum JSON (`/t/…` vs `/r/…/t/…`).
-pub fn forum_thread_web_url(room_wire: &str, thread_tag: &str) -> String {
- let room = room_wire.trim();
- let tag = thread_tag.trim().trim_start_matches('#');
- if room.is_empty() || room == "public" {
- format!("https://slug.social/t/{tag}")
- } else if let Some((short, slug)) = room.split_once('/') {
- if short.is_empty() || slug.is_empty() {
- format!("https://slug.social/t/{tag}")
- } else {
- format!("https://slug.social/r/{short}/{slug}/t/{tag}")
- }
- } else {
- format!("https://slug.social/t/{tag}")
- }
-}
-
/// Resolve an item path as a first-class canonical path.
pub fn resolve_item(item: &str) -> Result<String, String> {
let canonical = canonicalize_item(item);
@@ -109,14 +51,12 @@ pub fn parse_parent_specs(parent: Option<&String>) -> Vec<String> {
}
/// Apply offset+limit pagination to the flattened component rankings.
-/// Items are flattened in component order (largest component first), then unranked last.
-/// Returns (components, unranked_items) after the window.
pub fn paginate_rankings(
components: Vec<RankComponent>,
- unranked_items: Vec<String>,
+ unranked_items: Vec<GardenItemUrl>,
offset: usize,
limit: Option<usize>,
-) -> (Vec<RankComponent>, Vec<String>) {
+) -> (Vec<RankComponent>, Vec<GardenItemUrl>) {
let mut remaining_skip = offset;
let mut remaining_take = limit.unwrap_or(usize::MAX);
let mut out_components: Vec<RankComponent> = Vec::new();
@@ -141,7 +81,7 @@ pub fn paginate_rankings(
});
}
- let out_unranked: Vec<String> = if remaining_take > 0 {
+ let out_unranked: Vec<GardenItemUrl> = if remaining_take > 0 {
unranked_items
.into_iter()
.skip(remaining_skip)
@@ -183,11 +123,9 @@ pub fn is_pair_voted(group: &crate::reducer::GroupState, a: &str, b: &str) -> bo
group.voted_pairs.contains(&(i, j))
}
-/// Compute graph connectivity stats for a set of items within the ranking group.
pub fn compute_connectivity_stats(group: &crate::reducer::GroupState, pool: &[String]) -> ConnectivityStats {
let n = pool.len();
- // Map pool items to global indices (items not yet in the group get no index)
let global_idxs: Vec<Option<usize>> = pool
.iter()
.map(|it| {
@@ -197,7 +135,6 @@ pub fn compute_connectivity_stats(group: &crate::reducer::GroupState, pool: &[St
.collect();
let present: Vec<usize> = global_idxs.iter().filter_map(|x| *x).collect();
- // Build local index mapping for items that exist in the ranking group
let global_to_local: HashMap<usize, usize> = present
.iter()
.enumerate()
@@ -213,7 +150,6 @@ pub fn compute_connectivity_stats(group: &crate::reducer::GroupState, pool: &[St
}),
);
- // Items not in the ranking group at all are also isolates
let items_not_in_group = global_idxs.iter().filter(|x| x.is_none()).count();
let num_components = comps.len() + isolates.len() + items_not_in_group;
@@ -237,52 +173,3 @@ pub fn vote_touches_path(a: &str, b: &str, parent_canon: &str) -> bool {
let under = |item: &str| item == parent_canon || item.starts_with(&format!("{}/", parent_canon));
under(a) || under(b)
}
-
-#[cfg(test)]
-mod wire_url_tests {
- use super::{forum_thread_web_url, item_path_for_api_in_room};
-
- #[test]
- fn public_room_unchanged() {
- let u = "https://slug.social/~/a/b";
- assert_eq!(item_path_for_api_in_room(u, "public"), u);
- }
-
- #[test]
- fn private_room_prefixes_ontology() {
- assert_eq!(
- item_path_for_api_in_room("https://slug.social/~/topic/x", "9ab12cd/my-room"),
- "https://slug.social/r/9ab12cd/my-room/~/topic/x"
- );
- }
-
- #[test]
- fn private_room_ontology_root() {
- assert_eq!(
- item_path_for_api_in_room("https://slug.social/~", "9ab12cd/my-room"),
- "https://slug.social/r/9ab12cd/my-room/~"
- );
- assert_eq!(
- item_path_for_api_in_room("https://slug.social/~/", "9ab12cd/my-room"),
- "https://slug.social/r/9ab12cd/my-room/~"
- );
- }
-
- #[test]
- fn external_url_untouched_in_private_room() {
- let u = "https://example.com/z";
- assert_eq!(item_path_for_api_in_room(u, "9ab12cd/my-room"), u);
- }
-
- #[test]
- fn forum_web_public_vs_room() {
- assert_eq!(
- forum_thread_web_url("public", "debate"),
- "https://slug.social/t/debate"
- );
- assert_eq!(
- forum_thread_web_url("9ab12cd/my-room", "#debate"),
- "https://slug.social/r/9ab12cd/my-room/t/debate"
- );
- }
-}
diff --git a/server/src/api/mod.rs b/server/src/api/mod.rs
index 042aa248305f9362a3be78f9eea2a5abf6ba707a..cf22cb0129366c3aed031bc86f3197a4321cb806 100644
--- a/server/src/api/mod.rs
+++ b/server/src/api/mod.rs
@@ -24,8 +24,7 @@ pub use auth::{
pub use helpers::{
api_error, compute_connectivity_stats, is_pair_voted, now_ms, paginate_rankings,
- parse_parent_specs, pick_random_distinct, sha256_hex, resolve_item, vote_touches_path,
- item_path_for_api,
+ parse_parent_specs, pick_random_distinct, resolve_item, sha256_hex, vote_touches_path,
};
pub use rpc::handle_rpc_batch;
diff --git a/server/src/api/rpc.rs b/server/src/api/rpc.rs
index 5b91f5836625eedbb1cd9423168046e3fb576c17..5f7d50188f1381267402f2e57e671234ef5db2fd 100644
--- a/server/src/api/rpc.rs
+++ b/server/src/api/rpc.rs
@@ -8,6 +8,7 @@ use axum::{
Json,
};
use rand::seq::SliceRandom;
+use slug_types::paths::{ForumThreadUrl, GardenItemUrl, TildeOntologyPath};
use slug_types::*;
use crate::{
@@ -27,9 +28,8 @@ use crate::{
use super::auth::verify_bearer_principal;
use super::helpers::{
- compute_connectivity_stats, forum_thread_web_url, is_pair_voted, item_path_for_api,
- item_path_for_api_in_room, now_ms, paginate_rankings, parse_parent_specs, pick_random_distinct,
- resolve_item, vote_touches_path,
+ compute_connectivity_stats, is_pair_voted, now_ms, paginate_rankings, parse_parent_specs,
+ pick_random_distinct, resolve_item, vote_touches_path,
};
use super::validate::{normalize_room_and_thread, validate_ingest_document};
@@ -184,7 +184,7 @@ fn compute_scope_rank_changes(
};
if changed {
changes.push(RankChange {
- item: item_path_for_api_in_room(&item, room_wire),
+ item: GardenItemUrl::from_storage_str(&item, room_wire),
before: b,
after: a,
});
@@ -206,7 +206,7 @@ fn compute_scope_rank_changes(
parent: if parent.is_empty() {
"/".to_string()
} else {
- item_path_for_api_in_room(parent, room_wire)
+ GardenItemUrl::from_storage_str(parent, room_wire).into_inner()
},
changes,
})
@@ -302,7 +302,7 @@ fn build_rank_response_for_content(
.ranked
.into_iter()
.map(|r| RankRow {
- item: item_path_for_api_in_room(r.item.as_str(), room_wire),
+ item: GardenItemUrl::from_stored(&r.item, room_wire),
percent: if want_percent {
Some((r.score / max_score) * 100.0)
} else {
@@ -315,10 +315,10 @@ fn build_rank_response_for_content(
})
.collect();
- let prefixed_unranked: Vec<String> = rankings
+ let prefixed_unranked: Vec<GardenItemUrl> = rankings
.unranked_items
.into_iter()
- .map(|s| item_path_for_api_in_room(s.as_str(), room_wire))
+ .map(|s| GardenItemUrl::from_stored(&s, room_wire))
.collect();
let (components, unranked_items) = if offset > 0 || limit.is_some() {
@@ -537,13 +537,13 @@ async fn rpc_post(
(
"npx slugsocial public garden pair".to_string(),
"npx slugsocial public garden rank".to_string(),
- forum_thread_web_url("public", &thread_id),
+ ForumThreadUrl::from_room_tag("public", &thread_id),
)
} else {
(
format!("npx slugsocial private {room_key} garden pair"),
format!("npx slugsocial private {room_key} garden rank"),
- forum_thread_web_url(&room_key, &thread_id),
+ ForumThreadUrl::from_room_tag(&room_key, &thread_id),
)
};
@@ -664,7 +664,7 @@ async fn rpc_check(
.ranked
.into_iter()
.map(|r| RankRow {
- item: item_path_for_api_in_room(r.item.as_str(), &room_key),
+ item: GardenItemUrl::from_stored(&r.item, &room_key),
score: r.score,
percent: None,
})
@@ -672,12 +672,12 @@ async fn rpc_check(
})
.collect();
CheckScopeRanking {
- parent: item_path_for_api_in_room(parent.as_str(), &room_key),
+ parent: GardenItemUrl::from_stored(parent, &room_key).into_inner(),
components,
unranked_items: scoped
.unranked_items
.into_iter()
- .map(|it| item_path_for_api_in_room(it.as_str(), &room_key))
+ .map(|it| GardenItemUrl::from_stored(&it, &room_key))
.collect(),
}
})
@@ -687,13 +687,13 @@ async fn rpc_check(
vec![
"npx slugsocial public forum post <TAG> --delegate <uuid:rig:
… preview truncated; 46,249 characters omittedB — c_6209cd238b3f (tommy-mor)
message
[6e344666] Improve sorterc scan speed, errors, and ingest compile. Make scan a fast DSL parse pass with human-readable output, surface full parse_error details, and add compile --ingest for single-event replay from a log. Co-authored-by: Cursor <cursoragent@cursor.com>
diff preview
diff --git a/server/src/offline.rs b/server/src/offline.rs
index 54ad0ded096a305ef8454ab2cdd1c3af71b14f5d..2db6f67e22e00a24ce673d13095644dd9fa9342d 100644
--- a/server/src/offline.rs
+++ b/server/src/offline.rs
@@ -28,6 +28,10 @@ pub struct CompileResult {
pub threads: Vec<String>,
pub rankings: Vec<CheckScopeRanking>,
pub stats: CompileStats,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub ingest_id: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub ingest_line: Option<usize>,
}
#[derive(Debug, Clone, Serialize)]
@@ -36,6 +40,8 @@ pub struct CompileError {
pub error: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub hint: Option<String>,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub parse_error: Option<String>,
}
#[derive(Debug, Clone, Serialize)]
@@ -50,7 +56,7 @@ pub struct MalformedIngest {
pub id: String,
pub room_id: String,
pub thread_tag: String,
- pub reason: String,
+ pub parse_error: String,
}
#[derive(Debug, Clone, Serialize)]
@@ -59,9 +65,36 @@ pub struct ScanResult {
pub path: String,
pub total_lines: usize,
pub parsed_events: usize,
+ pub ingest_events: usize,
pub bad_json_lines: Vec<BadJsonLine>,
pub malformed_ingests: Vec<MalformedIngest>,
- pub skipped_ingests: usize,
+}
+
+#[derive(Debug)]
+pub enum CompileIngestError {
+ NotFound(String),
+ Io(std::io::Error),
+ Compile(CompileError),
+}
+
+impl CompileIngestError {
+ pub fn into_compile_error(self) -> CompileError {
+ match self {
+ Self::NotFound(id) => CompileError {
+ ok: false,
+ error: format!("ingest not found: {id}"),
+ hint: Some("pass the ingest event id from events.jsonl".into()),
+ parse_error: None,
+ },
+ Self::Io(e) => CompileError {
+ ok: false,
+ error: format!("io error: {e}"),
+ hint: None,
+ parse_error: None,
+ },
+ Self::Compile(e) => e,
+ }
+ }
}
fn document_stats(doc: &dsl::Document) -> CompileStats {
@@ -166,19 +199,22 @@ fn rankings_for_simulated(
.collect()
}
-/// Validate and simulate one `.sorter` document against optional base reducer state.
-pub fn compile_document(
+fn compile_document_inner(
base: &ReducerState,
room: &str,
text: &str,
+ ingest_id: Option<String>,
+ ingest_line: Option<usize>,
) -> Result<CompileResult, CompileError> {
let room_key = room.trim();
let scope = scope_from_room_wire(room_key);
let validated = validate_ingest_document(base, text, &scope).map_err(|(_, message, hint)| {
+ let parse_error = dsl::parse_full(text).err().map(|e| e.to_string());
CompileError {
ok: false,
error: message,
hint,
+ parse_error,
}
})?;
@@ -200,15 +236,27 @@ pub fn compile_document(
threads: threads_in_document(text),
rankings: rankings_for_simulated(&simulated, &scope, room_key, &validated.doc),
stats: document_stats(&validated.doc),
+ ingest_id,
+ ingest_line,
})
}
+/// Validate and simulate one `.sorter` document against optional base reducer state.
+pub fn compile_document(
+ base: &ReducerState,
+ room: &str,
+ text: &str,
+) -> Result<CompileResult, CompileError> {
+ compile_document_inner(base, room, text, None, None)
+}
+
fn ingest_parse_error(raw: &str) -> Option<String> {
dsl::parse_full(raw).err().map(|e| e.to_string())
}
-fn load_events_from_jsonl(path: &Path) -> Result<(Vec<(usize, Event)>, Vec<BadJsonLine>), std::io::Error> {
+fn load_events_from_jsonl(path: &Path) -> Result<(usize, Vec<(usize, Event)>, Vec<BadJsonLine>), std::io::Error> {
let text = std::fs::read_to_string(path)?;
+ let total_lines = text.lines().count();
let mut events = Vec::new();
let mut bad_json_lines = Vec::new();
for (idx, line) in text.lines().enumerate() {
@@ -225,61 +273,90 @@ fn load_events_from_jsonl(path: &Path) -> Result<(Vec<(usize, Event)>, Vec<BadJs
}),
}
}
- Ok((events, bad_json_lines))
+ Ok((total_lines, events, bad_json_lines))
}
-/// Replay a JSONL event log into reducer state (same rules as server boot).
-pub fn load_reducer_from_jsonl(path: &Path) -> Result<(ReducerState, Vec<BadJsonLine>), std::io::Error> {
- let (events, bad_json_lines) = load_events_from_jsonl(path)?;
+fn replay_events(events: &[(usize, Event)]) -> ReducerState {
let mut state = ReducerState::default();
for (_line_no, ev) in events {
- state.apply_event(ev);
+ state.apply_event(ev.clone());
}
- Ok((state, bad_json_lines))
+ state
}
-/// Scan an events.jsonl for corrupt JSON lines and ingests that fail DSL replay.
-pub fn scan_jsonl(path: &Path) -> Result<ScanResult, std::io::Error> {
- let text = std::fs::read_to_string(path)?;
- let total_lines = text.lines().count();
- let (events, bad_json_lines) = load_events_from_jsonl(path)?;
+/// Replay a JSONL event log into reducer state (same rules as server boot).
+pub fn load_reducer_from_jsonl(path: &Path) -> Result<(ReducerState, Vec<BadJsonLine>), std::io::Error> {
+ let (_total_lines, events, bad_json_lines) = load_events_from_jsonl(path)?;
+ Ok((replay_events(&events), bad_json_lines))
+}
- let mut malformed_ingests = Vec::new();
- let mut skipped_ingests = 0usize;
- let mut state = ReducerState::default();
- let parsed_events = events.len();
+/// Find one ingest in a log and compile it against all prior events as base state.
+pub fn compile_ingest_from_log(path: &Path, ingest_id: &str) -> Result<CompileResult, CompileIngestError> {
+ let (_total_lines, events, bad_json_lines) = load_events_from_jsonl(path).map_err(CompileIngestError::Io)?;
+ if !bad_json_lines.is_empty() {
+ return Err(CompileIngestError::Compile(CompileError {
+ ok: false,
+ error: format!("jsonl has {} corrupt line(s)", bad_json_lines.len()),
+ hint: Some("fix the log or use `sorterc scan`".into()),
+ parse_error: None,
+ }));
+ }
+
+ let needle = ingest_id.trim();
+ let mut found: Option<(usize, Ingest)> = None;
+ let mut prior: Vec<(usize, Event)> = Vec::new();
for (line_no, ev) in events {
if let Event::Ingest(ref ing) = ev {
- if let Some(reason) = ingest_parse_error(&ing.raw) {
+ if ing.id == needle {
+ found = Some((line_no, ing.clone()));
+ break;
+ }
+ }
+ prior.push((line_no, ev));
+ }
+
+ let (line_no, ing) = found.ok_or_else(|| CompileIngestError::NotFound(needle.to_string()))?;
+ let base = replay_events(&prior);
+ compile_document_inner(&base, &ing.room_id, &ing.raw, Some(ing.id.clone()), Some(line_no))
+ .map_err(CompileIngestError::Compile)
+}
+
+/// Scan an events.jsonl for corrupt JSON lines and ingests whose DSL fails to parse.
+///
+/// This does not replay the log (which would run rank centrality on every ingest and
+/// can take minutes on real logs). It matches what the server skips on boot: parse failure.
+pub fn scan_jsonl(path: &Path) -> Result<ScanResult, std::io::Error> {
+ let (total_lines, events, bad_json_lines) = load_events_from_jsonl(path)?;
+
+ let mut malformed_ingests = Vec::new();
+ let mut ingest_events = 0usize;
+
+ for (line_no, ev) in &events {
+ if let Event::Ingest(ing) = ev {
+ ingest_events += 1;
+ if let Some(parse_error) = ingest_parse_error(&ing.raw) {
malformed_ingests.push(MalformedIngest {
- line: line_no,
+ line: *line_no,
id: ing.id.clone(),
room_id: ing.room_id.clone(),
thread_tag: ing.thread_tag.clone(),
- reason,
+ parse_error,
});
}
- let before = state.ingests_by_id.len();
- state.apply_event(ev);
- if state.ingests_by_id.len() == before {
- skipped_ingests += 1;
- }
- } else {
- state.apply_event(ev);
}
}
- let ok = bad_json_lines.is_empty() && malformed_ingests.is_empty() && skipped_ingests == 0;
+ let ok = bad_json_lines.is_empty() && malformed_ingests.is_empty();
Ok(ScanResult {
ok,
path: path.display().to_string(),
total_lines,
- parsed_events,
+ parsed_events: events.len(),
+ ingest_events,
bad_json_lines,
malformed_ingests,
- skipped_ingests,
})
}
@@ -330,4 +407,25 @@ mod tests {
assert!(!report.ok);
assert_eq!(report.bad_json_lines.len(), 1);
}
+
+ #[test]
+ fn scan_reports_dsl_parse_error_detail() {
+ let dir = tempfile::tempdir().unwrap();
+ let path = dir.path().join("events.jsonl");
+ let ingest = serde_json::json!({
+ "type": "ingest",
+ "ts": 1,
+ "id": "bad-ingest-id",
+ "raw": "{ no closing brace\n~/a { body }\n~/a 1:0 ~/b",
+ "principal": "test",
+ "room_id": "public",
+ "thread_tag": "t",
+ });
+ std::fs::write(&path, format!("{ingest}\n")).unwrap();
+ let report = scan_jsonl(&path).unwrap();
+ assert!(!report.ok);
+ assert_eq!(report.malformed_ingests.len(), 1);
+ assert_eq!(report.malformed_ingests[0].id, "bad-ingest-id");
+ assert!(report.malformed_ingests[0].parse_error.contains("parse error"));
+ }
}
diff --git a/sorterc/readme.md b/sorterc/readme.md
index 1ebcc3fc935541ea9e47e0458ec67a750fe19fff..e388615c34b40914ca51fc7a79cb738eebc2909b 100644
--- a/sorterc/readme.md
+++ b/sorterc/readme.md
@@ -60,21 +60,33 @@ Rankings use the same structure as the server's dry-run check: parent scope, con
### `scan` — lint an `events.jsonl`
-Reads a JSONL event log and reports problems without starting a server.
+Fast single-pass check. Does **not** replay the log (replay runs rank centrality on every ingest and gets slow fast).
```bash
cargo run -p sorterc -- scan events.jsonl
-cargo run -p sorterc -- scan events.jsonl --pretty
+cargo run -p sorterc -- scan events.jsonl --json
+cargo run -p sorterc -- scan events.jsonl --json --pretty
```
+Default output is human-readable with a blank line between each problem. Use `--json` for machine output.
+
Reports:
- **bad JSON lines** — lines that are not valid JSON
-- **malformed ingests** — ingest events whose `raw` DSL fails to parse
-- **skipped ingests** — ingests dropped during replay (same behavior as server boot)
+- **malformed ingests** — ingest events whose `raw` DSL fails to parse, with full `parse_error` text
Exits 0 when clean, 1 when any issue is found.
+### `compile --ingest` — compile one event from a log
+
+Replay all events **before** the target ingest as base state, then compile that ingest's DSL:
+
+```bash
+cargo run -p sorterc -- compile --ingest cabd8adc-57ae-402d-a940-8e24339ac451 --from events.jsonl --pretty
+```
+
+Output includes `ingest_id`, `ingest_line`, and rankings for that post only. This may take a while for ingests late in a large log (full replay up to that point).
+
## Typical uses
- Iterate on `.sorter` files in an editor and pipe through `compile` to see rankings instantly
diff --git a/sorterc/src/main.rs b/sorterc/src/main.rs
index 71382c180085cb0ad71043c852f8db5d3a48a284..5687c850d16973d28749380b8dc89f3bcebbfc56 100644
--- a/sorterc/src/main.rs
+++ b/sorterc/src/main.rs
@@ -22,9 +22,15 @@ struct Cli {
enum Command {
/// Parse and simulate a .sorter document; emit ranking JSON to stdout.
Compile {
- /// `.sorter` file, or `-` f
… preview truncated; 6,030 characters omittedHardlinks — judgments / attempts / prompt
judgments
attempts
Prompt text is loaded only by the download route.