proto: API conventions before stability — no `OUTPUT_ONLY` or `IMMUTABLE` anywhere, seven files with no field behavior at all, verbs without a resource noun, and `_time` beside `_at`
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 9
- Forks
- 0
- Avg merge
- 3h 3m
- Merged PRs (30d)
- 509
Description
Observed behavior
At eb8172f, across proto/flowstate/:
grep -rn 'OUTPUT_ONLY\|IMMUTABLE\|INPUT_ONLY\|IDENTIFIER' proto/returns nothing. OnlyREQUIREDandOPTIONALare used, in 8 of 16 files. Server-populated fields (RunResponse.workflow_idatservice.proto:172,GetResponse.starter, all ofRunSummaryatservice.proto:756-828) are indistinguishable in the descriptors from caller inputs. The MCP tool schemas are derived from these descriptors (cmd/flow/internal/mcp/schema.go), so an agent is offered read-only fields as arguments.audit.proto,authorization.proto,catalog.proto,debug.proto,diagnostics.proto,identity.proto,reports.protocarry zerogoogle.api.field_behaviorannotations.identity.proto:103(namespace, the field every tenant decision turns on) has none.- Message-level CEL rules exist in two files (
audit.proto:129-139,workflow.proto:752-757,1087-1092). Elsewhere cross-field invariants live in Go:service.proto:36-43says ofRunRequest.inputsthat "the oneof cannot say which arm is allowed ... so the server enforces it at submit", which a(buf.validate.field).celrule on the map value can say, so a non-Go client reads a contract the descriptor under-states. catalog.protohas 44 fields and no validation rule, andPluginCatalogis populated from a plugin'sDescribe(plugin.proto:317), a less-trusted peer.- Verbs:
Run,Get,List,Signal,Cancel,Terminatename no resource;CreateSchedule,ListSchedulesdo.GetandListcollide the day a second resource is listable (#1470's inventory is that day). - Timestamps:
start_time/close_timeon runs (service.proto:762,765),start_at/end_aton triggers and backfills (trigger.proto:629,663-664).
None of these is wrong on its own. Together they are the set a first external client meets, and every one is cheaper to settle now than after a tag.
Desired outcome
One conventions pass, recorded as a short section in docs/ARCHITECTURE.md or proto/README.md and enforced by buf lint where a rule exists:
- Every field carries a behavior:
REQUIRED,OPTIONAL,OUTPUT_ONLY,IMMUTABLE, orIDENTIFIER; a custombuf lintplugin or a repo test fails a field with none, the way #1544 proposes for comments. - The MCP schema generator omits
OUTPUT_ONLYfields from tool inputs. - Cross-field rules that can be said in
buf.validateare said there and the Go check becomes the duplicate that is deleted. catalog.protobounds every plugin-supplied string.- Resource-noun verbs and one timestamp suffix, as a single rename with the CLI's projections regenerated.
Acceptance criteria
flowstate_run's input schema no longer offersworkflow_id.- A test enumerates every field in
proto/flowstate/v1and fails on one with no behavior annotation. buf breakingagainst the previous tag is either clean (the repo has no tag yet) or the renames are recorded as the deliberate break in the first release notes.
Constraints and dependencies
- Adjacent: #1544 (comments on every field), #1543 (MCP annotations), #1590 (policy as proto), #1571 (the signature descriptor), #518 (field masks), #1216 (release foundations).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the listed proto/flowstate files, cmd/flow/internal/mcp/schema.go, and the existing rules in audit.proto and workflow.proto. Map field behaviors, validation, resource verbs, and timestamp suffixes before changing conventions. Done means the architecture guidance is recorded, the MCP schema omits workflow_id, the field-enumeration test passes, and buf breaking or release notes address renames.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- api, backend-api-design
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 28/100