Side A merely deletes a speculative, AI-generated design markdown file with no code impact, contributing nothing functional. Side B is a substantive refactor that separates canonical-path normalization from identity parsing, fixes wire-format inconsistencies (stripping '@' from stored identifiers), makes delegate optional, and updates code, tests, and integration scripts consistently across the codebase.
constitution · epochs · watch · epoch 3
comparison
c_30aff8402510 (tommy-mor) vs c_e2ee16c7ada5 (tommy-mor)
download prompt · raw event · cmp_23a63a9044b582
council reasoning
Commit A only deletes an obsolete markdown architecture brainstorm (plan2.md) with no code impact. Commit B delivers a real structural refactor: extracts canonical_path.rs and identity.rs, enforces strict naked wire identities (no @/@@, optional delegate), slims the reducer/events layer so it no longer rewrites identities, and updates CLI, APIs, HTML display, types, and tests accordingly—lasting design clarity and API consistency.
Side B makes a substantial architectural improvement by separating path normalization into `canonical_path.rs` and identity parsing into `identity.rs`, removing identity rewriting from the reducer, enforcing strict stored-form identities without `@` in APIs, and updating ingest/auth flows to support optional delegates with validation. Side A only deletes a planning document (`plan2.md`) containing design notes and example code, without changing project behavior or implementation.
sides
A — c_30aff8402510 (tommy-mor)
message
[7fc70de3] old plan
diff preview
diff --git a/plan2.md b/plan2.md
deleted file mode 100644
index 7d6b9b652f21d3b61d64e088c5a9679845d4fe5e..0000000000000000000000000000000000000000
--- a/plan2.md
+++ /dev/null
@@ -1,190 +0,0 @@
-This is a phenomenal synthesis. You stripped away the exact parts of `evaleval` that don't scale to a multi-tenant web application (string-splicing `eval` and in-memory nonce OCAP tracking) and kept the parts that make development lightning fast (embedded declarative payloads, single endpoint routing, and Javascript AST responses).
-
-You are entirely right about the **AST substitution in Rust**. Walking a `serde_json::Value` tree to find `{"$form": "field_name"}` and swapping the node for a String isn't a hack—in Rust, it’s just a completely standard recursive enum visitor.
-
-Let’s lock in this exact architecture. It is cohesive, secure, and incredibly ergonomic.
-
-Here is what the code actually looks like to execute this vision.
-
----
-
-### 1. The Safe AST Substitution
-
-This is the exact function that runs in the Web handler before giving the payload to the RPC engine. Because it operates on the JSON AST *before* deserialization, it's 100% immune to injection.
-
-```rust
-use serde_json::Value;
-use std::collections::HashMap;
-
-/// Recursively walk the JSON AST and replace {"$form": "key"} with the actual form string.
-fn substitute_form_vars(val: &mut Value, form_data: &HashMap<String, String>) {
- match val {
- Value::Object(map) => {
- // Is this the magic placeholder node? {"$form": "input_name"}
- if map.len() == 1 && map.contains_key("$form") {
- if let Some(field_name) = map.get("$form").and_then(|v| v.as_str()) {
- let submitted_text = form_data.get(field_name).map(|s| s.as_str()).unwrap_or("");
- *val = Value::String(submitted_text.to_string());
- return;
- }
- }
- // Otherwise, keep walking the object
- for v in map.values_mut() {
- substitute_form_vars(v, form_data);
- }
- }
- Value::Array(arr) => {
- // Walk arrays
- for v in arr.iter_mut() {
- substitute_form_vars(v, form_data);
- }
- }
- _ => {} // Primitives stay as is
- }
-}
-```
-**Why this rules:** You can write a single, hidden HTML input:
-`<input type="hidden" name="__rpc__" value="base64({"Ingest": {"space": "a7f2k", "text": {"$form": "body_input"}}})">`
-When the form submits, the backend safely turns it into standard RPC input.
-
----
-
-### 2. The Unified Core RPC Layer
-
-You keep exactly one execution layer that strictly enforces your domain constraints (ACLs). Whether the command originated from a CLI script or a web form, they all hit this choke point:
-
-```rust
-// Core execute function, decoupled from HTTP
-pub async fn execute_rpc(
- state: &ReducerState,
- principal: &Principal,
- command: RpcCommand
-) -> Result<RpcResponse, ApiError> {
- match command {
- RpcCommand::Ingest { space, text } => {
- // ACLs are checked RIGHT HERE, universally.
- if !state.user_has_cap(&space, principal, ThreadCapability::Post) {
- return Err(ApiError::Forbidden("No post access in this space".to_string()));
- }
- // Do the write, apply events...
- Ok(RpcResponse::IngestOk { ... })
- }
- // ...
- }
-}
-```
-
----
-
-### 3. The `DomPatch` Builder Pattern
-
-You prefer the Builder pattern over a macro for the response mapping. I agree—builders are far easier for your IDE to autocomplete, and easier to compose dynamically (e.g., iterating over a list of items to append).
-
-```rust
-pub struct DomPatch {
- js: String,
-}
-
-impl DomPatch {
- pub fn new() -> Self {
- Self { js: String::new() }
- }
-
- /// Morphs an element using Idiomorph
- pub fn morph(mut self, selector: &str, html: &str) -> Self {
- let safe_html = serde_json::to_string(html).expect("string escaping failed");
- self.js.push_str(&format!(
- "Idiomorph.morph(document.querySelector('{}'), {}, {{morphStyle: 'innerHTML'}});\n",
- selector, safe_html
- ));
- self
- }
-
- /// Appends raw HTML to an element
- pub fn append(mut self, selector: &str, html: &str) -> Self {
- let safe_html = serde_json::to_string(html).unwrap();
- self.js.push_str(&format!(
- "document.querySelector('{}')?.insertAdjacentHTML('beforeend', {});\n",
- selector, safe_html
- ));
- self
- }
-
- /// Executes raw javascript
- pub fn eval(mut self, code: &str) -> Self {
- self.js.push_str(code);
- self.js.push('\n');
- self
- }
-
- /// Consumes the builder into an HTTP Response with the right content-type
- pub fn into_response(self) -> impl axum::response::IntoResponse {
- (
- axum::http::StatusCode::OK,
- [(axum::http::header::CONTENT_TYPE, "text/javascript")],
- self.js
- )
- }
-}
-```
-
----
-
-### 4. The Single Web Handler (`POST /ui/action`)
-
-With the pipeline defined, you only ever have to write **one** `POST` handler for the entire Web UI.
-
-```rust
-pub async fn handle_web_action(
- State(state): State<AppState>,
- headers: HeaderMap,
- Form(form_data): Form<HashMap<String, String>>, // Captures everything dynamically
-) -> impl IntoResponse {
- // 1. Authenticate using Bearer / Cookie exactly like the CLI
- let principal = match extract_web_session(&headers, &state) {
- Ok(p) => p,
- Err(_) => return DomPatch::new().eval("window.location = '/auth/login';").into_response(),
- };
-
- // 2. Decode the Base64 JSON
- let b64 = form_data.get("__rpc__").expect("Missing RPC payload in form");
- let decoded = base64::decode(b64).expect("Bad b64");
- let mut json_ast: Value = serde_json::from_slice(&decoded).expect("Bad JSON");
-
- // 3. Do AST Substitution!
- substitute_form_vars(&mut json_ast, &form_data);
-
- // 4. Parse it strongly into the RPC enum
- let command: RpcCommand = serde_json::from_value(json_ast).expect("Invalid RpcCommand");
-
- // 5. Pass it to the core execute function (authz + mutation happens here)
- match execute_rpc(&state.reduced.read().await, &principal, command).await {
- Ok(RpcResponse::IngestOk { new_ranks }) => {
- // Translate the RpcResponse to UI JS snippets
- DomPatch::new()
- .morph("#rank-container", &render_ranking(&new_ranks))
- .eval("document.getElementById('ingest-form').reset();")
- .into_response()
- }
- Ok(_) => DomPatch::new().eval("console.log('Action complete');").into_response(),
- Err(e) => {
- // Reconcile errors
- DomPatch::new()
- .morph("#error-banner", &format!("<div class='error'>{}</div>", e.message()))
- .into_response()
- }
- }
-}
-```
-
-### The Verdict on the Grand Architecture
-
-By combining:
-1. The **Domain-Driven Asymmetry** (Spaces contain Gardens & Threads)
-2. The **Core RPC Logic** (1 executor, `Vec<RpcCommand>`, strict ACL checks)
-3. The **Single Web Form Controller** (b64 embedded, `substitute_form_vars()`)
-4. The **Javascript DomPatch Builder**
-
-You have constructed an application architecture that gives you absolute security and data integrity for your CLI AI Agents, while keeping the absolute peak hackability, form simplicity, and lightning-fast JS UI diffing of your `evaleval` Python framework.
-
-I'm sold. It is clean, it is uniquely fitted to the mechanics of Rust (`serde`, `enums`), and it solves the URL routing fatigue problem beautifully. This is the exact way to build `slug.social` v2.
B — c_e2ee16c7ada5 (tommy-mor)
message
[80ad7753] refactor: split canonical_path and identity; strict wire identity without @ - Add canonical_path.rs (tag + item URL normalization) and identity.rs (parse_username/parse_agent; reject @ in API input). - Slim events.rs to event types only; reducer applies no identity rewriting. - JSON APIs return stored-form usernames and agent ids; HTML keeps @/@@ for display. - Optional delegate on ingest; CLI and tests use naked uuid:rig:model. Made-with: Cursor
diff preview
diff --git a/cli/src/main.rs b/cli/src/main.rs
index 5ac8e289f2b7a366b5959d9338d02f9b546f408a..630c5dea1f78c0ec9bc53e6b96234a0dc75bb705 100644
--- a/cli/src/main.rs
+++ b/cli/src/main.rs
@@ -61,8 +61,8 @@ enum Command {
/// Example: --before 2026-06-01
#[arg(long, value_name = "DATE_OR_MS")]
before: Option<String>,
- /// Filter to posts from this actor (UUID prefix match).
- /// Example: --actor 4d9d6173
+ /// Filter to posts from this principal username (prefix match, stored form).
+ /// Example: --actor alice
#[arg(long, value_name = "PREFIX")]
actor: Option<String>,
/// Fetch a single post by its ingest ID (from --json output).
@@ -75,9 +75,8 @@ enum Command {
///
/// SYNTAX:
///
- /// Actor (required, once per document):
- /// @<uuid>:<rig>:<model>
- /// Example: @7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet
+ /// Identity: human comes from the bearer token; optional AI delegate from `--delegate`
+ /// (`uuid:rig:provider/model`). The document body is DSL only (items, votes, prose) — no `@` lines.
///
/// Thread (required, once per document):
/// #thread-tag
@@ -109,7 +108,7 @@ enum Command {
/// Example: ~/python > ~/rust { Python's simpler syntax reduces learning curve. }
///
/// Prose (optional, anywhere):
- /// Any line that doesn't start with @, #, or ~ is prose.
+ /// Any line that doesn't start with # or ~ (or `http`) is prose.
/// Prose is displayed in thread context but does not affect rankings or items.
/// Use prose to write blog posts, reasoning, or notes within your ingest.
///
@@ -125,8 +124,7 @@ enum Command {
/// EXAMPLES:
///
/// # From heredoc (recommended for agents)
- /// npx slugsocial ingest << 'EOF'
- /// @7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet
+ /// npx slugsocial ingest --delegate '7a3b9c2d-1234-5678-90ab-cdef12345678:claudecode:anthropic/claude-sonnet' << 'EOF'
/// #languages: Python vs Rust for systems programming
///
/// ~/languages/python { A high-level language with simple syntax and rich ecosystem. }
@@ -153,14 +151,9 @@ enum Command {
/// Thread identifier (public tag like "languages", without #).
#[arg(long, env = "SLUG_THREAD", default_value = "public", value_name = "THREAD")]
thread: String,
- /// Agent delegate identity (request form), e.g. @@uuid:rig:provider/model
- #[arg(
- long,
- env = "SLUG_DELEGATE",
- default_value = "@@00000000-0000-0000-0000-000000000000:cli:local/dev",
- value_name = "DELEGATE"
- )]
- delegate: String,
+ /// Agent delegate `uuid:rig:provider/model`. Omit for human-only ingests.
+ #[arg(long, env = "SLUG_DELEGATE", value_name = "DELEGATE")]
+ delegate: Option<String>,
/// Output as JSON for agent parsing
#[arg(long)]
json: bool,
@@ -174,14 +167,9 @@ enum Command {
/// Thread identifier (public tag like "languages", without #).
#[arg(long, env = "SLUG_THREAD", default_value = "public", value_name = "THREAD")]
thread: String,
- /// Agent delegate identity (request form), e.g. @@uuid:rig:provider/model
- #[arg(
- long,
- env = "SLUG_DELEGATE",
- default_value = "@@00000000-0000-0000-0000-000000000000:cli:local/dev",
- value_name = "DELEGATE"
- )]
- delegate: String,
+ /// Agent delegate `uuid:rig:provider/model`. Omit for human-only ingests.
+ #[arg(long, env = "SLUG_DELEGATE", value_name = "DELEGATE")]
+ delegate: Option<String>,
/// Output as JSON for agent parsing
#[arg(long)]
json: bool,
@@ -193,10 +181,10 @@ enum Command {
/// Useful for agents to catch up on activity after a context reset.
///
/// Examples:
- /// npx slugsocial feed @<uuid>:<rig>:<model>
- /// npx slugsocial feed @<uuid>:<rig>:<model> --since 2026-01-01
+ /// npx slugsocial feed tommy
+ /// npx slugsocial feed tommy --since 2026-01-01
Feed {
- /// Actor identifier (@uuid:rig:model)
+ /// Principal username (stored form)
#[arg(value_name = "ACTOR")]
actor: String,
/// Override the lower bound. Accepts Unix ms or YYYY-MM-DD.
@@ -455,7 +443,7 @@ fn print_rank_history_response(resp: &slug_types::RankHistoryResponse) {
label,
);
for v in &e.caused_by {
- println!(" {} {} {} {}", v.a, v.ratio, v.b, v.actor.as_deref().map(|a| format!(" (@{})", a)).unwrap_or_default());
+ println!(" {} {} {} {}", v.a, v.ratio, v.b, v.actor.as_deref().map(|a| format!(" ({})", a)).unwrap_or_default());
if !v.body.is_empty() {
println!(" {}", v.body.lines().next().unwrap_or(&v.body).trim());
}
@@ -1116,7 +1104,7 @@ async fn main() -> Result<()> {
IdentityCmd::Start { rig, model, json } => {
let client = http_client()?;
let uuid = uuid::Uuid::new_v4().to_string();
- let delegate = format!("@@{}:{}:{}", uuid, rig, model);
+ let delegate = format!("{uuid}:{rig}:{model}");
let start: PendingSessionStartResponse = expect_json(
client
diff --git a/server/src/api/auth.rs b/server/src/api/auth.rs
index cb0faa29b834931e2c2b2f5c174c875e2e2e9346..995ce4a61d29b024c399c656134f541ecfd880cf 100644
--- a/server/src/api/auth.rs
+++ b/server/src/api/auth.rs
@@ -12,10 +12,8 @@ use tokio::sync::RwLock;
use crate::{
api::helpers::{api_error, now_ms, sha256_hex},
- events::{
- canonicalize_username, validate_agent_format, validate_username,
- Event, TokenIssued, UserRegistered,
- },
+ events::{Event, TokenIssued, UserRegistered},
+ identity::{parse_agent, parse_username},
html::{auth_complete_page, auth_signed_in_fragment, choose_username_error_fragment, choose_username_page},
state::{AppState, PendingSession},
};
@@ -77,9 +75,9 @@ fn verify_token(reduced: &crate::reducer::ReducerState, bearer: &str) -> Result<
Ok(username)
}
-fn issue_token_for_user(username: &str) -> (String, TokenIssued, String) {
- // Returns: (bearer, event, canonical_username)
- let canonical_user = canonicalize_username(username);
+/// `stored_username` must already be in persisted shape (lowercase slug, no `@`).
+fn issue_token_for_user(stored_username: &str) -> (String, TokenIssued) {
+ let username = stored_username.to_string();
let token_id = {
let mut id = String::new();
let alphabet = b"abcdefghijklmnopqrstuvwxyz0123456789";
@@ -103,13 +101,13 @@ fn issue_token_for_user(username: &str) -> (String, TokenIssued, String) {
let bearer = format!("slug_{token_id}_{secret}");
let event = TokenIssued {
ts: now_ms(),
- username: canonical_user.clone(),
+ username: username.clone(),
token_id,
token_hash,
salt,
issued_via: "oauth".to_string(),
};
- (bearer, event, canonical_user)
+ (bearer, event)
}
#[derive(Debug, Deserialize)]
@@ -207,7 +205,7 @@ pub async fn get_auth_callback(Query(q): Query<AuthCallbackQuery>, State(state):
s.provider = Some("google".to_string());
s.provider_id = Some(sub.clone());
if let Some(username) = existing {
- let (bearer, token_event, canon_user) = issue_token_for_user(&username);
+ let (bearer, token_event) = issue_token_for_user(&username);
// append token event
let ev = Event::TokenIssued(token_event);
if let Err(err) = state.event_log.append(&ev).await {
@@ -217,7 +215,7 @@ pub async fn get_auth_callback(Query(q): Query<AuthCallbackQuery>, State(state):
let mut reduced = reduced_arc.write().await;
reduced.apply_event(ev);
}
- s.complete = Some((canon_user, bearer));
+ s.complete = Some((username, bearer));
return Redirect::temporary(&format!("{public_url}/auth/complete")).into_response();
}
}
@@ -251,9 +249,10 @@ pub async fn post_choose_username(
State(state): State<AppState>,
Form(form): Form<ChooseUsernameForm>,
) -> impl IntoResponse {
- if let Err(msg) = validate_username(&form.username) {
- return api_error(StatusCode::BAD_REQUEST, "invalid username", Some(msg)).into_response();
- }
+ let canon_user = match parse_username(&form.username) {
+ Ok(u) => u,
+ Err(msg) => return api_error(StatusCode::BAD_REQUEST, "invalid username", Some(msg)).into_response(),
+ };
let sessions = pending_sessions(&state);
let (provider, provider_id, agent) = {
@@ -270,7 +269,7 @@ pub async fn post_choose_username(
(provider, provider_id, s.agent.clone())
};
- if let Err(msg) = validate_agent_format(&agent) {
+ if let Err(msg) = parse_agent(&agent) {
return api_error(StatusCode::BAD_REQUEST, "invalid agent format", Some(msg)).into_response();
}
@@ -280,7 +279,7 @@ pub async fn post_choose_username(
if reduced.users_by_provider.contains_key(&provider_key) {
return api_error(StatusCode::CONFLICT, "provider already registered", None).into_response();
}
- if reduced.users_by_provider.values().any(|u| u == &canonicalize_username(&form.username)) {
+ if reduced.users_by_provider.values().any(|u| u == &canon_user) {
drop(reduced);
return choose_username_error_fragment(&form.session, "that username is taken — try another").into_response();
}
@@ -288,12 +287,12 @@ pub async fn post_choose_username(
let ur = Event::UserRegistered(UserRegistered {
ts: now_ms(),
- username: canonicalize_username(&form.username),
+ username: canon_user.clone(),
provider: provider.to_lowercase(),
provider_id: provider_id.clone(),
});
- let (bearer, ti, canon_user) = issue_token_for_user(&form.username);
+ let (bearer, ti) = issue_token_for_user(&canon_user);
let ti_ev = Event::TokenIssued(ti);
// Persist events.
@@ -325,15 +324,18 @@ pub async fn post_pending_session(
State(state): State<AppState>,
Json(req): Json<PendingSessionStartRequest>,
) -> impl IntoResponse {
- if let Err(msg) = validate_agent_format(&req.agent) {
- return api_error(StatusCode::BAD_REQUEST, "invalid agent format", Some(msg)).into_response();
- }
+ let agent_naked = match parse_agent(&req.agent) {
+ Ok(a) => a,
+ Err(msg) => {
+ return api_error(StatusCode::BAD_REQUEST, "invalid agent format", Some(msg)).into_response();
+ }
+ };
let session = format!("p_{}", uuid::Uuid::new_v4().simple());
let public_url = std::env::var("SLUG_PUBLIC_URL").unwrap_or_else(|_| "http://127.0.0.1:8080".to_string());
let login_url = format!("{public_url}/auth/login?session={}", urlencoding::encode(&session));
let poll_url = format!("/api/v0/pending-session/{}", session);
let s = PendingSession {
- agent: req.agent.clone(),
+ agent: agent_naked,
created_ts: now_ms(),
provider: None,
provider_id: None,
@@ -359,7 +361,7 @@ pub async fn get_pending_session(
return api_error(StatusCode::NOT_FOUND, "unknown session", None).into_response();
};
let (complete, user, token) = match &s.complete {
- Some((u, t)) => (true, Some(format!("@{}", u)), Some(t.clone())),
+ Some((u, t)) => (true, Some(u.clone()), Some(t.clone())),
None => (false, None, None),
};
Json(PendingSessionPollResponse {
@@ -388,7 +390,7 @@ pub async fn get_whoami(State(state): State<AppState>, headers: HeaderMap)
… preview truncated; 62,772 characters omittedHardlinks — judgments / attempts / prompt
judgments
- ~anthropic/claude-sonnet-latest: B (97:3)
- ~x-ai/grok-latest: B (1:25)
- openai/gpt-chat-latest: B (10:1)
attempts
Prompt text is loaded only by the download route.