lnrpc/chainrpc: surface re-org depth and Done over the chain notifier

[ellemouton]

Summary

The ChainNotifier confirmation/spend gRPC streams currently drop two pieces
of information that lnd already tracks internally:

1. Re-org depth — ConfirmationEvent.NegativeConf carries the depth as an
   int32, but the server discarded it and sent an empty Reorg{}.
2. Policy finality / Done — ConfirmationEvent.Done and
   SpendEvent.Done fire once a watch reaches lnd's configured re-org-safety
   depth, but the RPC server conveyed that only by closing the stream. A client
   cannot distinguish normal completion from unrelated teardown that way.

This PR makes the notification lifecycle reversible and explicitly terminal:

positive → reorg → positive → Done

Changes

• notifier: historical confirmation and spend registrations which are
  already beyond the re-org-safety limit now receive Done immediately after
  their positive event. Without this, they can never be reached by the
  per-block finality sweep and wait forever.
• proto: add Reorg.depth, add a payload-less Done message, and add
  done to the ConfEvent and SpendEvent oneofs. These are additive wire
  changes.
• RPC server: forward confirmation re-org depth and emit explicit Done
  for confirmation and spend streams. The server enforces positive-before-
  Done ordering even if Go selects the terminal channel first when both are
  ready.
• tests: cover already-mature historical registrations, terminal ordering,
  and the complete positive/reorg/positive/Done lifecycle for both stream
  types.

Semantics and compatibility

• Done means the backend's configured re-org-safety boundary, not a claim of
  consensus-level finality.
• Spend-side re-org depth remains 0: SpendEvent.Reorg is currently a bare
  internal signal and does not track depth.
• Older clients ignore the additive fields/oneof variants. Lifecycle-aware
  clients can distinguish normal completion from stream failure.

Downstream adapter: lightninglabs/lndclient#283.

Validation

• go test -tags=chainrpc ./lnrpc/chainrpc ./chainntnfs
• go test -race -tags=chainrpc ./lnrpc/chainrpc ./chainntnfs
• GitHub CI runs the repository-wide lint, unit, race, cross-compile, and itest
  matrix on the pushed head.

[github-actions]

🟠 PR Severity: HIGH

gh pr files | 5 files | 288 lines changed (92 excluding generated/docs)

🟠 High (3 files)

• lnrpc/chainrpc/chain_server.go - lnrpc/* RPC/API definition logic (chain notifier server implementation)
• lnrpc/chainrpc/chainnotifier.proto - lnrpc/* wire/API definition change (new proto fields)
• lnrpc/chainrpc/chainnotifier.swagger.json - lnrpc/* generated API surface (REST gateway spec)

🟢 Low (2 files)

• docs/release-notes/release-notes-0.21.0.md - release notes only
• lnrpc/chainrpc/chainnotifier.pb.go - auto-generated protobuf code (excluded from line/file counting)

Analysis

The highest-severity files touched are under lnrpc/chainrpc/*, which falls under the lnrpc/* category (RPC/API definitions) — classified as HIGH severity. This includes a .proto change (new/changed RPC fields) and the corresponding server-side handler in chain_server.go, plus the generated swagger spec.

No bump conditions apply: only 4 non-generated files changed (well under the 20-file threshold), ~92 non-generated/non-doc lines changed (well under the 500-line threshold), and no critical packages (lnwallet, htlcswitch, contractcourt, sweep, etc.) are touched.

Since this PR modifies a public RPC API surface (chainnotifier), it warrants review from someone familiar with the lnrpc API conventions and backward-compatibility concerns, consistent with HIGH severity.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}
<!-- pr-severity-bot -->

[lightninglabs-deploy]

@Roasbeef: review reminder