Input declarations: enum as a first-class type, and where must: stops being enough
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 9
- Forks
- 0
- Avg merge
- 3h 3m
- Merged PRs (30d)
- 509
Description
Owner review feedback on the input-declaration surface (#177 slice 1 shipped type, required, example, sensitive, must).
The observation
environment:
type: string
required: true
example: production
must: 'this in ["staging", "production"]'
A closed set of values is a type, not a constraint. Spelling it as a must: works but loses everything a type would give: the LSP cannot offer staging/production as completions, flow run --input environment=prod cannot say "not one of the two values" in the vocabulary of the declaration, docs generation cannot render the choices, and a future schedule or call: binding cannot validate statically against the set. First-class spelling to explore:
environment:
type: enum
values: [staging, production]
required: true
Proto-first: this is a schema decision on InputDeclaration (additive field), and the choices become descriptor data every surface reads (validator, LSP, flow run coercion, docs, MCP). The must: spelling keeps working; flow fix could offer the rewrite when the constraint matches the recognizable shape.
The larger question behind it
must: today evaluates one expression against this. The feedback asks where that stops: constraints that need another input's value (an environment/region compatibility matrix), constraints over vars:, cross-references to types declared elsewhere (#177's user-declared types). Each widens the evaluation scope, and scope is exactly where the constraint surface can go wrong in both directions: too narrow and authors hand-roll validation in step if: clauses where failures arrive mid-run; too wide and a "declaration" quietly becomes a program that runs at submit time against state the declaration reader cannot see.
A deliberate ladder to design against, rather than growing case by case:
thisonly (shipped).- All declared inputs (
inputs.*in scope; enables cross-field checks at bind time; still pure, still submit-time). - Declared types from #177 as named, reusable constraint sets.
- Beyond that (vars, steps): probably a refusal with a diagnostic naming where that logic belongs.
Related: #177 (typed workflows), #326 (one language, small substrate; an enum type is YAML-as-data, the compatibility matrix is CEL-as-logic, and this issue is where that boundary gets drawn for declarations).
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 by locating the proto/schema definition for InputDeclaration and tracing how descriptor data reaches the validator, LSP, flow run coercion, docs generation, and MCP. Define the additive enum representation and decide the supported constraint-scope ladder, including diagnostics for unsupported references. Done means the schema decision and affected-surface behavior are specified clearly enough for implementation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, yaml
- Domain
- api, documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100