Ideas: where to take error translation next (recovery actions, self healing, proactive detection)

[!IMPORTANT]
This is not a task to execute. It is a set of ideas captured while building the error
translation layer, written down so the reasoning is not lost. Nothing here is agreed, scoped or
prioritised. It needs a discussion to decide whether any of it is worth doing, and in what form,
before anyone picks it up.

Labelled on-hold and needs-triage deliberately.

Context: what already shipped

ConnectionDiagnosticsService turns a failed database operation into an explanation the user can
act on, when the cause is infrastructure rather than the database. Providers exist for DocumentDB
Local (Docker), Kubernetes port forwarding, and Atlas TLS rejections.

It is translation only. Providers return text. They never show UI, never recover, never retry,
and never touch the error object. That constraint is what keeps the design small, and it is
documented in .github/skills/error-translation/SKILL.md.

Covered surfaces today: cluster connect and list databases (all views), everything below a cluster
(all four tree views, via BaseExtendedTreeDataProvider), Collection view query and Query Insights,
Document view, tree-node commands, the shell, and the query playground.

The question this issue exists to answer

Now that failures are explained, is it worth also making them fixable in place? The options
below have very different cost curves, and lumping them together as "future work" hides that.

---

Tier A: name an action (not perform it)

A provider returns text plus a command to offer, rather than a function to run:

{ message: string; action?: { commandId: string; title: string } }

The call site shows the button and executes the command. The provider still never acts; it only
names what would help. The "no side effects in providers" rule survives intact.

Most plumbing already exists: common.displayErrorMessage already accepts actions: string[] and
returns the chosen one, vscode.window.showErrorMessage takes action labels, and the Quick Start
commands (...localQuickStart.start, .open, .viewLogs) are already registered.

Important constraint if we do this: stop after the action succeeds. Do not resume the original
operation. The message becomes "DocumentDB Local is not running. [Start it]", and the user runs
their operation again. Because nothing is replayed and no error is suppressed after the fact, none
of the machinery in Tier B is needed.

Cost: a contract field, a small amount of service code, a few lines per call site that wants
buttons. Risk: low.

---

Tier B: perform the action and resume (self healing)

The moment we recover and continue, a whole package comes back, and it comes back together:

Needed because	Machinery
Recovery fixed it while other operations were failing	Recovery epochs, stale-error suppression
Several nodes fail at once, each wants to prompt	Prompt singleton per cluster
Starting a container takes tens of seconds, probes pile up	In-flight dedupe, cooldown
A write must never be replayed after recovery	Operation intent plumbed to every call site
A declined or failed recovery must not re-prompt forever	Recovery cooldown

The last row is the expensive one. Intent (foreground read / foreground write / background) would
have to reach every call site, which is exactly the plumbing the current design avoids by putting
the catch in shared places. BaseExtendedTreeDataProvider and commandErrorHandling do not know
or care whether an operation was a read or a write today. Tier B makes them care.

Cost: substantial, plus a class of concurrency bugs that only appear under load.
Value over Tier A: the user saves one click and one re-run.

Worth being explicit: "users had to click Start and then press Run again" is probably not a strong
enough complaint to justify this. If we do it, it should be because of evidence, not symmetry.

---

Tier C: proactive detection

Subscribe to the MongoDB driver's SDAM events (serverHeartbeatFailed,
topologyDescriptionChanged) on already-open clients, so the tree could show a cluster as
unreachable before the user tries anything. This adds no new polling: the driver already
heartbeats open clients, and this is the opposite of the unconditional Docker polling that was
removed.

Note there are currently zero topology listeners in the codebase.

Cost: small. Value now: also small, because on-demand translation already gives a correct
explanation the moment the user hits the problem, and for Quick Start the tree row self-corrects as
a side effect of the preflight. The open question is what a single failed heartbeat should mean, as
a blip is not an outage.

---

Two smaller things that are probably worth more than any of the above

These are cheap and concrete, and would inform whether Tier A is worth building at all.

1. An Azure diagnostics provider. Atlas, Kubernetes and Docker have one; Azure does not. Firewall
   and IP-rule rejections on vCore and RU still surface as raw driver errors, and are plausibly the
   most common infrastructure failure by volume. One file plus a registration line, following the
   Atlas provider's shape.

2. Close the telemetry gap. connectionDiagnostics.explained fires only on success, and
   diagnosisProviderId = 'none' is recorded only in ClusterItemBase. So we can see when we
   explained a failure, but not how often we had a failure and nothing to say. Recording the
   miss everywhere turns "which provider should we write next" and "is Tier A worth it" from
   opinion into a query.

Suggested discussion order

1. Do we agree Azure provider + telemetry miss counter come first?
2. After a release of data, does anything justify Tier A?
3. What specific, evidenced complaint would be required before Tier B is even considered?
4. Park Tier C unless something changes.

Also unresolved

• Should ConnectionReachabilityService and ConnectionDiagnosticsService eventually share a base
  registry? They have identical registerProvider semantics but different lifecycles and dispatch
  keys. Possibly premature.
• Webview limitation, recorded in the skill: only the error message crosses the tRPC boundary,
  so a provider needing an error's class or code cannot be served from a webview.

Start by reading .github/skills/error-translation/SKILL.md, ConnectionDiagnosticsService, BaseExtendedTreeDataProvider, and commandErrorHandling. This issue is discussion-only: done means agreeing on whether Azure diagnostics, telemetry misses, Tier A, Tier B, or Tier C should become separately scoped work before implementation begins.