← 1.0.0 scope SAPE-9

Name collision: operation names get a namespace — the decision, and what it costs

Status
In progress
Component
server
Priority
High — unrecoverable after the tag either way
Blocked by
—
Blocks
—
Decided
2026-09-21 — namespaces

The decision

Operation names are namespaced. The dossier that follows recommended the opposite — flat names, with the decision spent instead on recording who declared what. The owner chose namespaces. That is the answer, and the rest of this page is now the record of how the question was argued rather than an open question.

The shape, settled so that nothing about it has to be asked again:

Why it could not be left for 1.1

This is the part that turned a preference into a deadline. internal/store/collision_test.go holds TestAnOperationNameMayHoldAnySeparatorAName, which measures that every separator a convention might pick is already a legal operation name — orders/recent, @acme/orders.recent and acme:orders.recent all declare successfully today. COMPATIBILITY.md section 3 forbids tightening a rule inside 1.x.

Put those two together: a 1.1 that refused a:b:c, or that reinterpreted the colon in a name somebody had already declared, would be breaking a promise 1.0.0 made. A namespace that misses the tag can never be added at all. That test was written to record a curiosity about how loose the name rule was. It turned out to be the clock.

Description

Decide whether operation names are namespaced, and write the decision down with its reasoning. There are two answers and this ticket is done when one of them is chosen: namespaces exist, or names are flat forever and the collision behaviour is documented as intended. The decision has now been made; the ticket stays open until the behaviour it chose is in the code and under test.

Why now

Naming is the flat-out worst thing to leave undecided across a 1.0 boundary. Adding namespaces later changes what an existing name means, and every operation anybody declared is addressed by one. Deciding "no namespaces" later is equally impossible if somebody has already been given a way to write a qualified name. Both doors close at the tag; this ticket picks which one closes.

Measured 2026-09-20. There is no namespace. Searching every .go file for namespace finds two hits, both in sapedb_test.go (lines 32 and 34) and both about Go's own package scope, not about operation names. The collision behaviour is in internal/store/ops.go:367, DeclareOperation: operation.Version = 1, then if found { operation.Version = latest.Version + 1 }. Declaring a name that already exists does not fail and does not warn — it creates version N+1 of the existing name, keeps the older versions, and returns success. Two unrelated authors choosing orders.list produce one operation with two versions, and the second author's declaration silently becomes the one Invoke reaches, because Invoke takes the newest.

The sharpest form of that measurement, from the dossier: the first author's application did not change one line. It called the name it was given, with the argument it was given, and deleted a document — because the second declaration of that name was a delete where the first had been a get. Nothing about a redeclaration has to resemble what it declares over: not the action, not the collection, not the declared scopes.

pipelines/tasks/0071 adds a reason this decision cannot wait for the external-operations group to land first: the recommended v1 shape for an external operation is an OperationBundle — one or more store.Operations declared under a signature — and every operation inside a bundle is still just a name in the same flat table DeclareOperation already writes to. A stranger's bundle and a name already declared on the target server collide exactly the way two unrelated authors do in the blockquote above, silently, by this ticket's own measurement — there is nothing about "external" that changes the collision rule. Whichever way this ticket decides, that decision is what an OperationBundle author has to be told before they publish one.

Acceptance criteria

  1. Done. A written decision exists, naming which of the two answers was chosen and why. A ticket closed with neither answer written down is not closed.
  2. The behaviour in the blockquote is covered by a test that asserts it deliberately, whichever way the decision goes — so the current silent-versioning is either proved intentional or proved changed.
  3. Not applicable: the decision was namespaces. If the decision is "no namespaces": the flat-name rule and the collision consequence are on the documentation page that tells people how to name an operation, in the place they read before choosing a name rather than after.
  4. The decision is "namespaces": every existing unqualified name still resolves, proved by declaring an operation the old way and invoking it by its old name. The migration for zero deployed databases is free, and the test is what proves it stayed free.
  5. The decision is cited from SAPE-2's policy document under declaration semantics, since that is the surface it freezes. The name grammar joins the frozen list.
  6. The collision scenario can no longer happen between two authors who each use their own namespace, proved by exercising DeclareOperation — not by comparing name strings.

Out of scope