picatz / picatz/flowstate

Input declarations: enum as a first-class type, and where must: stops being enough

Open
#332 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

design dsl enhancement kind/design-record
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:

  1. this only (shipped).
  2. All declared inputs (inputs.* in scope; enables cross-field checks at bind time; still pure, still submit-time).
  3. Declared types from #177 as named, reusable constraint sets.
  4. 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.