ADR#0068: A Reference Field Says It Is a Reference in Both Its Name and Its Type
Context
Fields across proto/trogonai that point at something stored or owned elsewhere are spelled inconsistently. ArtifactRef artifact_ref stutters the word twice; SkillVersionRef version_ref and ModelVersionRef version_ref carry the referenced kind in the type and a generic version_ref in the field, which reads correctly only once the type is already known. Out-of-line stored bytes are worse: Checkpoint.capture_attestation_ref and ExecutionAttemptStarted.host_artifact_ref are bare string fields whose digest lives in a separate sibling field, so nothing in the schema ties the locator to what the referenced bytes must hash to. StoredArtifact.storage_ref and Cost.rate_ref are the same problem on a single field: an opaque string standing in for a location or an identifier a reader cannot otherwise recognize as one.
A JSON consumer of these events frequently has no access to the .proto schema, only the wire JSON. Reading "result": {...} on its own does not say whether result is the payload itself or a pointer to a payload stored elsewhere; the field has to say so by name, because the type is invisible at that layer. Naming a reference by role alone works for a hierarchy position such as parent, because a parent is never mistaken for inline content, but not for a kinship field such as ProjectId project_id, where a bare project would read as an embedded project. A field that could plausibly hold the thing itself, such as a result, a response, an attestation, or an attempt's artifact, does carry that risk, and needs the suffix.
proto/trogonai/session and proto/trogonai/workflows are excluded from Rust codegen in buf.gen.yaml, so no generated code or compiled caller exists yet for any of these fields. This is the cheapest the rename and the type changes will ever be.
Decision
A reference field's name ends in _ref (a structured reference to something else, carrying more than an opaque string) or _id (a single opaque identifier) exactly when the thing it names could otherwise be mistaken for inline content by a reader with no schema. The type backs up the name: a reference is a value object (ClaimCheck, StorageLocator, a *Ref message, a single-field *Id message), never a bare string.
ArtifactRef artifact_ref,ArtifactRef result_ref,ArtifactRef before_ref/after_ref,ArtifactRef response_ref: kept as is. The stutter is the name correctly declaring, independent of the type, that the field is a pointer to an artifact stored out of line.SkillVersionRef version_ref,ModelVersionRef version_ref: kept as is, for the same reason.- Out-of-line stored bytes referenced by a bare
stringplus a separate digest field become a singleClaimCheck(aStorageLocatorplus aDigest), keeping the_refname:Checkpoint.capture_attestation_ref,ExecutionAttemptReady.ready_attestation_ref,ExecutionAttemptStarted.host_artifact_ref. The separate digest field is retired; the name does not move, because it already said "reference." - An opaque location string becomes a
StorageLocatorvalue object, never a barestring:StoredArtifact.storage_ref. - An opaque identifier string becomes a single-field id message and takes the
_idsuffix that names it as such:Cost.rate_refbecomesCost.rate_id(PriceRateId), since nothing about a price rate needs the richerClaimCheckshape, only a stable opaque identifier. CheckoutReffields namedcheckout(CreateSession,ForkSession,RecoverSession,CreateChildSession,SessionStarted, the workflowRun) are renamed tocheckout_ref, for the same reason: a schema-less reader seeing"checkout": {...}cannot tell a bound reference from an inline checkout record.- Changing a field's type allocates a new field number and reserves the old one, so old bytes never decode as the new type. The old name is reserved too, unless the field keeps it at the new number. Reservations follow the existing style, for example
reserved 7; reserved resume_cursor;inexecution_attempt_started.proto.
Consequences
- A bare
stringfield naming a location, an identifier, or stored bytes elsewhere inproto/trogonai/sessionafter this ADR is a bug, not an accepted shorthand. buf breakingagainstmainreports the field removals, additions, and reserved ranges in every touched file. This is expected and accepted whileproto/trogonai/session,proto/trogonai/agents, andproto/trogonai/workflowsremain excluded from codegen; no compiled caller observes the break.- A reviewer reading a field name alone, with no type or schema in hand, can tell a reference from inline content:
_refor_idmeans elsewhere, anything else means here.parentand other bare hierarchy-position fields are the deliberate exception this ADR does not touch: see Hierarchy position is referenced by a bare parent field, which this ADR narrows rather than contradicts, since a hierarchy position is never itself the payload a reader might confuse it for. - Research and comparison documents and test fixtures that quote these proto names are updated to match; documents describing another product's own field keep that product's real name unchanged.
Alternatives Considered
Name every field by role alone, reference or not
Rejected. This reads cleanly once the schema is in hand, which is the case inside this repository's own Rust code, but a JSON consumer without the .proto on hand sees only "result": {...} and cannot tell a pointer from a payload. The suffix carries exactly the information the type cannot convey at that layer.
Suffix only the primitive strings, leave structured *Ref fields bare
Rejected. This still leaves the type doing all the work: a reader has to already know that ArtifactRef is a reference type to read artifact: ArtifactRef as a pointer rather than an embedded artifact. The name should not depend on the reader already knowing the type's shape.
