#35518 doc: document -blocknotify, -walletnotify and other -*notify options

• Document that shell notifications run asynchronously without ordering guarantees
• Prevent external scripts and integrations from assuming sequential notification delivery

Adds doc/notifications.md to document the execution model of the five -*notify startup options. Specifically explains that each notification runs asynchronously in a detached thread without ordering guarantees, directing consumers to query state via RPC instead.

Problem: Users and external script integrations have historically assumed sequential notification execution, leading to race conditions and confusion as noted in issue #14278.

P3 · user request

• P3 because it fills a long-standing documentation gap on notification execution
• Prevents script authors from making false assumptions about delivery ordering
• Directs integrators to query state via RPC rather than relying on notify ordering

P3 because it addresses a long-standing documentation gap (#14278) that caused developers to make false assumptions about notification delivery ordering. The addition is concise and prevents script authors from relying on undefined concurrency guarantees.

Membership: Adds doc/notifications.md and updates doc/README.md to document shell command notifications.

Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 1

• Author has been silent for over two months after addressing all review comments

The author has been inactive for 79 days, exceeding the 60-day silence threshold, although all reviewer feedback has already been addressed and approved.

Author status: silent since 2026-06-30 after addressing all review feedback

Resolved concerns:

• sedited requested not exhaustively duplicating command-level help text and instead focusing on threading and ordering guarantees; author distilled the doc and moved blocknotify IBD docs to help text in #35586
• sedited recommended removing ZMQ comparisons and simplifying phrasing; author adopted the suggestions

• Resolved objection against duplicating command-level help text in markdown (sedited)
• Strong support after condensing to focus on concurrency and ordering guarantees (sedited)
• Agreed that notifications lack execution ordering guarantees (willcl-ark)

Strong: sedited approved after initial scope comments were addressed; willcl-ark agreed on ordering semantics

Review feedback was completely addressed by scoping the doc strictly to concurrency guarantees, resulting in an explicit approval from sedited.

• sedited approved on 2026-07-23 after the patch was distilled
• willcl-ark agreed on 2026-09-16 that notification ordering is never guaranteed

Objections:

Support:

• sedited: approved after the doc was condensed to focus strictly on threading, concurrency, and ordering guarantees

Participants: sedited (objection), willcl-ark (neutral)

State derived from the lists: substantive support, no open objection (sedited)

Review verdicts (DrahtBot): 1

• ACK: sedited

0 lines under test/bench/ci.

• doc/notifications.md +20/-0
• doc/README.md +1/-0

Adds doc/notifications.md documenting that shell command notifications (-*notify) run in detached threads without ordering guarantees and recommends verifying state via RPC. Solves a persistent trap for developers integrating external automation with bitcoind, partially closing #14278. The scope was trimmed in review to focus purely on execution semantics, earning an ACK from sedited. The PR is clean and ready for merge consideration despite author inactivity.