[codex] Structure legacy connection migration errors

[juliusmarminge]

Summary

• split legacy mobile catalog parse and schema-decode failures into distinct schema errors
• preserve the exact JSON or schema failure as cause
• keep stable caller-facing messages independent of defect text and avoid retaining the credential-bearing raw document

Validation

• pnpm vp test apps/mobile/src/connection/migration.test.ts
• pnpm vp check
• pnpm vp run typecheck
• pnpm vp run lint:mobile

---

Note

Low Risk
Localized error-model refactor in legacy migration with no change to successful migration behavior; callers must handle new error tags if they matched on the old type.

Overview
Replaces the single LegacyConnectionMigrationError with two tagged schema errors: LegacyConnectionDocumentParseError (invalid JSON) and LegacyConnectionDocumentDecodeError (schema validation). Each carries the underlying failure in cause via Schema.Defect(), while message is a fixed string that no longer embeds defect text (avoiding leaking raw catalog content in error strings).

migrateLegacyConnectionCatalog maps JSON.parse and decode failures to the matching error type. Tests assert tags, preserved causes, and stable messages for malformed JSON and invalid connections shape.

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

Note

Split legacy connection migration errors into distinct parse and decode error types

Replaces the single LegacyConnectionMigrationError class in migration.ts with two distinct tagged error classes: LegacyConnectionDocumentParseError for JSON parse failures and LegacyConnectionDocumentDecodeError for schema decode failures. Each class preserves the original exception as a cause field and returns a fixed message string. Behavioral Change: callers handling LegacyConnectionMigrationError will no longer match these errors and must be updated to handle the two new tags.

^{Macroscope summarized 2b98359.}

[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: 23cbfa74-abfc-4478-b597-03c76f667ec0

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/mobile-connection-migration-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

Straightforward error class refactor that splits a generic migration error into two specific typed errors with preserved cause chains. Changes are self-contained with corresponding unit tests added.

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

[juliusmarminge]

Superseded by the existing connection-persistence owner PR #3255, which already carries the structured migration stage and exact parse/decode causes.