docs(arty): document panic handling

[martintmk]

Summary

• document JoinError outcomes for task panics and runtime shutdown
• define first-panic shutdown and inherited critical-task behavior
• record the stable telemetry emitter surface now provided by observed

Validation

• just package=arty format
• just package=arty readme
• just package=arty spellcheck
• just package=arty clippy
• GitHub required checks passed
• Codecov project and patch coverage passed at 100%

Review

• completed independent Opus, Sonnet, and GPT review passes
• clarified that the runtime contracts are planned and who can inspect panic join errors during shutdown
• retained the requested observer_core provenance statement; automation reviewers could not verify it from this repository history

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (efd8178) to head (91d6979).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #741   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         583      583           
  Lines       62930    62930           
=======================================
  Hits        62930    62930           

Flag	Coverage Δ
linux	?
linux-arm	?
scheduled	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[martintmk]

Posted by an AI agent

Reviewed the exact PR head across API design, correctness, tests, performance, naming, telemetry, resilience, consistency, public API, and public documentation. I found two blocking issues and one non-blocking documentation issue, all anchored inline.

Focused validation: cargo check -p arty passed. The paired cargo public-api and rustdoc comparisons found no public Rust API or rustdoc changes.

[martintmk]

Posted by an AI agent

The panic policy presents planned runtime behavior as a current guarantee

Problem
PANICS.md now says every spawned task returns JoinError, the first panic starts shutdown, and criticality is inherited; DESIGN.md states the same behavior in the present tense. At this head, arty still exposes only thread-awareness and optional time re-exports, with no spawn API, JoinError, critical-task API, or observed dependency, while STABILIZATION.md explicitly calls the runtime surface planned.

Why this matters
These policy pages are linked from the published crate documentation, so consumers can read fail-fast shutdown, join-error classification, and critical-task completion as guarantees of the current crate even though none of those APIs or behaviors is available.

Suggested fix
Mark the new task, panic, and shutdown sections explicitly as planned design until the corresponding runtime surface is implemented and tested; keep the existing current unwind-safety requirements separate.

[martintmk]

Posted by an AI agent

Inherited critical tasks can prevent fail-fast shutdown from completing

Problem
The design says every descendant spawned from a critical task is also critical and that all critical tasks run until they finish, but it defines neither a way to spawn ordinary work from that context nor a bounded drain deadline. A critical operation that calls code spawning unrelated or never-ready work can therefore make the entire descendant tree exempt from shutdown indefinitely.

Why this matters
The first panic is supposed to trigger fail-fast shutdown, yet one detached or stalled descendant can turn that path into a permanent hang and prevent telemetry flushing or other high-value cleanup from completing.

Suggested fix
Define a bounded critical-drain phase and an explicit spawn escape hatch that clears inherited criticality for unrelated work. Specify the terminal outcome for critical tasks and join handles when the drain deadline expires.

[martintmk]

Posted by an AI agent · Non-blocking

observer_core names a nonexistent predecessor for the telemetry API

Problem
The stabilization note says the Sink/emit! surface previously lived in observer_core, but repository history identifies the predecessor as the emit crate family (including Emitter being renamed to Sink); no observer_core crate or path exists in the relevant history.

Why this matters
This note is intended to identify the compatibility lineage maintainers must preserve, so the incorrect name sends readers to the wrong contract and obscures the actual rename history.

Suggested fix
Replace the provenance sentence with the established emit → observed and Emitter → Sink lineage, or omit the historical claim.