spec: a step's failure is part of the model — retry, onError and {error} - #54
Open
iliyan-velichkov wants to merge 1 commit into
Open
spec: a step's failure is part of the model — retry, onError and {error}#54iliyan-velichkov wants to merge 1 commit into
iliyan-velichkov wants to merge 1 commit into
Conversation
Mirrors the specification proposal: retry: { count, every } and
onError: <step | end> on the two service-task shapes whose work is a call - a
delegate: handler and a non-fan-out notify: send - with the whole-value {error}
placeholder recording the final attempt's message on the record.
The send is the case that motivates it: the spec already says a sending process
step SHOULD fail the activity, since the message is that step's whole purpose,
and then offers nothing to handle it - so the failure becomes an incident against
the job and a document that was issued correctly sits in Issued for ever when a
mail server blinks, with no error message and no failure status.
Both normative notes carry the refusals: a setter step, a call: or bare step, a
fan-out send (fail-soft per row, so neither key could ever fire - observed with
outcome: and onNotifyFailed instead), and any other step kind.
The reference index gains its row and a snippet. Anchors verified against the
built HTML - VitePress drops the apostrophe in "step's", so the cross-link is
#retry-onerror-a-steps-failure-is-part-of-the-model.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The site half of IntentFile/intent-specification#71. Merge after that one.
Why
A process step that calls out fails sometimes, and the format has nothing to say about it. Everything else about a flow is modelled; what happens when the work of a step does not succeed is left entirely to the platform's defaults, so the model describes the application fully right up to the first failure and then stops.
The send is the sharpest case, because the spec already prescribes the failure — "a sending process step SHOULD [fail the activity], since the message is that step's whole purpose" — and then offers no way to handle it. The failure becomes an incident against the job, so a document that was issued correctly sits in
Issuedfor ever when a mail server is briefly unreachable, with no error message and no failure status. Not visibly wrong; invisibly stalled. The workaround is to make the send the last step, which constrains process design for a reason unrelated to the domain.What changed
docs/spec/processes.md— a new retry / onError section under Service tasks, with the two keys, the{error}placeholder, an example carrying both adelegate:and anotify:step, and two::: info Normativecontainers. The first is the shape rule and its refusals: asetField/setRelationFieldstep (a status write is refused by the model's own gates, and a gated one is refused to the person who acted — routing that away would take the refusal out of their hands), acall:or bare service task, a fan-out send (the spec already says a fan-out must not fail its activity, so neither key could ever fire — its deliveries are observed withoutcome:andonNotifyFailed), and any step kind other thanserviceTask. The second covers commit semantics, byte-identical output when neither key is declared, and the rule that the{error}message must name the cause and not only the step — it is the only account of the failure the record will carry.docs/reference.md— the index row and a snippet underprocesses.npm run docs:buildis clean. The anchor was taken from the built HTML rather than the heading: VitePress drops the apostrophe in "step's", so the cross-link is#retry-onerror-a-steps-failure-is-part-of-the-model.