picatz / picatz/flowstate

server/cli: a terminal failure reports a kind and nothing about what remains recoverable — after `Expression`, `InvalidInput` or `PolicyDenied`, `flow get` says FAILED, every lifecycle verb says FailedPrecondition, and no surface says whether the completed prefix is safe to repeat

Open
#1,902 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cli design engine enhancement
Dominant language
Go
Stars
9
Forks
0
Avg merge
3h 3m
Merged PRs (30d)
509

Description

Written against b015dc6.

Observed behavior

The assessing pass forced three terminal failures under flow server dev: a division by zero, an invalid dynamic http URL, and denied loopback egress. flow get -o json returned STATUS_FAILED with Expression, InvalidInput and PolicyDenied respectively, exiting nonzero. For all three, cancel, terminate and signal returned FailedPrecondition: the workload had already finished.

The full classification (errors.go:143-160) divides as:

Kinds Attempt retry What an operator must consider afterwards
Upstream, Timeout, Internal, RateLimited retryable while policy permits exhausted attempts and prior effects
InvalidInput, UnknownTask, Expression permanent repair input, program or capability
PolicyDenied, LimitExceeded permanent resolve the refusal or the workload design
UpstreamUnknown permanent reconcile the external operation before repeating
RunTimeout permanent assess unfinished work and effects

For every row there is no shipped in-place retry, resume, rerun-from or manual undo. A new submission is possible, and the kind alone does not establish that repeating the completed prefix is safe: undo: ran for what it could, and nothing records which effects it did not reverse.

Desired outcome

A recovery account on the run, not another retry verb: after a terminal failure, flow get and GetTimeline report, per completed step, whether its effect stands, was compensated, or is unknown; which step failed and with what kind; and what a rerun from that step (#1587, #1754) would repeat. The account is derived from RunState and the attempt outcomes the model filed beside this records; it is the operator-facing projection of #1879's recovery contract.

Acceptance criteria

  • For each of the three forced failures, flow get prints a recovery section naming the failed step, the kind, the steps whose effects stand, and the compensations that ran.
  • A run that failed after an UpstreamUnknown step marks that step as unreconciled and flow rerun --from (once it exists) refuses to repeat it without an explicit flag.
  • DEPLOYMENT.md's recovery section (#1736) points at the account rather than describing the procedure in prose alone.

Constraints and dependencies

  • Adjacent: #1587, #1754, #1879, #1736, #1864, the attempt-outcome model.
  • Both drivers: the account is derived from RunState, which both drivers produce.

Open questions

  1. Is the account part of GetResponse or a separate RPC, given Get is already the largest read?

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 errors.go:143-160, the RunState and attempt-outcome model, and the existing Get and GetTimeline paths. Trace how both drivers produce RunState and determine whether the recovery account belongs in GetResponse or a separate RPC. Done means the three forced failures expose failed steps, effect and compensation status, and rerun guidance; update DEPLOYMENT.md to point to the account.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, backend, cli
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.