MOTIVATION

Worlds currently have two identifiers: an internal UUID (World.world_id, used as the routing key and directory name) and a display-only name. With slugs coming in as a first-class, required, URL-safe identifier, that three-identifier situation is complexity for no gain. Simpler: the slug is the identifier. The UUID goes away entirely.

This is a refactor, not a feature. Scope is deliberately narrow: replace every reference to world_id: Uuid with the slug. No UI changes. No new MCP tools. No behavioral changes besides the identifier swap.

A follow-up ticket for a bolt-on read-only web UI at /w/:slug/... depends on this one landing first.

================================================================ THE RULE

A world has exactly one identifier: its slug.

• Required at creation. No Option, no default, no auto-generation.
• Validated at the creation boundary against the URL-safe grammar below.
• Unique across the registry. Collisions fail loud with SLUG_COLLISION.
• Used as the directory name in {data_root}/worlds/{slug}/.
• Used as the HashMap key in the in-memory registry.
• Returned wherever responses today return world_id.

================================================================ GRAMMAR

Valid slug, precisely:

• Length: 1..=64
• First character: [a-z0-9]
• Last character: [a-z0-9]
• Middle characters (if any): [a-z0-9_-]
• Single-character slugs allowed (they are their own first AND last)
• No uppercase, no dots, no whitespace, no other punctuation

Examples: ant-smoke OK my_world OK ant-1 OK prod OK a OK a1-b2_c3 OK Ant-smoke REJECT (uppercase) ant smoke REJECT (whitespace) -ant REJECT (leading hyphen) ant REJECT (leading underscore) ant- REJECT (trailing hyphen) ant REJECT (trailing underscore) ant.smoke REJECT (dot is reserved for entity id hierarchy) "" REJECT (empty) 65+ chars REJECT (too long)

Validation is strict. No normalization, no trimming, no prettification. The string as typed is either valid or rejected.

================================================================ WHAT CHANGES AT EACH LAYER

src/slug.rs (NEW, ~60 lines + tests)

• pub fn validate(raw: &str) -> Result<&str, SlugError> Returns the input unchanged on success. No normalize function exists.
• pub enum SlugError { Empty, TooLong { len: usize }, InvalidChar { ch: char, index: usize }, LeadingHyphen, TrailingHyphen, LeadingUnderscore, TrailingUnderscore, }
• Implements Display and std::error::Error.
• Unit tests cover every rule in the grammar table above.

src/kernel.rs

• World.world_id: Uuid -> World.slug: String. Required. No #[serde(default)] — deserializing a pre-slug world fails loud.
• World::new(now, chronon) -> World::new(slug, now, chronon)
• World::with_environment(now, chronon, env) -> World::with_environment(slug, now, chronon, env)
• Internal references to self.world_id become self.slug.

src/scenarios.rs

• Scenario::seed(now) -> Scenario::seed(slug: String, now). Slug passes through to World::new. No slug validation here — validation happens at the create_world boundary.

src/worlds.rs (the core of the refactor)

• WorldMeta.world_id: Uuid -> WorldMeta.slug: String. Required, no default.
• DeletedWorldRecord.world_id: Uuid -> DeletedWorldRecord.slug: String.
• world_dir(data_root, world_id: Uuid) -> world_dir(data_root, slug: &str). Returns {data_root}/worlds/{slug}/.
• create_world(data_root, scenario, name: Option<String>) -> create_world(data_root, scenario, slug: String, name: Option<String>). Validates slug via slug::validate before any disk or registry work. Fails with a typed error on grammar violation. Dir-exists collision check stays. In-memory registry collision lives in the MCP layer (see below) so the insert and the check share one write-lock scope.
• load_all validates each directory name against the slug grammar; any directory whose name fails validation is logged and skipped (same policy as the current "not a UUID" branch).
• WorldMeta::read fails loud on missing slug field.
• Returned map keyed by slug: HashMap<String, WorldHandle>.

