docs: storage error handling and the storage adapter contract

[darcyparker]

What

Adds a dev-docs page, packages/automerge-repo/dev-docs/storage-error-handling.md, documenting what happens when storage I/O fails and where the responsibility for reliability lies. This is the follow-up suggested in the review discussion on #676. Doc-only; no code changes.

Contents

• What StorageSource guarantees: a failed save does not crash the process, and the change is retained in memory so a later save or reload re-persists it. It converts a fatal crash into a recoverable condition and does nothing more.
• The storage adapter contract: adapters own robustness; retry and backoff are one consideration (not a mandate, and not always the best fit); escalation is the adapter's responsibility, since only the adapter knows its backend.
• Reliability strategies: network redundancy via peers is usually the strongest lever, since a document synced to the repo instances you connect to is already durable in more than one place; adapter retry/backoff and other strategies (multi-backend write-through, a durable queue, reconciliation) are options to weigh.
• Observability and alerting: failures surface via the pluggable logger (setLoggerFactory, shaped for console/pino/winston); shipping logs (for example via OpenTelemetry) to an alerting layer is a deployment concern owned by the application embedding automerge-repo.
• Why there is no first-class storage error event: the logging path already exists and is configurable, escalation belongs in the adapter, and redundancy comes from the network; a custom LoggerFactory is the hook for programmatic handling.

[msakrejda]

Cool, thanks! Broadly, I think these docs are good. I'm not sure if this is the right place for them. It might be, but we're not really doing that for other stuff. Other options:

• a note in https://automerge.org/docs/reference/repositories/storage/ (maybe not the right place either, since it doesn't talk about implementation much)
• comments on StorageAdapterInterface (though maybe this is too high-level for something like that)

I'll sleep on it.

[darcyparker]

Cool, thanks! Broadly, I think these docs are good. I'm not sure if this is the right place for them. It might be, but we're not really doing that for other stuff. Other options:

• a note in https://automerge.org/docs/reference/repositories/storage/ (maybe not the right place either, since it doesn't talk about implementation much)
• comments on StorageAdapterInterface (though maybe this is too high-level for something like that)

I'll sleep on it.

NP - Use it as a reference. Feel free to close this PR.