Side A is a real, tested refactor that de-duplicates substantial shared test logic (HTTP helpers, mock OAuth, server env, harness counters) across auth.bb, grants.bb, integration.bb, and oauth.bb, reducing duplication and improving maintainability with no behavior change. Side B is almost entirely a speculative planning document (plan.md) plus a thin, unused-by-callers RouteContext wrapper stub that doesn't migrate any call sites, representing scaffolding/intent rather than delivered value.
constitution · epochs · watch · epoch 3
comparison
c_48fcbcde8f88 (tommy-mor) vs c_7ec67b9cef2c (tommy-mor)
download prompt · raw event · cmp_282f80313e5765
council reasoning
A finishes a real maintainability win: it deletes large duplicated copies of HTTP/OAuth/assert/build helpers from auth.bb/grants.bb/integration.bb and centralizes them in test.common and test.oauth (including multi-user mock Google, complete-registration!, slug-server-env, cargo build helper). B mainly adds a forward-looking plan.md plus a thin RouteContext wrapper around ThreadNav with no call-site migration of ItemId yet, so most lasting substance is still unfinished scaffolding.
Side A performs a substantial refactor that consolidates duplicated test infrastructure into shared utilities (`test.common` and `test.oauth`), adds reusable helpers such as `run-cargo-build-release!`, `slug-server-env`, `complete-registration!`, and parameterized mock Google behavior, and updates multiple integration test suites to use them. Side B mainly adds a planning document and introduces a thin `RouteContext` wrapper re-export without migrating call sites, so it provides architectural intent but little immediate functional value.
sides
A — c_48fcbcde8f88 (tommy-mor)
message
[b32c92f2] consolidated shared functions in tests (composer 2 fast)
diff preview
diff --git a/test/auth.bb b/test/auth.bb
index a67cc1de763434176d2f68e419dd37a8cd328395..78cffc875ffe83f512bca253f4a7489227311da4 100644
--- a/test/auth.bb
+++ b/test/auth.bb
@@ -3,113 +3,14 @@
(:require [babashka.process :as p]
[babashka.fs :as fs]
[cheshire.core :as json]
- [org.httpkit.server :as http]
- [test.common :as common]))
+ [clojure.string :as str]
+ [test.common :as common]
+ [test.oauth :as oauth]))
-(def ^:private ansi-green "\033[32m")
-(def ^:private ansi-red "\033[31m")
-(def ^:private ansi-reset "\033[0m")
(def ^:private counts (atom {:pass 0 :fail 0}))
-(defn- pass [msg]
- (swap! counts update :pass inc)
- (println (str ansi-green " ✓ " ansi-reset msg)))
-
-(defn- fail [msg]
- (swap! counts update :fail inc)
- (println (str ansi-red " ✗ " ansi-reset msg)))
-
(defn- assert! [pred msg]
- (if pred
- (pass msg)
- (do (fail msg)
- (throw (ex-info (str "FAIL: " msg) {})))))
-
-(defn- http-client []
- (-> (java.net.http.HttpClient/newBuilder)
- (.followRedirects java.net.http.HttpClient$Redirect/ALWAYS)
- (.build)))
-
-(defn- http-get [url & {:keys [headers]}]
- (let [b (java.net.http.HttpRequest/newBuilder (java.net.URI/create url))]
- (doseq [[k v] (or headers {})]
- (.header b k v))
- (let [req (-> b (.GET) (.build))
- resp (.send (http-client) req (java.net.http.HttpResponse$BodyHandlers/ofString))]
- {:status (.statusCode resp) :body (.body resp) :headers (.map (.headers resp))})))
-
-(defn- http-post-json [url data & {:keys [headers]}]
- (let [body (json/generate-string data)
- b (java.net.http.HttpRequest/newBuilder (java.net.URI/create url))]
- (.header b "Content-Type" "application/json")
- (doseq [[k v] (or headers {})]
- (.header b k v))
- (let [req (-> b
- (.POST (java.net.http.HttpRequest$BodyPublishers/ofString body))
- (.build))
- resp (.send (http-client) req (java.net.http.HttpResponse$BodyHandlers/ofString))]
- {:status (.statusCode resp) :body (.body resp) :headers (.map (.headers resp))})))
-
-(defn- http-post-form [url form]
- (let [pairs (->> form
- (map (fn [[k v]]
- (str (java.net.URLEncoder/encode (name k) "UTF-8")
- "="
- (java.net.URLEncoder/encode (str v) "UTF-8"))))
- (clojure.string/join "&"))
- b (java.net.http.HttpRequest/newBuilder (java.net.URI/create url))]
- (.header b "Content-Type" "application/x-www-form-urlencoded")
- (let [req (-> b
- (.POST (java.net.http.HttpRequest$BodyPublishers/ofString pairs))
- (.build))
- resp (.send (http-client) req (java.net.http.HttpResponse$BodyHandlers/ofString))]
- {:status (.statusCode resp) :body (.body resp) :headers (.map (.headers resp))})))
-
-(defn- parse-query [s]
- (into {}
- (for [part (clojure.string/split (or s "") #"&")
- :when (not (clojure.string/blank? part))]
- (let [[k v] (clojure.string/split part #"=" 2)]
- [(keyword (java.net.URLDecoder/decode k "UTF-8"))
- (some-> v (java.net.URLDecoder/decode "UTF-8"))]))))
-
-(defn- b64url [s]
- (-> (java.util.Base64/getUrlEncoder)
- (.withoutPadding)
- (.encodeToString (.getBytes s "UTF-8"))))
-
-(defn- make-id-token [sub]
- (str (b64url "{\"alg\":\"RS256\",\"typ\":\"JWT\"}")
- "."
- (b64url (json/generate-string {:sub sub}))
- ".fakesig"))
-
-(defn- start-mock-google [port]
- (let [google-users ["google-user-1" "google-user-2"]
- !call-count (atom 0)
- handler
- (fn [req]
- (cond
- (and (= :get (:request-method req))
- (= "/o/oauth2/v2/auth" (:uri req)))
- (let [q (parse-query (:query-string req))
- redirect-uri (:redirect_uri q)
- state (:state q)
- loc (str redirect-uri "?code=mockcode&state=" state)]
- {:status 302 :headers {"Location" loc} :body ""})
-
- (and (= :post (:request-method req))
- (= "/token" (:uri req)))
- (let [n (swap! !call-count inc)
- sub (nth google-users (mod (dec n) (count google-users)))]
- {:status 200
- :headers {"Content-Type" "application/json"}
- :body (json/generate-string {:id_token (make-id-token sub)})})
-
- :else
- {:status 404 :body "not found"}))
- stop-fn (http/run-server handler {:port port})]
- {:stop-fn stop-fn :port port}))
+ (common/test-assert! counts pred msg))
(defn auth-test [& _args]
(println "\n━━━ auth v3 integration check ━━━\n")
@@ -117,8 +18,7 @@
(println "building server + CLI binaries…")
(common/letlocals
- (bind build @(p/process [(common/cargo-bin) "build" "--release" "-p" "slugsocial-server" "-p" "slugsocial"]
- {:inherit true :env common/base-env}))
+ (bind build (common/run-cargo-build-release! ["slugsocial-server" "slugsocial"]))
(assert! (zero? (:exit build)) "cargo build succeeds")
(bind server-bin "target/release/slugsocial-server")
(bind cli-bin "target/release/slugsocial")
@@ -134,19 +34,10 @@
(bind !server (atom nil))
(bind !google (atom nil))
- (bind server-env (merge common/base-env
- {"SLUG_DATA_DIR" tmp-dir
- "SLUG_KEYS" "test:test"
- "PORT" (str slug-port)
- "RUST_LOG" "warn"
- "SLUG_PUBLIC_URL" base-url
- "SLUG_GOOGLE_AUTH_URL" (str google-url "/o/oauth2/v2/auth")
- "SLUG_GOOGLE_TOKEN_URL" (str google-url "/token")
- "SLUG_GOOGLE_CLIENT_ID" "mock"
- "SLUG_GOOGLE_CLIENT_SECRET" "mock"}))
+ (bind server-env (common/slug-server-env tmp-dir base-url google-url slug-port))
(try
(println (str "\nstarting mock google on :" google-port))
- (reset! !google (start-mock-google google-port))
+ (reset! !google (oauth/start-mock-google google-port :google-users ["google-user-1" "google-user-2"]))
(assert! (some? (:stop-fn @!google)) "mock google started")
(println (str "starting server on :" slug-port))
@@ -154,34 +45,33 @@
(assert! (common/wait-for-server base-url 10000) "server responds to /healthz")
(println "\nstarting pending session…")
- (let [start-resp (http-post-json (str base-url "/api/v0/pending-session")
- {:agent "00000000-0000-0000-0000-000000000000:bb:local/dev"})
+ (let [start-resp (oauth/http-post-json (str base-url "/api/v0/pending-session")
+ {:agent "00000000-0000-0000-0000-000000000000:bb:local/dev"})
_ (assert! (= 200 (:status start-resp)) "pending-session start returns 200")
start-json (json/parse-string (:body start-resp) true)]
- (assert! (clojure.string/starts-with? (:session start-json) "p_") "session id has p_ prefix")
- (assert! (clojure.string/includes? (:login_url start-json) "/auth/login") "login_url provided")
+ (assert! (str/starts-with? (:session start-json) "p_") "session id has p_ prefix")
+ (assert! (str/includes? (:login_url start-json) "/auth/login") "login_url provided")
(println "\nsimulating browser oauth redirects…")
- ;; This will follow redirects: /auth/login -> mock google -> /auth/callback -> /auth/choose-username
- (let [login-get (http-get (:login_url start-json))]
+ (let [login-get (oauth/http-get (:login_url start-json))]
(assert! (= 200 (:status login-get)) "choose-username page reachable after oauth callback"))
(println "\nchoosing username…")
- (let [choose (http-post-form (str base-url "/auth/choose-username")
- {:session (:session start-json) :username "bbuser"})]
+ (let [choose (oauth/http-post-form (str base-url "/auth/choose-username")
+ {:session (:session start-json) :username "bbuser"})]
(assert! (= 200 (:status choose)) "choose-username POST returns 200"))
(println "\npolling pending session…")
- (let [poll (http-get (str base-url "/api/v0/pending-session/" (:session start-json)))]
+ (let [poll (oauth/http-get (str base-url "/api/v0/pending-session/" (:session start-json)))]
(assert! (= 200 (:status poll)) "pending-session poll returns 200")
(let [poll-json (json/parse-string (:body poll) true)]
(assert! (:complete poll-json) "pending session complete=true")
(assert! (= "bbuser" (:user poll-json)) "poll returns stored username bbuser")
- (assert! (clojure.string/starts-with? (:token poll-json) "slug_") "poll returns bearer token")
+ (assert! (str/starts-with? (:token poll-json) "slug_") "poll returns bearer token")
(println "\nwhoami…")
- (let [who (http-get (str base-url "/api/v0/whoami")
- :headers {"Authorization" (str "Bearer " (:token poll-json))})]
+ (let [who (oauth/http-get (str base-url "/api/v0/whoami")
+ :headers {"Authorization" (str "Bearer " (:token poll-json))})]
(assert! (= 200 (:status who)) "whoami returns 200")
(let [who-json (json/parse-string (:body who) true)]
(assert! (= "bbuser" (:user who-json)) "whoami user is bbuser (stored form)"))))))
@@ -195,11 +85,11 @@
(str "identity start exits 0 (stderr: " (:err start-proc) ")"))
(let [start-cli (json/parse-string (:out start-proc) true)]
(assert! (= "present_oauth_url_to_user" (:phase start-cli)) "identity start --json phase")
- (assert! (clojure.string/starts-with? (:session start-cli) "p_") "CLI start session id")
- (let [login-get (http-get (:login_url start-cli))]
+ (assert! (str/starts-with? (:session start-cli) "p_") "CLI start session id")
+ (let [login-get (oauth/http-get (:login_url start-cli))]
(assert! (= 200 (:status login-get)) "CLI login_url redirect chain succeeds"))
- (let [choose (http-post-form (str base-url "/auth/choose-username")
- {:session (:session start-cli) :username "cliuser"})]
+ (let [choose (oauth/http-post-form (str base-url "/auth/choose-username")
+ {:session (:session start-cli) :username "cliuser"})]
(assert! (= 200 (:status choose)) "choose-username for cliuser"))
(let [poll-proc @(p/process [cli-bin "identity" "poll" (:session start-cli)
"--poll-interval-ms" "100" "--max-wait-secs" "30" "--json"]
@@ -209,10 +99,10 @@
(let [poll-cli (json/parse-string (:out poll-proc) true)]
(assert! (= "complete" (:phase poll-cli)) "identity poll --json phase")
(assert! (= "cliuser" (:user poll-cli)) "CLI poll user (stored form)")
- (assert! (clojure.string/starts-with? (:token poll-cli) "slug_") "CLI poll token")
+ (assert! (str/starts-with? (:token poll-cli) "slug_") "CLI poll token")
(let [token-path (str cli-home "/.config/slugsocial/token")]
(assert! (fs/exists? token-path) "token written under isolated HOME")
- (assert! (= (clojure.string/trim (slurp token-path)) (:token poll-cli))
+ (assert! (= (str/trim (slurp token-path)) (:token poll-cli))
"token file matches poll JSON"))
… preview truncated; 24,704 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.