Reversible Lucid Upgrade and Migration
Overview
Move one Lucid contract boundary at a time with an immutable baseline, representative fixtures, canary evidence, and tested rollback.
Prerequisites
- Clean source revision, dependency lockfile, manifests, deployed artifact identity, and current production version
- Representative synthetic imports, documents, data, and connector events where applicable
- Owners for code, data, Lucid application, source system, and rollback
Tool Discipline
Use Read, Glob, and Grep for version and usage inventory, WebFetch for current official migration contracts, and Write or Edit only for approved local changes, tests, and receipts.
Current Contract
The Standard Import format evolves and may render differently over time. Extension SDK/CLI and manifest behavior are versioned through project dependencies. REST resources may require Lucid-Api-Version. These are separate migration axes and must not be changed blindly together.
Authentication
Preserve credential classes and least scopes unless a documented target contract requires change. Treat new scopes, redirect URIs, consent, account grants, and secret rotation as separate approved migrations.
Instructions
- Inventory current and target package/CLI versions, API-version headers, manifests/scopes, import fixtures, connector schemas, and deployment artifacts.
- Capture a clean baseline: build, types, manifests, tests, fixture imports/exports, data reconciliation, and rollback.
- Re-fetch exact official docs and inspect target installed types/changelogs; create a breaking-change matrix.
- Split changes into reversible steps: tooling/dependencies, compile fixes, manifest/scopes, format/schema, API version, and deployment.
- Present dependency edits and any auth/data contract changes for approval.
- Apply one step, regenerate the lockfile with the project package manager, and run narrow then full affected gates.
- Test old/new representative fixtures and compare rendering, data, identifiers, errors, and performance.
- Deploy a bounded canary after approval; reconcile, monitor, and roll back on threshold breach before broader promotion.
Approval Boundaries
Do not upgrade packages, change API versions/scopes, rewrite stored data, reinstall extensions, or deploy merely because a newer version exists.
Output
Return baseline/target matrix, official evidence, changed files, dependency and scope diffs, tests, canary, rendering/data variance, approval, and rollback status.
Error Handling
| Condition | Response |
|---|---|
| Target types remove a used API | Stop and redesign with supported primitives; do not conceal it with casts. |
| Import renders differently | Preserve both artifacts, quantify variance, and require owner acceptance. |
| Rollback changes data/schema | Test a forward repair and recovery copy before rollout. |
Example
axis=sdk; baseline=locked; target=reviewed; fixture-parity=pass; scope-delta=none; canary=not-approved
Resources
Next Steps
Promote only after canary parity, explicit acceptance of known variance, and tested rollback from the exact artifact.