From 7087abffda9f20f59be23b1f956abb6650a05766 Mon Sep 17 00:00:00 2001 From: Preetam Dwivedi Date: Mon, 13 Jul 2026 19:06:53 -0700 Subject: [PATCH] docs(entity): entity docs describe data, not controller choreography MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary ### Why? Entity doc comments had started narrating pipeline choreography — which controller writes a field, which seams read it, which stage never touches it (e.g. "written only by the orchestrator's speculate controller … the seams never write it"). That is control-flow knowledge that belongs with the code that owns the behavior; restated on the entity it goes stale as the pipeline evolves and distracts from what the entity actually guarantees. ### What? Adds entity guideline 7 to CLAUDE.md: docs describe what a type or field *is* and its invariants (immutability, uniqueness scope, units, valid range) — never which controller/stage/seam reads or writes it; ownership and write-path rules live in controller/store/extension docs. Lifecycle enums may define states in terms of pipeline stages where that is the state's meaning, but must not name the components performing transitions. Also trims the one instance in the merged entity files this stack touches (`SpeculationPathBuild.Version`'s "version arithmetic is owned by the controller" clause — the convention is already documented in CLAUDE.md and the storage README). ## Test Plan Doc-only change. --- CLAUDE.md | 1 + submitqueue/entity/speculation_path_build.go | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index de042dd8..941840a8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -120,6 +120,7 @@ Domain objects live under each domain's `entity/` tree, or under `platform/base/ 4. Every field must have a comment 5. Reference other entities by ID (string or int), not directly 6. String enums with sentinel values (`""` for unknown) +7. Docs describe the data, not the choreography — say what a type or field *is* and its invariants (immutability, uniqueness scope, units, valid range), never which controller/stage/seam reads or writes it. Ownership and write-path rules live with the code that owns them (controller, store, or extension docs). Lifecycle enums may define states in terms of pipeline stages where that *is* the state's meaning (e.g. "admitted under the build budget"), but must not name the components that perform transitions. ### Extensions diff --git a/submitqueue/entity/speculation_path_build.go b/submitqueue/entity/speculation_path_build.go index 8cd39fcf..634b0159 100644 --- a/submitqueue/entity/speculation_path_build.go +++ b/submitqueue/entity/speculation_path_build.go @@ -33,7 +33,7 @@ type SpeculationPathBuild struct { CreatedAt int64 // Version is the version of the object. It is used for optimistic locking: // updates are conditional on the persisted version matching the caller's - // expected version. Versioning starts at 1; version arithmetic is owned by - // the controller, the store performs a pure conditional write. + // expected version. Versioning starts at 1 and is incremented for each + // change to the object. Version int32 }