Adds chart patterns doc for resource verdicts - #218
Merged
Conversation
Adds docs/chart-patterns.md, an embedder-facing guide to the two canonical chart reactions when a host reports an external resource unavailable: park/retry (temporary - retry loop via <send delay>, with the retry budget and backoff visible as states in the document) and fail-fast (permanent - an explicit arrow to a failed final state). The verdict itself is the host's, delivered as events; the chart only routes on it, per the errors-are-events posture (ADR-0004, ADR-0051). The guide's example chart is runnable as written; a new test (test/statifier/chart_patterns_test.exs) pins both arms - budget exhaustion into the failed final state, and immediate fail-fast on the revoked-style verdict - so the doc cannot drift from engine behavior. README gains a pointer to the new guide. Refs: st-3twi
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
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.
Why
A chart that reaches an external resource has to route somewhere, explicitly, when the host reports that resource unavailable - a host's external connection or credential may be paused or revoked. The engine's posture (errors are events, no silent defaults) puts that decision in the document, but nothing embedder-facing showed the two canonical shapes. st-3twi asks for a patterns doc plus a runnable example pinning both.
What
docs/chart-patterns.md: an embedder-facing guide to the two reactions - park/retry for a temporarily unavailable resource (retry loop via<send delay>, with the retry budget and backoff visible as states in the document, not hidden in handler code) and fail-fast for a permanently unavailable one (explicit arrow to a failed final state). The guide is explicit that the temporary/permanent verdict is the HOST's, delivered as events (distinct names, or one event routed on payload withcond); the chart only routes. Cites the existing seams instead of re-arguing them:docs/extending.md/ADR-0051 forerror.executionvserror.communication,docs/durable-timers.md(ADR-0054/0059) for park delays that outlive the process, ADR-0004 for the errors-are-events posture.test/statifier/chart_patterns_test.exs: the guide's example chart, verbatim, driven throughStatifier.Testing.Casein both arms - three pauses exhaust the budget into thefailedfinal state; a revoked-style verdict fails fast fromrequesting- so the doc cannot drift from engine behavior.Notes
docs/extending.mdsection: Adds Invoke.Handler conformance case #216 (st-718j) adds an extending.md section on the same page region, and this content is chart-authoring guidance, not handler-writing guidance - the two compose with no textual overlap (this branch does not touchdocs/extending.md).Statifier.Session; enabled-set drop inStatifier.Interpreter.Selection.select_transitions/2), each run red and reverted green.mix qualitygreen (2,479 tests, 96.5% coverage) andmix quality --profile mergegreen; the ADR judge skipped cleanly (no files in a judged scope). Skips were not-applicable only (gettext).Closes: st-3twi