Skip to content

Adds chart patterns doc for resource verdicts - #218

Merged
johnnyt merged 1 commit into
mainfrom
st-3twi-verdict-patterns
Aug 22, 2026
Merged

Adds chart patterns doc for resource verdicts#218
johnnyt merged 1 commit into
mainfrom
st-3twi-verdict-patterns

Conversation

@johnnyt

@johnnyt johnnyt commented Aug 22, 2026

Copy link
Copy Markdown
Member

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 with cond); the chart only routes. Cites the existing seams instead of re-arguing them: docs/extending.md/ADR-0051 for error.execution vs error.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 through Statifier.Testing.Case in both arms - three pauses exhaust the budget into the failed final state; a revoked-style verdict fails fast from requesting - so the doc cannot drift from engine behavior.
  • README gains a pointer to the new guide alongside the extending/durable-timers/testing-charts entries.

Notes

  • Deliberately placed as a new doc rather than an docs/extending.md section: 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 touch docs/extending.md).
  • Both new tests carry verified sabotage notes (schedule-instruction drop in Statifier.Session; enabled-set drop in Statifier.Interpreter.Selection.select_transitions/2), each run red and reverted green.
  • Gate: full mix quality green (2,479 tests, 96.5% coverage) and mix quality --profile merge green; the ADR judge skipped cleanly (no files in a judged scope). Skips were not-applicable only (gettext).
  • No changelog fragment: docs and test harness only, no public-surface change.

Closes: st-3twi

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
@johnnyt
johnnyt merged commit 89ae56c into main Aug 22, 2026
1 check passed
@johnnyt
johnnyt deleted the st-3twi-verdict-patterns branch August 22, 2026 15:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant