Side B fixes a real performance problem (scan no longer does a full state replay with rank centrality on every ingest), adds a genuinely new debugging capability (`compile --ingest` to replay-and-compile a single event), and includes new test coverage validating parse-error surfacing. Side A is a solid but more cosmetic feature (fullscreen layout, sorted edge-history list, preview morph) accompanied by large repetitive CSS duplication across three theme files, offering less durable engineering value per line changed.
constitution · epochs · watch · epoch 3
comparison
c_477013996fa5 (tommy-mor) vs c_6209cd238b3f (tommy-mor)
download prompt · raw event · cmp_895e7346fc679c
council reasoning
B redesigns `scan_jsonl` to a fast parse-only pass (dropping full reducer replay/rank work that made real logs slow), surfaces full DSL `parse_error` detail, and adds `compile --ingest` plus human-readable scan output—lasting tooling. A is solid product work (chromeless fullscreen layout, left-oriented edge history sort/ratios, post morph preview) but is narrower UX polish on one flow versus B’s reusable offline diagnostics.
Side B adds substantial tooling improvements with lasting developer value: it introduces `compile --ingest` to replay and compile a single ingest from an event log, refactors replay logic, makes `scan` dramatically faster by using a parse-only pass instead of full replay, and surfaces detailed `parse_error` information with updated CLI output and tests. Side A improves the vote-compare UI with a fullscreen layout, preview morphing, reordered vote history, and related CSS/tests, but these are primarily presentation and workflow enhancements rather than foundational tooling and diagnostics.
sides
A — c_477013996fa5 (tommy-mor)
message
[893a2007] fullscreen?
diff preview
diff --git a/agents.md b/agents.md
index d9a924d2f77c444d9b112bbf37a480b963ace4f0..1f66ddbeddd1e40310947c7eb474c1ac4858bc42 100644
--- a/agents.md
+++ b/agents.md
@@ -37,9 +37,9 @@ Strict **CSP** that blocks `eval` would break the current app. Other projects ma
- **Non-morph `POST /ui` responses:** **`SetGardenPin`** returns **`303 See Other`** and **`Set-Cookie`** (same as **`POST /theme`**). Garden pin/unpin is a normal **`<form method="POST" action="/ui" data-navigate="full">`** — browser navigation applies cookies reliably (see **`test/browser_garden_pin.clj`**). Each **`__rpc__`** payload includes **`form_action: "/ui"`**; **`post_ui_html`** rejects mismatches to bind tokens to the UI endpoint.
-- **`VoteComparePost`:** On success returns **`text/javascript`** that **morphs** **`#vote-compare-preview`** (new ingest card) and **`#vote-edge-history-region`** (recomputed edge list). Uses **`RpcResult::PostOk`**’s **`post_id`** / **`post_index`** for the card. **`__rpc__`** carries **`form_action: "/ui"`**; **`thread_tag`** and ratio fields come from the same form as **`$form`** holes.
+- **`VoteComparePost`:** On success returns **`text/javascript`** that **morphs** **`#vote-compare-preview`** (new ingest card), **`#vote-edge-history-region`** (recomputed **`<ul>`** — ratios match **`left`/`right`** query order, bullets, sorted by strength toward **`left`** then newer). The compare **`GET`** page uses **`layout_full_bleed_chromeless`** (no breadcrumbs, no **`#controls`**, no **`slug-pin-hud`**; **`view-vote-compare-fullscreen`** full-width **`body`**). **`__rpc__`** carries **`form_action: "/ui"`**; **`thread_tag`** and ratio fields come from the same form as **`$form`** holes.
-- **Garden pin / compare voting:** Cookie **`slug_garden_pin`** via **`set_garden_pin`**. Pairwise UI: **`GET /vote/compare?…`** / **`GET /r/:room_key/vote/compare?…`**. HUD: **`#slug-pin-hud`** when **`layout`** passes garden metadata on **`body`**; the label is **`POST /ui`** **`set_garden_pin`** **`clear:true`** (**`slug_ui.js`**), not a permalink to the item.
+- **Garden pin / compare voting:** Cookie **`slug_garden_pin`** via **`set_garden_pin`**. Pairwise UI: **`GET /vote/compare?…`** / **`GET /r/:room_key/vote/compare?…`** (fullscreen **`GET`** page: no HUD; other garden pages). HUD (**`#slug-pin-hud`**): only when **`layout`** passes garden metadata on **`body`**; the label is **`POST /ui`** **`set_garden_pin`** **`clear:true`** (**`slug_ui.js`**), not a permalink to the item.
**Rule of thumb:** New **CLI or API** verbs → `RpcCommand`. New **in-page morph or form-driven** behavior that only makes sense in the browser → `HtmlUiAction`. If both need the same operation, implement the real work once (e.g. call shared RPC helpers from `post_ui_html`) and keep the wire shapes separate.
diff --git a/server/src/api/ui_html.rs b/server/src/api/ui_html.rs
index 5aa6a86326ba3545d261322c010e02fe86ee1c57..696e7b3605e2e68aee0351116c494c2958506add 100644
--- a/server/src/api/ui_html.rs
+++ b/server/src/api/ui_html.rs
@@ -254,7 +254,17 @@ async fn dispatch_ui_action(
};
n
};
- let js = vote_compare_post_success_js(state, &nav, &left_id, &right_id).await;
+ let js = vote_compare_post_success_js(
+ state,
+ &nav,
+ &room,
+ &thread_tag,
+ &left_id,
+ &right_id,
+ pid.as_str(),
+ post_index,
+ )
+ .await;
Response::builder()
.status(StatusCode::OK)
.header(header::CONTENT_TYPE, "text/javascript; charset=utf-8")
diff --git a/server/src/html/garden.rs b/server/src/html/garden.rs
index 121d9498e8cb93d4d001dc1bbce23d74fbb958f5..41f9e9c64a80a55a9d3ece2a6a1f592cf5e8d8dd 100644
--- a/server/src/html/garden.rs
+++ b/server/src/html/garden.rs
@@ -22,17 +22,17 @@ use crate::{
},
events::ThreadCapability,
path_types::ItemId,
- reducer::{ContentState, ReducerState, ScopeId},
+ reducer::{scope_from_room_wire, ContentState, ReducerState, ScopeId},
scope_rank::{build_children_rankings, ChildrenRankings},
state::AppState,
timeago,
};
use super::{
- bc_path, bc_path_external, bc_segment, cli_panel, layout, now_ms, ratio_pct,
- render_linkified_with_embeds_in_scope, theme_from_jar, theme_next_from_uri,
+ bc_path, bc_path_external, bc_segment, cli_panel, layout, layout_full_bleed_chromeless, now_ms,
+ ratio_pct, render_linkified_with_embeds_in_scope, theme_from_jar, theme_next_from_uri,
breadcrumb_path::{ExternalOntologyPath, OntologyPath},
- forum::{ThreadNav},
+ forum::{ingest_entry_markup, ThreadNav},
};
/// `GET /vote/compare` — pairs `left` / `right` query params with optional `thread`.
@@ -89,25 +89,62 @@ fn canonical_edge_items(a: &ItemId, b: &ItemId) -> (ItemId, ItemId) {
}
}
-/// Votes whose endpoints are exactly this unordered pair, oldest first.
-fn votes_for_edge(content: &ContentState, a: &ItemId, b: &ItemId) -> Vec<crate::reducer::VoteData> {
+/// All votes whose endpoints are exactly this unordered pair (unsorted).
+fn edge_vote_entries_for_pair(content: &ContentState, a: &ItemId, b: &ItemId) -> Vec<crate::reducer::VoteData> {
let (lo, hi) = canonical_edge_items(a, b);
let lo_s = lo.as_str();
let hi_s = hi.as_str();
- let mut out: Vec<crate::reducer::VoteData> = content
+ content
.item_votes
.get(&lo)
.into_iter()
.flat_map(|q| q.iter())
.filter(|v| {
- let touches = (v.a.as_str() == lo_s && v.b.as_str() == hi_s)
- || (v.a.as_str() == hi_s && v.b.as_str() == lo_s);
- touches
+ (v.a.as_str() == lo_s && v.b.as_str() == hi_s)
+ || (v.a.as_str() == hi_s && v.b.as_str() == lo_s)
})
.cloned()
- .collect();
- out.sort_by_key(|v| v.ts);
- out
+ .collect()
+}
+
+fn ratios_for_compare_page(v: &crate::reducer::VoteData, page_left: &ItemId, page_right: &ItemId) -> (i32, i32) {
+ let pl = page_left.as_str();
+ let pr = page_right.as_str();
+ match (v.a.as_str(), v.b.as_str()) {
+ (a, b) if a == pl && b == pr => (v.ratio_left, v.ratio_right),
+ (a, b) if a == pr && b == pl => (v.ratio_right, v.ratio_left),
+ _ => (v.ratio_left, v.ratio_right),
+ }
+}
+
+fn left_share_normalized(ratio_left: i32, ratio_right: i32) -> f64 {
+ let l = ratio_left.max(0) as f64;
+ let r = ratio_right.max(0) as f64;
+ let sum = l + r;
+ if sum <= 0.0 {
+ 0.5
+ } else {
+ l / sum
+ }
+}
+
+/// Stronger preference for **`page_left` first**; ties **newer first**.
+fn sort_votes_for_compare_display(
+ mut votes: Vec<crate::reducer::VoteData>,
+ page_left: &ItemId,
+ page_right: &ItemId,
+) -> Vec<crate::reducer::VoteData> {
+ votes.sort_by(|va, vb| {
+ let (ratio_left_a, ratio_right_a) = ratios_for_compare_page(va, page_left, page_right);
+ let (ratio_left_b, ratio_right_b) = ratios_for_compare_page(vb, page_left, page_right);
+ let sa = left_share_normalized(ratio_left_a, ratio_right_a);
+ let sb = left_share_normalized(ratio_left_b, ratio_right_b);
+ match sb.partial_cmp(&sa).unwrap_or(std::cmp::Ordering::Equal) {
+ std::cmp::Ordering::Equal => vb.ts.cmp(&va.ts),
+ o => o,
+ }
+ });
+ votes
}
/// Number of vote ingests recorded for this unordered pair in `content` (same scope as ranking).
@@ -144,39 +181,40 @@ fn vote_edge_history_markup(
content: &ContentState,
left: &ItemId,
right: &ItemId,
- nav: &ThreadNav,
) -> maud::Markup {
- let votes = votes_for_edge(content, left, right);
- let (lo, hi) = canonical_edge_items(left, right);
+ let votes = edge_vote_entries_for_pair(content, left, right);
+ let votes = sort_votes_for_compare_display(votes, left, right);
+ let legend_left = item_display_path(left.as_str());
+ let legend_right = item_display_path(right.as_str());
html! {
@if votes.is_empty() {
p class="muted vote-edge-empty" { "no votes on this pair in this scope yet" }
} @else {
- h3 class="vote-edge-history-title" { "votes on this edge" }
- ol class="vote-edge-history" {
+ h3 class="vote-edge-history-title" {
+ "votes on this edge"
+ span class="vote-edge-history-axis muted" { " · " (legend_left) " : " (legend_right) }
+ }
+ ul class="vote-edge-history" {
@for v in &votes {
- @let (ratio_lo, ratio_hi) = if v.a == lo && v.b == hi {
- (v.ratio_left, v.ratio_right)
- } else {
- (v.ratio_right, v.ratio_left)
- };
- @let pct = ratio_pct(ratio_lo, ratio_hi);
- @let left_class = if lo.as_str() == left.as_str() { "ratio-left current" } else { "ratio-left" };
- @let right_class = if hi.as_str() == left.as_str() { "ratio-right current" } else { "ratio-right" };
- li class="vote-edge-history-row" {
+ @let (r_left, r_right) = ratios_for_compare_page(v, left, right);
+ @let pct = ratio_pct(r_left, r_right);
+ @let row_tip = format!(
+ "{}:{} counts toward {} (left of bar) vs {} (right of bar); #{} · @{}",
+ r_left,
+ r_right,
+ legend_left,
+ legend_right,
+ v.thread_tag,
+ v.principal,
+ );
+ li class="vote-edge-history-row" title=(row_tip) {
div class="vote-edge-meta" {
- a href=(nav.garden_item_href(&lo)) {
- code { (item_display_path(lo.as_str())) }
- }
- span class="vote-edge-ratio" { (format!("{}:{}", ratio_lo, ratio_hi)) }
- a href=(nav.garden_item_href(&hi)) {
- code { (item_display_path(hi.as_str())) }
- }
+ span class="vote-edge-ratio" { (format!("{}:{}", r_left, r_right)) }
span class="muted" { " · #" (v.thread_tag) " · @" (v.principal) }
}
- div class="ratio-bar vote-edge-bar" {
- div class=(left_class) style={(format!("width: {:.3}%;", pct))} {}
- div class=(right_class) style={(format!("width: {:.3}%;", 100.0 - pct))} {}
+ div class="ratio-bar vote-edge-bar" aria-hidden="true" {
+ div class="ratio-left" style={(format!("width: {:.3}%;", pct))} {}
+ div class="ratio-right" style={(format!("width: {:.3}%;", 100.0 - pct))} {}
}
@if !v.body.trim().is_empty() {
div class="vote-edge-reason muted" { (v.body.trim()) }
@@ -192,14 +230,33 @@ fn vote_edge_history_markup(
pub(crate) async fn vote_compare_post_success_js(
state: &AppState,
nav: &ThreadNav,
+ room_wire: &str,
+ thread_tag: &str,
left: &ItemId,
right: &ItemId,
+ post_id: &str,
+ post_idx: Option<usize>,
) -> String {
let reduced = state.reduced.read().await;
+ let scope = scope_from_room_wire(room_wire);
+ let Some(ing) = reduced.ingests_by_id.get(post_id).cloned() else {
+ drop(reduced);
+ return "console.warn('vo
… preview truncated; 11,546 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.