# 0057 — The serving registry is the primitive; served names are stable and disambiguated

Status: accepted (2026-09-06 WEBSERVE grill round 1, releases#272 / #248)

## Context

#248 offered two ways for a node to expose files: a dedicated served FOLDER per adapter or
entity (drop a file in, it is served — zero steps, serves everything in it), or a core
REGISTRY of individual entries added deliberately (`spt serve add <path>`, attachments
auto-registering on send). Files from different directories can share a filename, so whichever
primitive wins needs a rule for two `report.md`s.

## Decision

**The registry is the primitive.** A served folder is not a second mechanism: it is a registry
entry of type *dir*, declared by an adapter in its manifest, so one enumerable list always
answers "what is this node exposing" — an audit is one command (or one index page).

**Served names are stable and disambiguated by suffix.** When an entry's bare name
`<stem>.<ext>` is already taken on this node, the new entry is served as `<stem>~<n>.<ext>`
(the suffix sits before the extension so the file still opens as its type). Rules:

- the first registrant keeps the bare name; `n` increments per `(stem, ext)`;
- the assignment is persisted on the entry, so an entry's URL never changes for its life;
- a freed name is never reused — a stale link answers *not found*, it never silently opens a
  different file;
- re-registering the same absolute path returns the existing entry, not a new suffix;
- a registrant may name the entry explicitly (`--as <name>`), subject to the same rule;
- disambiguation is per node — across nodes the URL's node prefix (ADR-0056) already separates
  names.

## Alternatives rejected

- **Folders as the primitive.** Zero-step, but exposure becomes a property of where a file
  happens to sit, and "what am I serving" has no single answer. Rejected: exposure must be a
  deliberate act with an enumerable record.
- **Content-hash paths as the canonical name.** Collision-proof, but unreadable in a chat line
  and unstable across an edit of a reference-served file. Kept out; a hash can be a secondary
  alias later without changing this decision.
- **Reusing freed names.** Shorter names over time, at the cost of a link that can change
  meaning. Rejected on the same ground as the URL grammar: a link must not lie.

## Consequences

- `spt serve list` (and the node index page) is the audit surface; agents read the URL from it
  rather than guessing a name.
- Attachments (ADR-0058) are registry entries, so message links inherit the same stability.
- The registry needs a persisted counter per `(stem, ext)`; that is the one piece of state the
  stability promise costs.