src/mcp.rs

• McpEnv.worlds: Arc<RwLock<HashMap<Uuid, WorldHandle>>> -> Arc<RwLock<HashMap<String, WorldHandle>>>. Keyed by slug.
• McpEnv.tombstones -> keyed by slug.
• McpEnv::resolve(world_id: Uuid) -> McpEnv::resolve(slug: &str).
• require_world_id(args) is renamed to require_world_slug(args) and returns Result<String, McpError>. Validates slug grammar via slug::validate; returns BAD_SLUG on grammar violation.
• Every world-touching handler updates its require call: get_world, list_turns, get_turn, diff_turns, get_state_at, get_entity, entity_history, get_events, run_turn, get_turn_status, list_attempts, delete_world.
• handle_create_world:
  • Extract slug from args. Required. MISSING_ARG if absent, BAD_ARG if non-string, BAD_SLUG if grammar violation.
  • Under the write lock on env.worlds: check contains_key(slug) before insert. On hit, release lock and return SLUG_COLLISION. On miss, call worlds::create_world and insert the returned handle.
  • name stays an optional display label (unchanged semantics).
• handle_delete_world: target by slug.
• handle_list_worlds: response includes slug in each row.
• Tool manifest descriptions: every mention of "UUID of the world" becomes "slug of the world; see docs/terms.md for the grammar." JSON schema world_id/world_slug field gains "description": "slug, e.g. 'ant-smoke'".
• McpError::unknown_world(world_id: Uuid) -> McpError::unknown_world(slug: &str). Error code stays UNKNOWN_WORLD.
• New error codes: BAD_SLUG, SLUG_COLLISION.

src/persistence.rs

• log_perception, log_intent, log_adjudication, log_adjudication_rejected, log_turn_complete, log_attempt_failed: every world_id: Uuid parameter becomes world_slug: &str.
• On-disk JSON shape: same field name, slug-valued string instead of UUID-valued string. See the open knob below on whether to also rename the JSON field.

src/turn_job.rs

• Any world_id: Uuid on attempt records becomes world_slug: String.

src/server.rs

• AppState.worlds keyed by slug. Same for tombstones.
• Dashboard handler constructs WorldRow with slug.

src/html.rs

• WorldRow.world_id: Uuid -> WorldRow.slug: String.
• Dashboard renders the slug instead of the UUID.

tests/phase0.rs and tests/ant_scenario.rs

• Every Scenario::AntOnPlate.seed(now) call supplies a test-local slug (e.g. "phase0-time-test", "ant-events-test").
• Every worlds::create_world(...) gains a slug arg.
• Asserts on world.world_id become asserts on world.slug.

docs/terms.md

• New section: "World slug — grammar, uniqueness, lifetime."
• Remove all language that refers to world_id as a UUID.

================================================================ WHAT DOES NOT CHANGE

• attempt_id stays Uuid (server-generated, not operator-named)
• ticket_id stays Uuid (same reason)
• entity_id stays the semantic string from the prior ticket — untouched
• turn_ref stays turn_NNNNNN, derived from the turn number
• OAuth flow untouched
• code_nav untouched (no world state)
• No UI work lands in this ticket

================================================================ MIGRATION

Production registry is empty (list_worlds returned 0 earlier this session). No live worlds on disk. No migration path is built.

If any world happens to exist on disk at deploy time, it will fail to load: WorldMeta::read rejects meta.json without a slug field, and load_all skips directories whose names don't parse as slugs (UUIDs happen to be valid slug-shaped strings by grammar, so the directory name check passes — the meta.json check is what fails). The fix is manual: add a slug field to each meta.json, rename the directory to match. No fallback code path is added.

================================================================ IMPLEMENTATION ORDER

Bottom-up, each step compiles before the next:

