[philocalyst]

Summary

With our new contracts and API methods in place, this is the first demo that proves why this is valid. Pretty smol

Documentation

Added a real Adapters guide.

• Adapter / BasicAdapter stay the default and stay deliberately result-free.
• FallibleAdapter and try_execute_query() are the opt-in for sources that can actually fail.
• Row-error policy belongs to the caller: surface it, skip that row, or stop at the first failure. The library shouldn't be picking.
• Do NOT reach for FallibleAdapter to model an infallible source. The direct traits make the common case smaller and easier to read, and that's the whole point of having two traits. If the guide doesn't land that, the two-trait design was a waste.

The live demo

demo-hytradboi moves to FallibleDemoAdapter. Its Hacker News starting edges hit the network, and until now a failed request got printed to stderr and silently dropped mid-query, you get a short result set with no indication that anything went wrong, too bad. With this new future on the way, you see real Result rows to make decisions on.

The pure resolver logic stays on DemoAdapter. Only the boundary that can actually fail moves, which is exactly the migration the guide describes. (yay consistency)

Migration

None for library users. Documentation and a demo binary.

Stack

Depends on #977, which introduces FallibleAdapter and try_execute_query().

1. Execute synchronous queries on a stream kernel #976 — stream execution kernel
2. Make adapter errors first-class #977 — first-class adapter errors
3. YOU HERE — fallible adapter docs and demo
4. Give each failed row its own error #979 — row-ordered error propagation
5. Expose the stream kernel as a native async API #980 — native async adapters
6. Add async adapter ergonomics and ordered concurrent helpers #982 — async ergonomics
7. Document async adapters and move the weather example onto them #981 — async docs and the weather example

Cross-fork PRs can only be based on main, so the diff is cumulative. The two commits unique to this PR are Add a Rust adapters guide to the docs and Move the live demo to a fallible adapter.

Validation

(CI CHECKS)

• Workspace tests, clippy, rustdoc, and formatting
• Demo binary builds and lints clean