picatz / picatz/flowstate

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`

Open
#1,663 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design engine kind/decision
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. Only REQUIRED and OPTIONAL are used, in 8 of 16 files. Server-populated fields (RunResponse.workflow_id at service.proto:172, GetResponse.starter, all of RunSummary at service.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.proto carry zero google.api.field_behavior annotations. 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-43 says of RunRequest.inputs that "the oneof cannot say which arm is allowed ... so the server enforces it at submit", which a (buf.validate.field).cel rule on the map value can say, so a non-Go client reads a contract the descriptor under-states.
  • catalog.proto has 44 fields and no validation rule, and PluginCatalog is populated from a plugin's Describe (plugin.proto:317), a less-trusted peer.
  • Verbs: Run, Get, List, Signal, Cancel, Terminate name no resource; CreateSchedule, ListSchedules do. Get and List collide the day a second resource is listable (#1470's inventory is that day).
  • Timestamps: start_time/close_time on runs (service.proto:762,765), start_at/end_at on 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, or IDENTIFIER; a custom buf lint plugin or a repo test fails a field with none, the way #1544 proposes for comments.
  • The MCP schema generator omits OUTPUT_ONLY fields from tool inputs.
  • Cross-field rules that can be said in buf.validate are said there and the Go check becomes the duplicate that is deleted.
  • catalog.proto bounds 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 offers workflow_id.
  • A test enumerates every field in proto/flowstate/v1 and fails on one with no behavior annotation.
  • buf breaking against 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.