1. src/slug.rs + unit tests
2. src/kernel.rs, src/scenarios.rs (World, Scenario::seed signatures)
3. src/worlds.rs (WorldMeta, registry keys, create/delete/load)
4. src/persistence.rs + src/turn_job.rs (audit fields, attempt records)
5. src/mcp.rs (McpEnv, require_*, every world-touching handler, tool manifest descriptions, new error codes)
6. src/server.rs + src/html.rs (AppState, dashboard)
7. tests (phase0, ant_scenario) — these will not compile until their scenario/create_world calls gain slugs; update alongside each preceding step as needed
8. docs/terms.md

================================================================ ACCEPTANCE

• cargo build clean
• cargo test green (including the live-router ant tests)
• rg -n 'world_id.*Uuid|Uuid.*world_id' src/ returns no matches in production code (comments referencing the prior contract are OK)
• rg -n 'pub fn.*world_id' src/ returns no matches (the parameter name is gone at every public API)
• Production smoke: create a fresh world with a slug, run a turn, read events, confirm the slug appears where world_id used to
• list_worlds response rows contain slug, not UUID

================================================================ OPEN KNOB

Should the MCP wire-level arg field AND the on-disk audit-event JSON field be renamed from world_id to world_slug, or stay as world_id with only the described value format changing?

RECOMMENDATION: rename to world_slug at both layers. It is a breaking MCP contract change, but the registry is empty and the renamed field is unambiguously correct — a client seeing world_slug will supply a slug-shaped value; a client seeing world_id might still reach for a UUID and hit BAD_SLUG errors.

Alternative: keep world_id as the wire/on-disk name with updated descriptions. Less churn, more legacy baggage.

The ticket body assumes RENAME unless the caller overrides.

Implemented end-to-end, committed, deployed, and smoke-tested in production.

New module src/slug.rs:

• Strict grammar: 1..=64 chars, [a-z0-9] at both ends, [a-z0-9_-] in middle. No uppercase, no dots, no whitespace, no other punctuation. Single-char slugs are their own first and last.
• validate(&str) -> Result<&str, SlugError>. No normalize function — string as typed is valid or rejected.
• SlugError variants: Empty, TooLong, InvalidChar, LeadingHyphen, TrailingHyphen, LeadingUnderscore, TrailingUnderscore.
• 14 unit tests covering every accept/reject case in the spec table. Edge-order note: the checks emit InvalidChar for an out-of-alphabet character (e.g. 'A' or '.') and LeadingHyphen/TrailingHyphen/LeadingUnderscore/TrailingUnderscore only for valid-alphabet chars at wrong edges.

Identifier retirement at every layer:

• kernel: World.world_id: Uuid → World.slug: String. Required, no serde default. World::new / World::with_environment take slug first.
• scenarios: Scenario::seed(slug, now). Seeds pass slug through; they do not validate (validation is the create_world boundary).
• worlds: WorldMeta.slug, DeletedWorldRecord.slug. world_dir(&Path, &str). create_world validates slug before disk/registry work; dir-exists collision stays. load_all skips directories whose names fail slug::validate. Registry returns HashMap<String, WorldHandle>.
• mcp: McpEnv.worlds and .tombstones keyed by String. require_world_slug(args) validates via slug::validate and returns BAD_SLUG on grammar violation. handle_create_world takes slug arg, does a contains_key check + insert under one write-lock scope, returns SLUG_COLLISION on duplicate. New error codes BAD_SLUG and SLUG_COLLISION; UNKNOWN_WORLD unchanged. Manifest descriptions updated from "UUID of the world" to "slug of the world."
• persistence: every audit log signature changed from world_id: Uuid to world_slug: &str. Events.jsonl field renamed "world_id" → "world_slug". No alias, no fallback.
• server + html: AppState keyed by String. WorldRow.slug. Dashboard renders slug.
• minds: render_world emits world_slug: to the adjudication prompt.
• tickets: Ticket.world_context: Option → Option. Judgment call per rule 2 (no legacy baggage) — world_context is a world reference. Verified all 7 live tickets on the pod have world_context: null, so no data-side fallout.

