ADR#0040: Contract Field Vocabulary: Identifiers, Handles, and Display Labels
Context
One concept keeps recurring across domains: a human-facing label with no enforced semantics. Today it is spelled three different ways.
The agents contract calls it name. AgentProvisioned.name carries it, and the retired value object behind it validated only that the string was non-blank: no syntax rule, no uniqueness rule. The one place uniqueness was even mentioned was an assumed upstream precondition noted in a since-deleted command comment, never a domain invariant, and a per-stream decider cannot enforce cross-stream uniqueness anyway.
The sessions contract, the decider aggregate ADR#0035 establishes, calls the same kind of concept title. SessionRenamed.title is documented as "the session's display title": the same mutable label, spelled differently because it lives in a different domain.
ADR#0025's example data spells it a third way again, display_name, but as a key inside the annotations bag rather than as a field of its own: a stringly-typed convention that carries the right name but the wrong structure.
Meanwhile name also appears where it is legitimate. ToolUseBlock.name and ToolCallRequested.name are tool handles: keys the tool catalog actually resolves to a tool definition. Those two fields are not the ambiguity; they are why the ambiguity is dangerous. A reader cannot tell, from the word name alone, whether a given occurrence resolves to anything.
The platform's recorded stance is explicit over implicit. The genesis AgentProvisioned.revision field is recorded explicitly, "so no consumer derives it from convention," for exactly this reason: nothing is left to a reader's inference when a contract can say it directly. A field called name that nothing resolves makes an implicit promise that nothing keeps. Left unpinned, each new domain re-invents the choice on its own, and the drift compounds: three spellings today become four, five, and six as the next domain faces the same field and guesses again.
Everything this decision touches is greenfield. Nothing described here is deployed. A breaking rename costs once, now; a permanent vocabulary exception costs every future reader, forever.
Decision
1. The two-question test
Apply this test to any string field on a platform-owned record whose purpose is to name or refer to something. Opaque and derived data, digests, serialized payloads, and free-form content (content_digest, input_json) name nothing; they are outside the test's scope and keep their descriptive spellings.
- Q1: Does any mechanism resolve this value? If nothing looks the value up, joins on it, or treats it as a key into a catalog, the value is a display label. Spell it
display_name. Stop here. - Q2 (only if Q1 is yes): Does the value denote the same referent forever, or whatever is currently bound to it?
- Rigid, opaque, and minted once at creation: the value is an identifier. Spell it
id, nested inside its own record, or<record>_idwhen referenced flatly. - Legible, registry-owned, late-bound, and rebindable to a different referent over time: the value is a handle. Spell it
name.
- Rigid, opaque, and minted once at creation: the value is an identifier. Spell it
2. Spelling rules
The test above compiles to a small set of spelling rules:
- A record's own identity is
id, nested inside that record, or<record>_idwhen referenced flatly. It never changes after creation. - A reference to another entity by identity is
<referent>_id.parent_tool_use_idandtool_execution_idalready comply. - Placement keeps its pre-existing spelling rule and is a recorded exception to the bullet above: bare
parentmeans a placement node ref, and kinship is alwaysparent<Type>Id, per the agent-platform decision record and the comment quoted on the field itself. A reader applying<referent>_idmechanically toparentwould be undoing a deliberate convention, not fixing an oversight. - A reference to another entity by handle is
<referent>_name. - A record's own display label is
display_name. It is always an explicit field, never a key inside anannotationsmap or any other opaque bag. This revises the illustrative placement in ADR#0025's example data, which putdisplay_nameinsideannotations; that placement predates this decision and is superseded by it, consistent with the explicit-over-implicit stance recorded above.
3. Bare name is reserved
Bare name is not available for a display label under any circumstance. Only a record that is itself the named entry in a registry that resolves and enforces the handle may carry bare name. A label that nothing resolves may not be called name, no matter how convenient the word feels in the moment.
4. Wire-fidelity exemption
A message whose entire purpose is to mirror an external protocol verbatim keeps that protocol's vocabulary, even where it would otherwise fail the test above. ToolUseBlock mirrors the provider's emitted tool-use block exactly, {id, name, input}, because faithful provider replay requires reproducing what the provider actually sent, not a platform-preferred respelling of it. ToolUseBlock.name therefore keeps name. The same exemption covers any future record whose job is to mirror a provider or external protocol rather than to express the platform's own contract.
5. Authorized greenfield renames
Applying this decision authorizes the following renames:
AgentProvisioned.namebecomesAgentProvisioned.display_name. Nothing resolves it; it is a label, not a handle.SessionRenamed.titlebecomesSessionRenamed.display_name. It is the same concept as the field above, under its third spelling; the field isv1alpha1and undeployed, so the rename costs nothing beyond this pass.ToolCallRequested.namebecomesToolCallRequested.tool_name. It is a platform-owned execution record referencing a tool by handle, so it takes the<referent>_namespelling from rule 2.
Tool invocation stays addressed by handle deliberately. tool_name must not become an id: late binding to whatever the catalog currently resolves for that name is the intended semantics, not an accident this ADR should close.
6. Addressable agent names are deliberately absent
This decision does not give an agent a resolvable handle. Making the agent's label a real, resolved handle would require a reservation mechanism, and a per-stream decider cannot provide uniqueness across streams on its own; that is its own future decision with its own machinery, not a side effect of a vocabulary fix. This ADR names that trigger and leaves it unpulled. Agent identity remains agent_id, self-certifying per ADR#0036.
Consequences
- One greppable spelling exists per concept across every future domain. Choosing a field name becomes a decision-tree lookup, not a taste call.
- The word
nameregains teeth. Seeing it on a platform-owned record now means a registry resolves it; it is no longer a coin flip between handle and label. - The rename cost above is paid exactly once, before deployment. The alternative was carrying a permanent vocabulary exception in every future reader of
AgentProvisioned,SessionRenamed, andToolCallRequested. - Wire-fidelity records such as
ToolUseBlockare a recorded, deliberate boundary rather than an unexplained inconsistency; a future reader can tell the two apart on sight.
