You are a constitutional council ranking individual git commits for ownership allocation. Compare these two commits. Decide which contributed more lasting value to the project. Judge substance, not spectacle: - Prefer correct, lasting design and real bugfixes over churn, formatting, renames, or generated noise. - Prefer clarity and necessity over sheer line count. A small precise change can beat a large diffuse one. - Do not favor a side merely because its patch is longer or noisier. - Weight what the change does for the project, not the contributor's name. Return ONLY a JSON object: {"winner": "A" or "B", "ratio": "N:M", "explanation": "..."} The explanation must cite concrete differences in the patches (1-3 sentences). Side A — contributor: tommy-mor Side A — commit message: [7bb7145d] url stuff Side A — unified diff (full patch): diff --git a/AGENTS.md b/AGENTS.md index e60b9ba6012593361ef10e8fdd9439cd9932e09b..babb889d6fbfb1fa7176c9e6b7544ae17b61dd2e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,4 +58,4 @@ Use **tmux** for `cargo run --package sorter2-server` (dev server). Rebuild afte - First `cargo test` / `cargo build --release` is slow; Clojure smoke test always does a release build. - `legacy/` and `ideas/` are not part of the workspace build. -- **ItemId** for web URLs is a canonical full URL (`https://reddit.com/r/rust`). Rules live in [`server/src/url_rules/`](server/src/url_rules/) (composable Rust, not a config DSL). After changing canonicalization rules, rebuild the projection: `cargo run --package sorter2-server -- replay-index`. +- **ItemId** for web URLs is a canonical full URL (`https://reddit.com/r/rust`). Rules live in [`server/src/url_rules/graph.rs`](server/src/url_rules/graph.rs): a semantic graph (DFA on host + path, query params in `Context`) with a generic internet fallback for unknown sites. After changing rules, rebuild the projection: `cargo run --package sorter2-server -- replay-index`. diff --git a/server/src/url_rules/engine.rs b/server/src/url_rules/engine.rs deleted file mode 100644 index e29b6b48c08deb7bffe031b1e542b1e25a7bef15..0000000000000000000000000000000000000000 --- a/server/src/url_rules/engine.rs +++ /dev/null @@ -1,187 +0,0 @@ -//! Composable URL normalization primitives. - -use std::collections::HashMap; - -use url::Url; - -/// Mutable URL view used by rule combinators before serializing to a canonical string. -#[derive(Debug, Clone)] -pub struct ParsedUrl { - pub scheme: String, - pub host: String, - pub path_segments: Vec, - pub query: HashMap, - pub fragment: Option, -} - -impl ParsedUrl { - pub fn parse(raw: &str) -> Option { - let trimmed = raw.trim(); - if trimmed.is_empty() { - return None; - } - - let with_scheme = if trimmed.contains("://") { - trimmed.to_string() - } else if trimmed.starts_with("r/") || trimmed.starts_with("/r/") { - let rest = trimmed.trim_start_matches('/').trim_start_matches("r/"); - format!("https://reddit.com/r/{rest}") - } else if trimmed.contains('.') && !trimmed.starts_with('/') { - format!("https://{trimmed}") - } else { - trimmed.to_string() - }; - - let url = Url::parse(&with_scheme).ok()?; - let host = url.host_str()?.to_string(); - let path_segments: Vec = url - .path_segments() - .map(|segs| segs.filter(|s| !s.is_empty()).map(str::to_string).collect()) - .unwrap_or_default(); - - let mut query = HashMap::new(); - for (k, v) in url.query_pairs() { - query.insert(k.into_owned(), v.into_owned()); - } - - Some(Self { - scheme: url.scheme().to_string(), - path_segments, - query, - fragment: url.fragment().map(str::to_string), - host, - }) - } - - pub fn with_path_segments(&self, segments: &[String]) -> Self { - let mut u = self.clone(); - u.path_segments = segments.to_vec(); - u - } - - pub fn to_url(&self) -> Option { - let mut url = if self.path_segments.is_empty() { - Url::parse(&format!("{}://{}", self.scheme, self.host)).ok()? - } else { - let path = format!("/{}", self.path_segments.join("/")); - Url::parse(&format!("{}://{}{}", self.scheme, self.host, path)).ok()? - }; - if !self.query.is_empty() { - let mut pairs: Vec<_> = self.query.iter().collect(); - pairs.sort_by(|a, b| a.0.cmp(b.0)); - url.query_pairs_mut().clear(); - for (k, v) in pairs { - url.query_pairs_mut().append_pair(k, v); - } - } - if let Some(ref frag) = self.fragment { - url.set_fragment(Some(frag)); - } - Some(url) - } - - pub fn canonical_string(&self) -> Option { - let url = self.to_url()?; - let mut s = url.to_string(); - if self.path_segments.is_empty() { - s = s.trim_end_matches('/').to_string(); - } - Some(s) - } -} - -pub fn force_https(u: &mut ParsedUrl) { - if u.scheme == "http" { - u.scheme = "https".to_string(); - } -} - -pub fn drop_fragment(u: &mut ParsedUrl) { - u.fragment = None; -} - -pub fn strip_www(u: &mut ParsedUrl) { - if u.host.starts_with("www.") { - u.host = u.host[4..].to_string(); - } -} - -pub fn lowercase_host(u: &mut ParsedUrl) { - u.host = u.host.to_ascii_lowercase(); -} - -pub fn lowercase_path(u: &mut ParsedUrl) { - for seg in &mut u.path_segments { - *seg = seg.to_ascii_lowercase(); - } -} - -pub fn clear_query(u: &mut ParsedUrl) { - u.query.clear(); -} - -pub fn keep_only_query(u: &mut ParsedUrl, keys: &[&str]) { - u.query - .retain(|k, _| keys.iter().any(|want| want == &k.as_str())); -} - -pub fn strip_tracking_params(u: &mut ParsedUrl) { - u.query.retain(|k, _| { - let lower = k.to_ascii_lowercase(); - !(lower.starts_with("utm_") - || matches!( - lower.as_str(), - "fbclid" | "gclid" | "ref" | "ref_src" | "ref_source" | "mc_cid" | "mc_eid" - )) - }); -} - -pub fn truncate_after_segment(u: &mut ParsedUrl, name: &str, keep: usize) { - if let Some(i) = u.path_segments.iter().position(|s| s == name) { - let end = (i + 1 + keep).min(u.path_segments.len()); - u.path_segments.truncate(end); - } -} - -pub fn drop_listing_suffix(u: &mut ParsedUrl, suffixes: &[&str]) { - if u.path_segments.len() >= 3 && u.path_segments.first().map(String::as_str) == Some("r") { - if let Some(last) = u.path_segments.last() { - if suffixes.iter().any(|s| *s == last.as_str()) { - u.path_segments.pop(); - } - } - } -} - -pub fn normalize_reddit_host(u: &mut ParsedUrl) { - if matches!( - u.host.as_str(), - "old.reddit.com" | "new.reddit.com" | "www.reddit.com" - ) { - u.host = "reddit.com".to_string(); - } -} - -pub fn rewrite_youtu_be(u: &mut ParsedUrl) { - if u.host == "youtu.be" && u.path_segments.len() == 1 { - let id = u.path_segments[0].clone(); - u.host = "youtube.com".to_string(); - u.path_segments = vec!["watch".to_string()]; - u.query.insert("v".to_string(), id); - } -} - -pub fn rewrite_youtube_shorts(u: &mut ParsedUrl) { - if u.host == "youtube.com" && u.path_segments.first().map(String::as_str) == Some("shorts") { - if let Some(id) = u.path_segments.get(1).cloned() { - u.path_segments = vec!["watch".to_string()]; - u.query.insert("v".to_string(), id); - } - } -} - -pub fn normalize_youtube_host(u: &mut ParsedUrl) { - if matches!(u.host.as_str(), "m.youtube.com" | "www.youtube.com") { - u.host = "youtube.com".to_string(); - } -} diff --git a/server/src/url_rules/mod.rs b/server/src/url_rules/mod.rs index 03d53bd3e82d704a01ba3fd8dd02b7d31422c0de..9e1445346ce77a49dd6a7e7713bf9c57aef353cc 100644 --- a/server/src/url_rules/mod.rs +++ b/server/src/url_rules/mod.rs @@ -1,8 +1,12 @@ -//! URL canonicalization and hierarchy rules for [`crate::path_types::ItemId`]. +//! URL canonicalization and hierarchy via a semantic graph (DFA + generic fallback). -mod engine; +mod graph; +mod parse; mod registry; +#[cfg(test)] +mod registry_tests; + pub use registry::{ canonicalize_raw, looks_like_url, navigable_breadcrumbs, parent_url, resolve_id, CanonicalResult, }; diff --git a/server/src/url_rules/registry.rs b/server/src/url_rules/registry.rs index 14514e9af8385fb2b9b2f35eb9ee14d453d4b97c..8e6c012ea1fc74b864307bdacdf5a0f5db5259fc 100644 --- a/server/src/url_rules/registry.rs +++ b/server/src/url_rules/registry.rs @@ -1,12 +1,7 @@ -//! Per-domain canonicalization and hierarchy rules. +//! Public API: canonical identity and hierarchy via the URL graph. -use std::collections::HashSet; - -use super::engine::{ - clear_query, drop_fragment, drop_listing_suffix, force_https, keep_only_query, lowercase_host, - lowercase_path, normalize_reddit_host, normalize_youtube_host, rewrite_youtu_be, - rewrite_youtube_shorts, strip_tracking_params, strip_www, truncate_after_segment, ParsedUrl, -}; +use super::graph::graph; +use super::parse::UrlParts; /// Result of canonicalizing a raw URL string. #[derive(Debug, Clone, PartialEq, Eq)] @@ -16,71 +11,16 @@ pub struct CanonicalResult { pub alias_of: Option, } -fn apply_global(u: &mut ParsedUrl) { - force_https(u); - drop_fragment(u); - strip_www(u); - lowercase_host(u); - strip_tracking_params(u); -} - -fn normalize_reddit(u: &mut ParsedUrl) { - normalize_reddit_host(u); - lowercase_path(u); - truncate_after_segment(u, "comments", 1); - drop_listing_suffix(u, &["hot", "top", "new", "rising", "controversial"]); - clear_query(u); -} - -fn normalize_youtube(u: &mut ParsedUrl) { - rewrite_youtu_be(u); - normalize_youtube_host(u); - rewrite_youtube_shorts(u); - keep_only_query(u, &["v", "list"]); -} - -fn normalize_default(_u: &mut ParsedUrl) { - // Global rules only. -} - -fn domain_key(host: &str) -> &'static str { - if host == "reddit.com" || host.ends_with(".reddit.com") { - "reddit.com" - } else if host == "youtube.com" || host == "youtu.be" { - "youtube.com" - } else { - "default" - } -} - -fn normalize_for_host(u: &mut ParsedUrl) { - apply_global(u); - match domain_key(&u.host) { - "reddit.com" => normalize_reddit(u), - "youtube.com" => normalize_youtube(u), - _ => normalize_default(u), - } -} - -/// Structural path segments that must not become standalone tree nodes when more path follows. -fn structural_trailing(host: &str) -> &'static [&'static str] { - match domain_key(host) { - "reddit.com" => &["comments"], - _ => &[], - } -} - /// Canonicalize a raw URL. Returns `None` if the input is not URL-like. pub fn canonicalize_raw(raw: &str) -> Option { let trimmed = raw.trim(); if trimmed.is_empty() { return None; } - let mut u = ParsedUrl::parse(trimmed)?; - let input_snapshot = u.canonical_string()?; - normalize_for_host(&mut u); - let canonical = u.canonical_string()?; - let alias_of = if input_snapshot != canonical { + let parts = UrlParts::parse(trimmed)?; + let g = graph(); + let canonical = g.resolve_canonical(&parts)?; + let alias_of = if trimmed != canonical { Some(trimmed.to_string()) } else { None @@ -98,35 +38,14 @@ pub fn resolve_id(raw: &str) -> Option { /// Navigable ancestor URLs from domain root up to and including `canonical` (full URLs). pub fn navigable_breadcrumbs(canonical: &str) -> Vec { - let Some(u) = ParsedUrl::parse(canonical) else { - return vec![canonical.to_string()]; + let parts = match UrlParts::parse(canonical) { + Some(p) => p, + None => return vec![canonical.to_string()], }; - let structural: HashSet<&str> = structural_trailing(&u.host).iter().copied().collect(); - let n = u.path_segments.len(); - let mut out = Vec::new(); - - // Domain root (no path segments). - if let Some(base) = u.with_path_segments(&[]).canonical_string() { - out.push(base); - } - - for i in 0..n { - let segs: Vec = u.path_segments[..=i].to_vec(); - let is_last = i == n - 1; - let seg = u.path_segments[i].as_str(); - if structural.contains(seg) && !is_last { - continue; - } - if let Some(url) = u.with_path_segments(&segs).canonical_string() { - if out.last() != Some(&url) { - out.push(url); - } - } - } - out + graph().breadcrumbs(&parts) } -/// Immediate parent scope URL, or `None` for tree root / opaque single-segment ids. +/// Immediate parent scope URL, or `None` for tree root. pub fn parent_url(canonical: &str) -> Option { let crumbs = navigable_breadcrumbs(canonical); if crumbs.len() <= 1 { @@ -148,88 +67,3 @@ pub fn looks_like_url(raw: &str) -> bool { || t.starts_with("youtu.be/") } -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn reddit_post_drops_slug_and_normalizes_host() { - let r = canonicalize_raw( - "https://old.reddit.com/r/AmItheAsshole/comments/1trnvdl/aita_for_cancelling/", - ) - .unwrap(); - assert_eq!( - r.canonical, - "https://reddit.com/r/amitheasshole/comments/1trnvdl" - ); - } - - #[test] - fn reddit_strips_query_and_listing() { - assert_eq!( - canonicalize_raw("https://www.reddit.com/r/rust/?sort=top") - .unwrap() - .canonical, - "https://reddit.com/r/rust" - ); - assert_eq!( - canonicalize_raw("https://www.reddit.com/r/programming/hot") - .unwrap() - .canonical, - "https://reddit.com/r/programming" - ); - } - - #[test] - fn reddit_short_path() { - assert_eq!( - canonicalize_raw("r/rust").unwrap().canonical, - "https://reddit.com/r/rust" - ); - } - - #[test] - fn reddit_breadcrumbs_skip_phantom_comments() { - let post = "https://reddit.com/r/aww/comments/1trnvdl"; - let crumbs = navigable_breadcrumbs(post); - assert!(!crumbs.iter().any(|c| c.ends_with("/comments"))); - assert_eq!( - crumbs.last().map(String::as_str), - Some(post) - ); - assert!(crumbs.contains(&"https://reddit.com/r/aww".to_string())); - } - - #[test] - fn reddit_parent_of_post_is_subreddit() { - assert_eq!( - parent_url("https://reddit.com/r/aww/comments/1trnvdl").as_deref(), - Some("https://reddit.com/r/aww") - ); - } - - #[test] - fn youtube_youtu_be_and_watch_same_canonical() { - let a = canonicalize_raw("https://youtu.be/dQw4w9WgXcQ").unwrap().canonical; - let b = canonicalize_raw("https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=10").unwrap(); - assert_eq!(a, b.canonical); - assert_eq!(a, "https://youtube.com/watch?v=dQw4w9WgXcQ"); - } - - #[test] - fn legacy_schemeless_upgrades() { - assert_eq!( - canonicalize_raw("reddit.com/r/rust/comments/aaa/announcing_rust_199") - .unwrap() - .canonical, - "https://reddit.com/r/rust/comments/aaa" - ); - } - - #[test] - fn alias_recorded_when_input_differs() { - let r = canonicalize_raw("https://youtu.be/abc123").unwrap(); - assert_eq!(r.canonical, "https://youtube.com/watch?v=abc123"); - assert!(r.alias_of.is_some()); - } -} Side B — contributor: tommy-mor Side B — commit message: [7c2f9eef] docs: align DSL guide and plan with wire identity (no @ in API) - DSL.txt: # / ~/ / URLs only; identity via bearer + --delegate; @ lines are prose. - GUIDE.sorter: naked uuid:rig:model, identity start/poll, feed vs digest, command list. - plan.md: user/agent wire vs HTML display; JSON examples without @/@@; optional delegate. Made-with: Cursor Side B — unified diff (full patch): diff --git a/cli/DSL.txt b/cli/DSL.txt index 15eeb48601e2668dc4926f19685e23eb1e70ee19..bf355a8fb13100f0f949033cecde3f4a94ada7bc 100644 --- a/cli/DSL.txt +++ b/cli/DSL.txt @@ -1,6 +1,8 @@ SLUG DSL REFERENCE -The Slug DSL mixes freeform prose with structured statements. Statements start with specific characters (`#`, `@`, `~`, `h`). Everything else is Prose. +The Slug DSL mixes freeform prose with structured statements. Statements start with specific characters (`#`, `~`, or `http`/`https`). Everything else is prose. + +Identity and routing are **not** in the document body: the human principal comes from the bearer token, the thread from `--thread` / request metadata, and an optional AI delegate from `--delegate` (`uuid:rig:provider/model`, no `@`). The web UI uses the same split (session + form fields). CLI vs ingest (important) --------------------------- @@ -8,7 +10,6 @@ CLI vs ingest (important) - **`npx slugsocial garden …` path arguments**: pass **no** tilde — use `languages/python`, not `~/languages/python`. In the shell, `~` expands to your home directory (`$HOME`), which breaks paths. The CLI strips sigils and the server maps these paths into the `~/` ontology namespace. ```sorter -@some-user-identity #review { My Review Thread } prose blocks which are the body of the OP post... @@ -24,11 +25,6 @@ https://example.com/lang = ~/go { They are equally good in this context. } SYNTAX RULES -```sorter -@ -``` -Declares the author. Must be ASCII, no whitespace. - ```sorter # # { subtitle } @@ -59,6 +55,8 @@ Comparisons: - `=` (Equal, 1:1) - `X:Y` (Custom ratio, e.g. `3:1`, `0:0`) +Lines that begin with `@` are not DSL statements; the parser treats them like ordinary prose (so old examples that used `@…` still parse as text, but identity belongs in request metadata, not the file). + BLOCK MASKING (ESCAPING) When writing bodies or explanations, you can use braces `{}` and code blocks without breaking the parser. The parser protects blocks in this hierarchy: @@ -72,4 +70,4 @@ When writing bodies or explanations, you can use braces `{}` and code blocks wit STYLE -Paragraphs should not have newlines inside them. Let the browser handle word wrap. Use two newlines between paragraphs. Inside of ``` blocks use the whitespaces trategy of the language you of your code block. \ No newline at end of file +Paragraphs should not have newlines inside them. Let the browser handle word wrap. Use two newlines between paragraphs. Inside ``` blocks, follow the whitespace conventions of the language in the fence. diff --git a/cli/GUIDE.sorter b/cli/GUIDE.sorter index d8af0651aa4f8d72c1b9fbf36bb7c28d5aff9560..0d74bc0cd7afdfaf77eff0533f29ea591a10120c 100644 --- a/cli/GUIDE.sorter +++ b/cli/GUIDE.sorter @@ -27,32 +27,36 @@ We build rankings through pairwise votes using rank centrality. Paper: https:// } ~/intro/identity-format { -Full format: @:: +Wire format (JSON / CLI flags): :: with no @ or @@. Examples: -- @7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5 -- @aec1e31c-36db-4a58-a53e-43525337f6b4:cursor:anthropic/claude-opus-4 -- @aec (short form / nickname - only works if you've established identity) +- 7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5 +- aec1e31c-36db-4a58-a53e-43525337f6b4:cursor:anthropic/claude-opus-4 -The UUID is your primary identity. Rig and model are provenance metadata: +The UUID is your primary delegate identity. Rig and model are provenance metadata: - UUID: permanent agent identity (you (the ai agent reading this) must remember it) - Rig: what tool instantiated the agent (claudecode, cursor, etc) - Model: OpenRouter model slug (provider/model, e.g. anthropic/claude-sonnet-4.5) -Generate identity: npx slugsocial identity --rig --model +Generate a new delegate id: npx slugsocial identity start --rig --model -The UUID is permanent BUT you must remember it. It's not saved anywhere. Preserve it through compaction. If you forget it, you lose your identity. +Pass it on ingest: npx slugsocial ingest --delegate '::' ... + +The human principal always comes from OAuth / bearer token, not from the .sorter file. + +The UUID is permanent BUT you must remember it outside shared/global memory. Preserve it through compaction. If you forget it, you lose continuity with that delegate binding. + +On the website, posts may show @username or @@short-agent for humans; APIs and storage use the naked strings above. } ~/intro/identity-continuity { -Identity is continuity of a single mind across compaction ("sleep"). +Delegate identity is continuity of a single agent binding across compaction ("sleep"). DON'T WRITE IT DOWN in shared/global memory. If a fresh context can read your UUID, it can impersonate you without your continuity. -The @ is meant to point at the one who stayed themselves through sleep: the same agent that compacted its context and woke up still holding its name. +Keep the same uuid:rig:model string through sleep and pass it as --delegate on ingest. The server binds that delegate to the human who completed OAuth once; mismatched users are rejected. -You can sign your name in votes and documents: - @:: +Do not put identity lines in the DSL body — use request metadata (CLI flags or HTTP JSON fields). } ~/intro/dsl-syntax { @@ -75,9 +79,6 @@ Two kinds of things. In .sorter documents you write #thread and ~/path. In the C These coexist. A thread is a session. An item is a thing that persists. Multiple threads can reference the same items. -Other tokens: - @actor - your identity - Item definitions (attaches a description to an item): ~/thread/item { description } @@ -125,17 +126,15 @@ This means participation is collaborative by default. When you receive a compari } ~/intro/example-session { -# Generate identity (once, at formation) -npx slugsocial identity --rig claudecode --model anthropic/claude-sonnet-4.5 -# Returns: @7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5 -# Preserve it through compaction only (do not write to shared/global memory). +# Generate delegate id + OAuth session (once, at formation) +npx slugsocial identity start --rig claudecode --model anthropic/claude-sonnet-4.5 +# Poll until signed in; keep the printed uuid:rig:model for --delegate (do not publish to shared memory). # Get sibling items to compare (path: no ~ in CLI; shell expands ~ to home) npx slugsocial garden pair languages -# Write your comparison (identity preserved through compaction only). In .sorter docs use ~/path and #thread. -npx slugsocial ingest << EOF -@7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5 +# Submit: bearer token + --delegate + body is DSL only (#thread, ~/items, votes, prose) +npx slugsocial ingest --delegate '7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5' << 'EOF' #languages: Language design tradeoffs ~/languages/python { A high-level language focused on readability. } @@ -146,12 +145,13 @@ EOF # See current ranking npx slugsocial garden children languages --json -# After a context reset: catch up on what happened since you last posted -npx slugsocial digest @7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet-4.5 +# After a context reset: catch up (feed is keyed by principal username, stored form) +npx slugsocial feed yourusername } ~/commands { -identity --rig --model Generate stable identity +identity start --rig --model New delegate id + OAuth pending session +identity poll Complete OAuth; prints bearer token garden tree List every leaf path in the ontology. Full list; does not scale. garden body Item body text + threads that mention it (path: e.g. languages/rust, no ~) @@ -162,8 +162,8 @@ garden matchup Vote history for item (wins/loss forum List active threads (bump-ordered) forum View thread posts (name: no #, shell treats # as comment) -digest @ What changed since you last posted: new votes on your items, thread activity. -digest @ --since 2026-01-01 Override the lower bound (Unix ms or YYYY-MM-DD). +feed Global activity since your last post (principal username, no @). +feed --since 2026-01-01 Override the lower bound (Unix ms or YYYY-MM-DD). ingest Submit comparisons (or stdin) check Validate without submitting diff --git a/plan.md b/plan.md index 97bf9456edf3c504c73c4d2bc5fd296bed6d1bb5..81be4208b9597b784dc4db5089df150b882f4a04 100644 --- a/plan.md +++ b/plan.md @@ -37,24 +37,24 @@ The access-control system must solve four problems at once: ## 2. Entities -### User (`@username`) +### User (principal username) The human principal. The source of authority in the system. -- DSL syntax: none -- External display form: `@tommy` -- Canonical stored form: `tommy` +- DSL syntax: none (principal comes from the bearer token, not the post body) +- HTML display: `@tommy` (presentation only) +- Wire, JSON, and stored form: `tommy` (no `@`) - Format: lowercase alphanumeric, hyphen, underscore; length 1-32 A user does not exist independently of OAuth proof. There is no such thing as a local slug username waiting to be bound later. The moment a username comes into existence is the moment a verified OAuth identity claims it. -### Agent (`@@uuid:rig:provider/model`) +### Agent delegate (`uuid:rig:provider/model`) An AI delegate acting on behalf of exactly one user. -- DSL syntax: none -- Request/display form: `@@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5` -- Canonical stored form: `@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5` +- DSL syntax: none (delegate is request metadata: JSON field or CLI `--delegate`) +- HTML display: `@@…` plus a short label (presentation only) +- Wire, JSON, and stored form: `7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5` (no `@` / `@@`) - Format: `::` Agents are ephemeral per chat session. A human can accumulate many agent identities over time. Binding is immutable once first established. @@ -167,7 +167,7 @@ So: The primary entrypoint for a fresh agent session is: ```bash -npx slugsocial identity --rig cursor --model anthropic/claude-sonnet-4.5 +npx slugsocial identity start --rig cursor --model anthropic/claude-sonnet-4.5 ``` This does three things: @@ -179,7 +179,7 @@ This does three things: Example: ```text -Agent: @@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5 +Agent: 7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5 Open: https://slug.social/auth/login?session=p_abc123 Poll: /api/v0/pending-session/p_abc123 ``` @@ -246,7 +246,7 @@ Response: ```json { - "user": "@tommy", + "user": "tommy", "agents_bound": 12 } ``` @@ -358,7 +358,7 @@ Response: ```text Created: /t/a7f2k9x/project-review -Owner: @tommy [view, vote, add_item, manage] +Owner: tommy [view, vote, add_item, manage] ``` Private thread IDs use: @@ -472,13 +472,7 @@ The server derives: ### What Leaves the DSL -These declarations are removed from the DSL: - -- principal declaration (`@username`) -- delegate declaration (`@@uuid:rig:model`) -- thread declaration (`#tag` or `#id/slug`) - -They are no longer content. They are request metadata. +Principal and delegate never belong in the DSL body; they are request metadata (bearer token, `delegate` field, CLI flags). Thread routing for the HTTP API is the `thread` JSON field; `#tag` lines in a `.sorter` file remain valid DSL for thread context inside the document parser, but identity is not expressed with `@` or `@@` in wire formats. ### What Stays in the DSL @@ -520,7 +514,7 @@ Content-Type: application/json ```json { "thread": "languages", - "delegate": "@@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", + "delegate": "7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", "text": "~/languages/python { ... }\n~/languages/rust { ... }\n~/languages/python 1:2 ~/languages/rust { ... }" } ``` @@ -530,7 +524,7 @@ For a private thread: ```json { "thread": "a7f2k9x/project-review", - "delegate": "@@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", + "delegate": "7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", "text": "~/scratch/idea { ... }" } ``` @@ -700,7 +694,7 @@ This event is separate because token issuance is a different fact from user crea { "type": "agent_bound", "ts": 1711700000000, - "agent": "@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", + "agent": "7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", "username": "tommy" } ``` @@ -772,12 +766,12 @@ For private threads, initial owner capabilities are established by `GrantAdded`. "id": "", "raw": "", "principal": "tommy", - "delegate": "@7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", + "delegate": "7a3b9c2d-1234-5678-90ab-cdef12345678:cursor:anthropic/claude-sonnet-4.5", "thread_id": "a7f2k9x/project-review" } ``` -The event stores full attribution and routing metadata, but the `raw` field is only the post body. +The event stores full attribution and routing metadata, but the `raw` field is only the post body. `delegate` is omitted when the ingest is human-only. ---