What didn't change (per spec): attempt_id stays Uuid, ticket_id stays Uuid, entity_id stays semantic string, turn_ref stays turn_NNNNNN, OAuth and code_nav untouched.

Docs: new "World slug — grammar, uniqueness, lifetime" section in docs/terms.md including the grammar table, uniqueness semantics, lifetime-and-immutability discussion, and an explicit rationale for why slugs don't normalize while entity_ids do (different callers: operators vs. LLMs; different policies).

Receipts — source verification:

• Commit: df9d8ce on main ("refactor: retire World UUID, use slug as the only world identifier"). Commitlint green (no emails, no Co-Authored-By).
• cargo build: clean.
• cargo test --lib: 240 passed (up from 223 — new slug/worlds/mcp tests).
• cargo test --test phase0: 14 passed.
• cargo test --test ant_scenario: 3 passed including both long-running live-router tests ant_memory_grows_monotonically and suspended_seed_remains_unchanged_after_many_turns (~234s total).
• cargo test slug::tests: 14 passed.
• rg -n 'world_id.*Uuid|Uuid.*world_id' src/: no matches.
• rg -n 'pub fn.*world_id\b' src/: no matches.
• rg -n '"world_id"' src/: no matches.
• rg -n '.world_id\b' src/: no matches.
• Surviving world_id mentions are load-bearing: docs/terms.md § design-rationale for the retirement, tests/phase0.rs negative assertion that world_id is absent from audit-event JSON.

Receipts — deploy + production smoke:

• k8s/deploy.sh ran clean. Image chukwa:latest rebuilt; new pod chukwa-5b544bfdb6-hrmz2 Running 1/1. Watcher reconnected automatically.
• GET https://chukwa.benac.dev/healthz → ok.
• GET /v1/tooling/manifest confirms new schemas: create_world requires ['scenario','slug']; get_world/delete_world require ['world_slug']; descriptions updated.
• End-to-end MCP smoke:
  • create_world(scenario=ant_on_plate, slug=smoke-1, name="slug smoke test") → returns world_slug: "smoke-1", turn 0.
  • run_turn(world_slug=smoke-1) → attempt_id bdcd66da-8e64-46de-84fb-d2f676f528f6 enqueued; poll_with correctly echoes {tool: get_turn_status, args: {world_slug, attempt_id}}.
  • get_turn_status(world_slug=smoke-1, attempt_id=…) → committed turn 1 in 24.3s; delta {turn_before: 0, turn_after: 1, entities_touched: ["ant"], events_emitted: 4}.
  • get_events(world_slug=smoke-1) → 4 events in order perception_emitted → intent_formed → intent_adjudicated → turn_complete. Every event's JSON carries "world_slug": "smoke-1"; no "world_id" field anywhere in the response. Entity refs use semantic id "ant" (from the prior ticket).
  • delete_world(world_slug=smoke-1) → clean teardown; list_worlds returns 0 immediately after.

Acceptance checklist vs spec:

• cargo build clean ✓
• cargo test green including live-router ant tests ✓
• rg 'world_id.*Uuid|Uuid.*world_id' src/ returns no matches ✓
• rg 'pub fn.*world_id' src/ returns no matches ✓
• Production smoke: fresh slug-named world, run a turn, read events, slug appears where world_id used to ✓
• list_worlds rows contain slug not UUID ✓ (confirmed via the create_world response shape; registry empty now)

Known non-issue worth flagging: Claude Code's ToolSearch may still show cached MCP tool schemas (old world_id arg) until it re-negotiates with the server. Actual tool invocations pass through — the old tool_id worked with the new required slug arg, and required world_slug arg, proving the server is the source of truth.

Per standing guidance I am not confirming this ticket — only proposing. Over to you. The follow-up read-only /w/:slug/... web UI ticket is now unblocked whenever you want to file it.