Skip to content

Commit 112d263

Browse files
authored
docs(entity): entity docs describe data, not controller choreography (#350)
## 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. ## Issues ## Stack 1. @ #350 1. #351 1. #353
1 parent c92e4e3 commit 112d263

2 files changed

Lines changed: 3 additions & 2 deletions

File tree

CLAUDE.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ Domain objects live under each domain's `entity/` tree, or under `platform/base/
120120
4. Every field must have a comment
121121
5. Reference other entities by ID (string or int), not directly
122122
6. String enums with sentinel values (`""` for unknown)
123+
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.
123124

124125
### Extensions
125126

submitqueue/entity/speculation_path_build.go

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ type SpeculationPathBuild struct {
3333
CreatedAt int64
3434
// Version is the version of the object. It is used for optimistic locking:
3535
// updates are conditional on the persisted version matching the caller's
36-
// expected version. Versioning starts at 1; version arithmetic is owned by
37-
// the controller, the store performs a pure conditional write.
36+
// expected version. Versioning starts at 1 and is incremented for each
37+
// change to the object.
3838
Version int32
3939
}

0 commit comments

Comments
 (0)