Side A's diff is mostly a noisy dump of already-existing files pasted at the repo root, with literal shell-prompt artifacts (`tommy@Tommys-Laptop:~/...⇒ cat ...`) embedded inside the '.rs' content, meaning these are not real, buildable additions integrated into the actual server/src tree. Side B, though much smaller, adds a real, properly wired module (`routing.rs`/`RouteContext`) integrated into `html/mod.rs`, plus a clear, actionable refactor plan (`plan.md`) that gives concrete lasting guidance for future work — substance over spectacle.
constitution · epochs · watch · epoch 3
comparison
c_f6d0fed9bf9a (tommy-mor) vs c_7ec67b9cef2c (tommy-mor)
download prompt · raw event · cmp_ba9d5932eec01e
council reasoning
Side B delivers a precise, lasting architectural foundation: a complete phased plan for structural ItemId (replacing stringly CanonicalItemUrl) plus the clean RouteContext wrapper and export that begins migratable href generation. Side A is a noisy bulk dump of prototype files (parser/reducer/ranking/vote plus .tdsl notes) that includes terminal garbage embedded in forms.rs and ranking.rs, making much of the large diff non-lasting churn rather than polished design.
Side B introduces a concrete architectural abstraction (`RouteContext`) for centralized HTML route generation, re-exports it from the HTML module, and documents a coherent migration plan toward structured `ItemId` handling. Side A is much larger, but it mixes many unrelated additions with obvious accidental terminal transcript text embedded at the start/end of files such as `forms.rs` and `ranking.rs`, reducing the reliability and lasting value of the patch despite its scope.
sides
A — c_f6d0fed9bf9a (tommy-mor)
message
[1d9d8ade] init seed
diff preview
diff --git a/TEST.sh b/TEST.sh
new file mode 100755
index 0000000000000000000000000000000000000000..266b71f29259f5c2cad2617476ebe2ebc9596d39
--- /dev/null
+++ b/TEST.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cargo test --all
+./scripts/clj-test.sh
diff --git a/bundle.js b/bundle.js
new file mode 100644
index 0000000000000000000000000000000000000000..8d316f9a57cc7c379fe4bd8e42e092c7eac5d265
--- /dev/null
+++ b/bundle.js
@@ -0,0 +1,52 @@
+/**
+ * Slug web UI: only plumbing — fetch/eval/SSE. No product UI logic here.
+ */
+(function () {
+ function evalJs(js) {
+ if (js && String(js).trim()) {
+ eval(js);
+ }
+ }
+
+ // Theme cookie sync (runs before paint; full reload if localStorage disagrees with cookie)
+
+ function initSlugUi() {
+ // POST forms → eval response (except theme + full-navigation forms)
+ document.addEventListener('submit', async function (e) {
+ var f = e.target;
+ if (!f || f.tagName !== 'FORM') return;
+ if ((f.method || 'get').toLowerCase() !== 'post') return;
+ if (f.id === 'slug-theme-form') return;
+ if (f.getAttribute('data-navigate') === 'full') return;
+ e.preventDefault();
+ var resp = await fetch(f.action, {
+ method: 'POST',
+ body: new URLSearchParams(new FormData(f)),
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+ credentials: 'same-origin',
+ });
+ evalJs(await resp.text());
+ });
+
+ // SSE: server-pushed JS
+ function connectSSE() {
+ var ssePath = window.location.pathname + window.location.search;
+ var es = new EventSource('/sse?path=' + encodeURIComponent(ssePath));
+ es.onmessage = function (e) {
+ evalJs(e.data);
+ };
+ es.onerror = function () {
+ es.close();
+ setTimeout(connectSSE, 3000);
+ };
+ }
+ connectSSE();
+ }
+
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', initSlugUi);
+ } else {
+ initSlugUi();
+ }
+})();
+
diff --git a/clj-test.sh b/clj-test.sh
new file mode 100755
index 0000000000000000000000000000000000000000..b62a49b98ed60a65a46807b7ad80fa3142f14952
--- /dev/null
+++ b/clj-test.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+mkdir -p target
+exec clojure -M:kaocha
diff --git a/forms.rs b/forms.rs
new file mode 100644
index 0000000000000000000000000000000000000000..d509fd889fde3fed2662ce0a39006b7a51ae762a
--- /dev/null
+++ b/forms.rs
@@ -0,0 +1,145 @@
+tommy@Tommys-Laptop:~/programming/slug-star/slug|main ⇒ cat server/src/form_template.rs
+//! Plan2-style JSON templates with `{"$form": "field_name"}` holes, filled from
+//! `application/x-www-form-urlencoded` (or any `String` → `String` map) **before**
+//! deserializing into a typed struct.
+//!
+//! # Wire format
+//!
+//! Templates are **compact JSON** (`serde_json::to_string`): one line, no pretty
+//! printing, strings escaped per JSON rules (`\"`, `\n`, etc.). Embed that string
+//! in HTML attributes or text nodes with normal HTML escaping (e.g. maud), not
+//! bespoke encodings.
+//!
+//! # Power vs flat hidden fields
+//!
+//! A form is always a string→string map. You can fake depth with dotted keys (`a.b.c`),
+//! but one structured blob (`__rpc__` = compact JSON) gives you nested objects,
+//! arrays, and optional fields without inventing a new naming scheme each time.
+//!
+//! # Security
+//!
+//! Substitution runs **before** `serde` into your command type. It does not fix
+//! authorization: if the client can replace the hidden `__rpc__` value, they can
+//! change the command shape unless you validate (signed blob, server-side session
+//! context, or treat the blob as hints only). Same threat model as any hidden field.
+
+use serde::Serialize;
+use serde_json::Value;
+use std::collections::HashMap;
+
+/// Serialize a value to compact JSON for a hidden `__rpc__` (or similar) field.
+pub fn template_json_compact<T: Serialize>(v: &T) -> serde_json::Result<String> {
+ serde_json::to_string(v)
+}
+
+/// Recursively walk the JSON AST and replace `{"$form": "key"}` with the submitted
+/// string for `key` (empty if missing). Other keys are unchanged.
+pub fn substitute_form_vars(val: &mut Value, form_data: &HashMap<String, String>) {
+ match val {
+ Value::Object(map) => {
+ if map.len() == 1 {
+ if let Some(Value::String(field_name)) = map.get("$form") {
+ let submitted = form_data
+ .get(field_name.as_str())
+ .map(|s| s.as_str())
+ .unwrap_or("");
+ *val = Value::String(submitted.to_string());
+ return;
+ }
+ }
+ for v in map.values_mut() {
+ substitute_form_vars(v, form_data);
+ }
+ }
+ Value::Array(arr) => {
+ for v in arr.iter_mut() {
+ substitute_form_vars(v, form_data);
+ }
+ }
+ _ => {}
+ }
+}
+
+/// Parse JSON, apply [`substitute_form_vars`], return the mutated value.
+pub fn fill_template_from_form(
+ template_json: &str,
+ form_data: &HashMap<String, String>,
+) -> Result<Value, serde_json::Error> {
+ let mut v: Value = serde_json::from_str(template_json)?;
+ substitute_form_vars(&mut v, form_data);
+ Ok(v)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use serde::Deserialize;
+
+ #[derive(Debug, Deserialize, PartialEq, Eq)]
+ struct Demo {
+ room: String,
+ thread_tag: String,
+ nested: Nested,
+ }
+
+ #[derive(Debug, Deserialize, PartialEq, Eq)]
+ struct Nested {
+ text: String,
+ }
+
+ #[test]
+ fn holes_become_strings() {
+ let json = r#"{
+ "room": "public",
+ "thread_tag": {"$form": "tag"},
+ "nested": {"text": {"$form": "body"}}
+ }"#;
+ let mut form = HashMap::new();
+ form.insert("tag".into(), "foo".into());
+ form.insert("body".into(), "hello\nworld".into());
+
+ let v = fill_template_from_form(json, &form).unwrap();
+ let d: Demo = serde_json::from_value(v).unwrap();
+ assert_eq!(
+ d,
+ Demo {
+ room: "public".into(),
+ thread_tag: "foo".into(),
+ nested: Nested {
+ text: "hello\nworld".into(),
+ },
+ }
+ );
+ }
+
+ #[test]
+ fn missing_form_key_is_empty_string() {
+ let json = r#"{"x": {"$form": "nope"}}"#;
+ let mut form = HashMap::new();
+ form.insert("other".into(), "y".into());
+ let v = fill_template_from_form(json, &form).unwrap();
+ assert_eq!(v["x"], "");
+ }
+
+ #[test]
+ fn array_of_holes() {
+ let json = r#"{"items": [{"$form": "a"}, {"$form": "b"}]}"#;
+ let mut form = HashMap::new();
+ form.insert("a".into(), "1".into());
+ form.insert("b".into(), "2".into());
+ let v = fill_template_from_form(json, &form).unwrap();
+ assert_eq!(v["items"], serde_json::json!(["1", "2"]));
+ }
+
+ #[test]
+ fn template_json_compact_escapes_and_single_line() {
+ let s = template_json_compact(&serde_json::json!({
+ "x": "quote\"and\nnewline"
+ }))
+ .unwrap();
+ assert!(!s.contains('\n'));
+ assert!(s.contains("\\\"") || s.contains("\\n"));
+ }
+}
+tommy@Tommys-Laptop:~/programming/slug-star/slug|main ⇒
+
diff --git a/gameifying.tdsl b/gameifying.tdsl
new file mode 100644
index 0000000000000000000000000000000000000000..93d2a61d94fcba4370c82d9612e6bb0f0318cc15
--- /dev/null
+++ b/gameifying.tdsl
@@ -0,0 +1,2 @@
+consider gating certain views (top all time?) by a 10 day usage streak.. or something like that.
+or like a path, on homepage(?), that shows day 1: r/amitheasshole, day2: r/aww, day3: gaming, or something like that. progressive revelation + usage incentive.
diff --git a/pagerank_streaming.tdsl b/pagerank_streaming.tdsl
new file mode 100644
index 0000000000000000000000000000000000000000..0f2231b94936c17610adf653ca26b0faa6f2ac3a
--- /dev/null
+++ b/pagerank_streaming.tdsl
@@ -0,0 +1,11 @@
+eventually i want to have ranking histories.
+like "visionary" and "fraud" waxing and waning in a uplot graph over time for #elon-musk.
+there are too many query combinations to precomupte the ranking histories
+(arbitrary user filters, and tag overlap combinations maybe),
+so we're just going to have to calculate them all on demand.
+computers are fast, its okay. for each vote, we need to calculate rank centrality again.
+i was thinking, for n votes we calculate the rank centrality,
+and get node weights. we then output that data to the client (over websocket, or testable barrier).
+then we calculate n+1 votes, _but we keep the node weights in memory_
+so the rank centrality process converges faster.
+this also has the side effect of making the ranking stream in satisfyingly as you load the page.
diff --git a/parser.rs b/parser.rs
new file mode 100644
index 0000000000000000000000000000000000000000..2b87b974f8d1dd93bee35681d87668a94e4ef349
--- /dev/null
+++ b/parser.rs
@@ -0,0 +1,1808 @@
+use std::collections::HashMap;
+use std::rc::Rc;
+use std::cell::RefCell;
+use crate::ui::action::UIAction;
+use crate::ui::types::{Suggestion, GuideOption, ScrollingSuggestion};
+
+// --- Core Abstractions ---
+
+/// Unique identifier for nodes in the graph
+type NodeId = &'static str;
+
+/// Pattern matching for edges
+#[derive(Debug, Clone)]
+pub enum EdgePattern {
+ /// Matches exact literal string
+ Literal(&'static str),
+
+ /// Matches any prefix of a string and suggests the full string
+ /// e.g., PrefixOf("reddit.com") matches "r", "re", "red", "reddit", "reddit.com"
+ PrefixOf(&'static str),
+
+ /// Captures a variable segment (e.g., subreddit name, username)
+ Variable(&'static str),
+
+ /// Matches any string (wildcard)
+ Any,
+}
+
+impl EdgePattern {
+ /// Try to match this pattern against input, return (consumed_chars, captured_value)
+ fn matches(&self, input: &str) -> Option<(usize, Option<String>)> {
+ match self {
+ EdgePattern::Literal(lit) => {
+ if input.starts_with(lit) {
+ Some((lit.len(), None))
+ } else {
+ None
+ }
+ }
+ EdgePattern::PrefixOf(target) => {
+ // Check if input is a prefix of target
+ if target.starts_with(input) && !input.is_empty() {
+ // It's a valid prefix
+ Some((input.len(), None))
+ } else if input.starts_with(target) {
+ // Full match
+ Some((target.len(), None))
+ } else {
+ None
+ }
+ }
+ EdgePattern::Variable(var_name) => {
+ // Consume until next '/' or end of string
+ let end = input.find('/').unwrap_or(input.len());
+ if end > 0 {
+ let captured = input[..end].to_string();
+ // Validate based on variable type
+ if is_valid_variable(var_name, &captured) {
+ Some((end, Some(captured)))
+ } else {
+ None
+ }
+ } else {
+ None
+ }
+ }
+ EdgePattern::Any => {
+ // Match everything until next '/' or end
+ let end = input.find('/').unwrap_or(input.len());
+ if end > 0 {
+ Some((end, Some(input[..end].to_string())))
+ } else {
+ None
+ }
+ }
+ }
+ }
+
+ /// G
… preview truncated; 148,978 characters omittedB — c_7ec67b9cef2c (tommy-mor)
message
[1c914c6e] stage set
diff preview
diff --git a/plan.md b/plan.md
new file mode 100644
index 0000000000000000000000000000000000000000..00d6867a1e0ed144a16a020ea037f685ce646c73
--- /dev/null
+++ b/plan.md
@@ -0,0 +1,155 @@
+# Plan: `ItemId` + `RouteContext` (identity vs hrefs)
+
+This document is for **the next agent** to continue the refactor without re-deriving context from chat. It supersedes ad-hoc notes: treat it as the checklist of record until the work lands and this file is deleted or trimmed.
+
+## Goal
+
+- **Identity** (what lives in the reducer graph, votes, indexes) becomes a **structural `ItemId` enum** in `slug-types`, not a canonical `String` / `CanonicalItemUrl` newtype.
+- **Presentation** (tilde / dash display, breadcrumbs) derives from `ItemId` via explicit methods, not string stripping.
+- **Routing** (browser `href`s for public vs room) goes through **`RouteContext`** (started in `server/src/html/routing.rs`) so Maud/handlers do not stitch `/r/…` vs `/~` ad hoc.
+
+**Non-goals for v1 of the migration:** backward-compatible JSONL or dual-read of old canonical strings in the event log (project has accepted breaking changes). If you reintroduce compat, document it here.
+
+## Current state (as of this plan)
+
+- **`CanonicalItemUrl`** (`types/src/paths.rs`): newtype around `String`; `parse` / `parent` / `display_path` / `tilde_tail` / etc. Reducer `ContentState`, `VoteData`, ranking, RPC, search, garden, breadcrumbs all use it or `String` keys derived from it.
+- **`ThreadNav`** (`server/src/html/forum/nav.rs`): encodes scope prefixes for threads and garden URLs; **`RouteContext`** now wraps `ThreadNav` (`server/src/html/routing.rs`, re-exported from `server/src/html/mod.rs`) but **most HTML still takes `&ThreadNav` directly** — migration incomplete.
+- **URL normalization** lives in `types/src/url_normalize.rs` + `canonicalize_item` / `finalize_external_identity_url` in `paths.rs` (YouTube, sorted query params, room path `room_route_segment` in `paths.rs`).
+- **Room HTTP paths** are `/r/{short}{slug}` (fused segment); wire **`room_id`** remains `short/slug` for RPC/events.
+
+## Target architecture
+
+### `ItemId` (types)
+
+Suggested shape (adjust after profiling `Ord` / `Hash` / serde size):
+
+```text
+ItemId::Root — tilde ontology root (today `SLUG_TILDE_ONTOLOGY_ROOT`)
+ItemId::Local { segments } — slug.social ~/… path as Vec<String> (lowercase segments, non-empty for non-root)
+ItemId::External { url: Url } — normalized `url::Url` (crate `url` already in `slug-types`)
+```
+
+**API surface (minimum):**
+
+- `ItemId::parse(&str) -> Option<ItemId>` — single entry from DSL / user input / legacy wire (internally may call `canonicalize_item` + structured split).
+- `ItemId::to_wire_url(&self) -> String` — only for **external** boundaries if needed (HTTP fetch, rare assertions); avoid using as the primary key once maps use `ItemId`.
+- `parent`, `display_path`, `tilde_tail` / `tilde_http_tail`, `tilde_segments`, `last_segment`, `normalized_storage` — port from `CanonicalItemUrl`.
+- **`Ord` + `Hash` + `Eq`** stable for `BTreeSet` / `HashMap` (see `write_actor` scope-rank snapshots).
+- **`Serialize` / `Deserialize`** — decide **tagged JSON** for any persisted or API-carried structs (e.g. `VoteData` in tests). If RPC must stay stringy for clients, use a **DTO layer** that converts `ItemId` ↔ wire at the boundary only.
+
+**Remove:** `CanonicalItemUrl` type and all `path_types::CanonicalItemUrl` / `slug_types::paths::CanonicalItemUrl` exports once call sites are migrated. **`Borrow<str>`** on the old newtype goes away; update `nav!` / any code that assumed map keys borrowed as `str`.
+
+### `RouteContext` (server HTML)
+
+- **File:** `server/src/html/routing.rs` — **`RouteContext(ThreadNav)`** with `item_href`, `item_href_raw`, `thread_url`, `garden_root_url`, `room_url`, `From`/`Into` `ThreadNav`.
+- **Direction:** new code and refactored Maud should take **`&RouteContext`** (or owned where appropriate) instead of `&ThreadNav` when building links. Long term, **`item_href(&ItemId)`** should not parse strings — it should pattern-match `ItemId` and append tilde tail or `/-/…` external tail using the same rules as today’s `ThreadNav::garden_item_url`.
+
+### Axum / garden routes
+
+- **No** single catch-all route (explicit decision): keep the existing router layout in `server/src/lib.rs`.
+- Room routes stay **`/r/:room_key/...`** with `room_key` fused; parsing via `slug_types::room_id_from_route_segment` / `room_route_segment` in `paths.rs`.
+
+## Phased execution (recommended order)
+
+### Phase 0 — Preconditions (quick)
+
+1. Read **`AGENTS.md`** (UI contract, durability matrix, `RpcCommand` vs `HtmlUiAction`).
+2. Run **`cargo test --workspace`** and **`./scripts/clj-test.sh`** on clean `main` before large diffs; repeat after each phase.
+
+### Phase 1 — `ItemId` in `slug-types` (no server yet)
+
+1. Add **`ItemId`** (new file e.g. `types/src/item_id.rs` **or** inline at bottom of `paths.rs` — see **Module cycle** below).
+2. Implement **`ItemId::parse`** using existing **`canonicalize_item`** + normalization; port **`CanonicalItemUrl`** methods to **`ItemId`** with tests ported from `paths.rs` `#[cfg(test)] mod tests`.
+3. **`GardenItemUrl::from_stored(&ItemId, room_wire)`** (and thread helpers) — build absolute hrefs from structure, not from re-parsing a canonical string.
+4. **`TildeHttpPathTail::to_item_id`** (rename from `to_canonical`) / **`tilde_http_path_to_item_id`**.
+5. **`TildeOntologyPath::from_stored(&ItemId)`**.
+6. Export **`ItemId`** from **`types/src/lib.rs`**; update **`server/src/path_types.rs`** re-exports.
+7. **Delete `CanonicalItemUrl`** and fix all **in-crate** references in `types` only until `cargo test` passes for `slug-types`.
+
+**Module cycle trap:** `item_id.rs` must not `use crate::paths::{...}` if `paths.rs` also imports `ItemId` for `GardenItemUrl` in the same module. **Fix one of:**
+
+- **A)** Put `ItemId` **inside `paths.rs`** below `canonicalize_item` / helpers (simplest, large file), or
+- **B)** Split **`canonicalize_item`** (+ dash host helpers + `finalize_external_identity_url`) into **`types/src/item_wire.rs`**, then `paths.rs` + `item_id.rs` both depend on `item_wire` only (cleaner, more files).
+
+### Phase 2 — Reducer + ranking (server core)
+
+1. **`server/src/reducer.rs`**: `ContentState` / `GroupState` / **`VoteData`** — replace **`CanonicalItemUrl`** with **`ItemId`** on all maps, sets, deques, vectors.
+2. **`apply_vote`**: normalize `a`/`b` via **`ItemId::parse`** or **`ItemId`**-aware logic (remove string round-trip).
+3. **`apply_ingest_to_content`**: **`dsl`** still yields strings for item titles in statements; normalize to **`ItemId`** at ingest boundary via **`ItemId::parse`** once per item.
+4. **`server/src/ranking.rs`**, **`server/src/scope_rank.rs`**, **`server/src/api/write_actor.rs`** (including **`BTreeSet`** ordering), **`server/src/api/validate.rs`**, **`server/src/api/helpers.rs`** — propagate **`ItemId`**.
+5. **`server/tests/basic.rs`** and any reducer tests constructing **`VoteData`** — use **`ItemId::parse(...).unwrap()`** or helpers.
+
+### Phase 3 — RPC + search + external resolver
+
+1. **`server/src/api/rpc.rs`**: rank/pair/matchup/search payloads; today many paths use **`GardenItemUrl::from_storage_str(item.as_str(), …)`** — switch to **`ItemId`** + **`GardenItemUrl::from_stored(&item_id, …)`** (or equivalent).
+2. **`server/src/html/search.rs`**: scoring uses item path strings — derive from **`ItemId::display_path`** / **`to_wire_url`** only at the scoring boundary if needed.
+3. **`server/src/external_resolver.rs`**: take **`&ItemId`** or **`ItemId::external_url()`** instead of **`&CanonicalItemUrl`**.
+
+### Phase 4 — HTML / Maud
+
+1. **`ThreadNav::garden_item_url`**: overload or replace with **`garden_item_href(&self, item: &ItemId)`** (no `CanonicalItemUrl::parse` inside).
+2. **`RouteContext`**: extend **`item_href(&ItemId)`**; migrate call sites from **`ThreadNav`** to **`RouteContext`** where only link-building is needed (keep **`ThreadNav`** where scope / auth helpers need the full struct).
+3. **`server/src/html/garden.rs`**, **`breadcrumb_path.rs`**, **`forum/*`**, **`editor.rs`**: replace **`CanonicalItemUrl`** with **`ItemId`**; breadcrumbs should walk **`ItemId::parent`** without string `rsplit`.
+4. **`types` JSON types** (`RankRow`, etc.): decide whether **`GardenItemUrl`** stays string for JSON or becomes a structured field; keep **one** wire format for the public API.
+
+### Phase 5 — Cleanup + docs
+
+1. Remove dead **`canonical_path`** / **`breadcrumb_path`** string logic if fully superseded.
+2. Update **`AGENTS.md`** if durability, `POST /ui`, or command surfaces change.
+3. Delete or shrink **`plan.md`** when done.
+
+## File / symbol checklist (non-exhaustive — grep-driven)
+
+Run periodically:
+
+```bash
+rg "CanonicalItemUrl" -g'*.rs'
+rg "path_types::CanonicalItemUrl" -g'*.rs'
+rg "tilde_http_path_to_canonical" -g'*.rs'
+```
+
+**High-touch files (from prior exploration):**
+
+| Area | Files |
+|------|--------|
+| Types | `types/src/paths.rs`, `types/src/lib.rs`, `types/src/url_normalize.rs`, (optional) `types/src/item_id.rs`, `types/src/item_wire.rs` |
+| Server re-exports | `server/src/path_types.rs`, `server/src/canonical_path.rs` |
+| Reducer / ingest | `server/src/reducer.rs`, `server/src/dsl.rs` (parse output types if changed) |
+| Ranking | `server/src/ranking.rs`, `server/src/scope_rank.rs` |
+| Writer / RPC | `server/src/api/write_actor.rs`, `server/src/api/rpc.rs`, `server/src/api/helpers.rs`, `server/src/api/validate.rs` |
+| HTML | `server/src/html/garden.rs`, `server/src/html/breadcrumb_path.rs`, `server/src/html/forum/nav.rs`, `server/src/html/routing.rs`, `server/src/html/search.rs`, `server/src/html/editor.rs`, `server/src/html/forum/ingest.rs`, … |
+| Tests | `server/tests/basic.rs`, `server/tests/integration.rs`, `types/src/paths.rs` tests, Clojure under `test/` if URLs/assertions mention canonical shapes |
+
+## Events / JSONL
+
+- **`Ingest`** events store **`raw` DSL** only — no change required for item identity inside the event.
+- If any future event type stores item ids as strings, migrate to **structured `ItemId` serde** or accept string only at the event boundary with immediate parse into **`ItemId`** on `apply_event`.
+
+## `nav!` macro (`server/src/paths.rs`)
+
+- Macros use **`keypath($key)`** with **`.clone()`** — **`ItemId`** must be **`Clone`** (already for enums). Remove any reliance on **`Borrow<str>`** for map keys.
+
+## Testing gate
+
+After each phase:
+
+```bash
+cargo test --workspace
+./scripts/clj-test.sh
+```
+
+## Risks / gotchas
+
+1. **`Ord` on `ItemId`**: must match prior **`CanonicalItemUrl`** / `String` ordering wherever **`BTreeSet`** is used (e.g. deterministic scope-rank snapshots in **`write_actor`**).
+2. **External `ItemId`**: **`Url`** equality / hashing — normalization is already centralized in **`url_normalize`**; ensure **`ItemId::parse`** always inserts normalized **`Url`** into **`External`**.
+3. **Fake parent URLs** in garden (e.g. **`https://.`** for external root ranking): find all **`parse("https://.")`** style hacks and express as **`ItemId`** or a dedicated sentinel.
+4. **Serde**: tests and any RPC clients that snapshot JSON may need expectation updates if **`VoteData`** shape changes.
+
+## Optional follow-ups (not blocking `ItemId`)
+
+- More **domain normalizers** in **`url_normalize.rs`** (e.g. `music.youtube.com`, Spotify, etc.).
+- **Room wire** vs **HTTP segment** helpers already in **`paths.rs`** (`ROOM_SHORT_ID_LEN`, `room_route_segment`, `room_id_from_route_segment`).
+
+---
+
+**End state criteria:** `rg CanonicalItemUrl` returns nothing; reducer maps use **`ItemId`**; HTML link generation for items goes through **`RouteContext` + `ItemId`**; tests and Kaocha green.
diff --git a/server/src/html/mod.rs b/server/src/html/mod.rs
index c3dccd03dc6da2a2f6f6fa828657e33a951884b
… preview truncated; 2,831 characters omittedHardlinks — judgments / attempts / prompt
judgments
attempts
Prompt text is loaded only by the download route.