# naming Specs

> Canonical path: `specs/naming/README.md`

Internal identifiers should use the most precise domain term available. For
example, use scope, panel, resolved, deterministic, managed, primary,
authoritative, acked, slots, or delivery when that is the actual concept
instead of using `surface` or `canonical` as a generic placeholder.

The words `surface` and `canonical` are not forbidden. Keep them when they are
the accurate technical term, including UI/rendering surfaces and genuine
canonicalization or canonical forms. The goal is semantic clarity, not a zero
token count.

Existing client, runtime, wire, and persisted protocols remain stable. When an
old literal contains `surface` or `canonical`, internal code may isolate it
behind an adapter or explicit tag. New semantic spellings may be accepted on
reads for prerelease compatibility, but writers continue to emit the frozen
protocol.

The naming guardrail therefore checks only identifier families whose ambiguous
meaning and replacement were explicitly reviewed. It must not grow into a
blanket lexical ban or require allowlisting every legitimate use.