[codex] Structure connection persistence failures

[juliusmarminge]

Summary

• replace web and mobile persistence constructor wrappers with explicit error mappings at each failure boundary
• attach operation, stage, resource, environment, thread, path, and the original cause to persistence failures
• preserve catalog and migration causes while keeping stable messages independent of cause text
• use tagged catch semantics for catalog recovery paths and hoist reusable Schema codecs

Validation

• vp test packages/client-runtime/src/platform/persistence.test.ts packages/client-runtime/src/connection/registry.test.ts apps/web/src/connection/storage.test.ts apps/mobile/src/connection/storage.test.ts apps/mobile/src/connection/migration.test.ts
• vp check (passes with existing unrelated warnings)
• vp run typecheck
• vp run lint:mobile

Stack

• based on [codex] Preserve client connection error causes #3242 because it uses the optional cause support added to ConnectionTransientError there

---

Note

Medium Risk
Broad changes to error shapes across web/mobile local connection persistence; recovery behavior is similar but callers that depended on old message strings or untyped causes may need updates.

Overview
Replaces ad-hoc string-built persistence errors with structured tagged errors whose user-facing message is stable and does not embed raw cause text.

ConnectionPersistenceError now records stage, resource, optional environmentId / threadId / path, and cause, with a computed message. Storage-layer failures map through new types (ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError) and ConnectionTransientError.fromStorageFailure, keeping the full failure chain on cause.

Web and mobile connection storage/catalog paths are updated to construct these errors at each boundary (IndexedDB, desktop secure storage, Expo secure store, file caches). Catalog encode/decode uses shared Schema Effect codecs; corrupt-catalog recovery uses Effect.catchTags for ConnectionTransientError only. LegacyConnectionMigrationError gains stage (parse | decode) and cause instead of a free-form message.

Tests assert cause preservation, stable messages, and that sensitive details stay out of surfaced strings.

^{Reviewed by Cursor Bugbot for commit 4d9e86a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Structure connection persistence failures with typed error classes across web and mobile storage

• Introduces ConnectionStorageOperationError, IndexedDbUnavailableError, DesktopSecureStorageUnavailableError, and a ConnectionTransientError.fromStorageFailure factory in model.ts to standardize transient storage errors with stable, non-leaking messages.
• Replaces free-form strings in ConnectionPersistenceError (persistence.ts) with structured fields (operation, stage, resource, environmentId, threadId, path, cause) and a derived stable message.
• Applies these structured errors throughout web (apps/web/src/connection/storage.ts) and mobile (apps/mobile/src/connection/storage.ts) storage layers, covering IndexedDB, secure storage, shell/thread cache, and catalog encode/decode paths.
• Wraps LegacyConnectionMigrationError with structured stage and cause fields in migration.ts; only ConnectionTransientError is caught during corrupt-catalog recovery, allowing other error types to propagate.
• Behavioral Change: non-transient errors from catalog load and legacy migration no longer get silently swallowed — they propagate to the caller.

^{Macroscope summarized 4d9e86a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ee00c60d-9f4a-4e28-a80e-1ddc90dc8a86

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/connection-persistence-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Structural refactor of error types in connection persistence code. Replaces string-based error messages with typed error classes containing structured fields (operation, stage, resource, cause) for better debugging and observability. Error handling flow unchanged; new tests verify the structured error behavior.

^{You can customize Macroscope's approvability policy. Learn more.}

Dismissing prior approval to re-evaluate 4d9e86a