CleanMM/Docs/ADR/ADR-008-Versioned-Workspace-State-and-Recovery-Payload-Compatibility.md

ADR-008: Versioned Workspace State and Recovery Payload Compatibility

Status

Accepted

Context

Atlas persists a local workspace-state file and stores recovery payloads for both Finding and app uninstall flows. Those payloads have already evolved in place: app recovery entries gained uninstall evidence, and the active roadmap now explicitly calls for payload stability, older-state compatibility, and more trustworthy history behavior.

Without an explicit persistence envelope, Atlas can only rely on best-effort shape decoding. That makes future recovery hardening riskier and leaves migration implicit. The Apps flow also risks showing stale preview or stale footprint counts after restore unless restored app payloads are reconciled with fresh app inventory.

Decision

• Atlas persists workspace state inside a versioned JSON envelope containing schemaVersion, savedAt, snapshot, currentPlan, and settings.
• Atlas continues to decode legacy top-level AtlasWorkspaceState files and rewrites them into the current envelope after a successful load when possible.
• AppRecoveryPayload carries an explicit schemaVersion and remains backward-compatible with the older raw-AppFootprint recovery payload shape.
• App restore flows clear stale uninstall preview state and refresh app inventory before the Apps surface reuses footprint counts.

Consequences

• Atlas now has an explicit persistence contract for future migration work instead of relying on implicit shape matching alone.
• Older state files remain loadable while the repo transitions to the versioned envelope.
• App recovery payloads become safer to evolve because compatibility is now a stated requirement.
• The Apps surface becomes more trustworthy after restore because it no longer depends only on stale pre-uninstall preview state.

Alternatives Considered

• Keep the unversioned top-level state file and rely on ad hoc per-type decoding: rejected because it scales poorly as recovery payloads evolve.
• Break compatibility and require a fresh state file: rejected because it damages trust in History and Recovery.
• Refresh app inventory only on explicit user action after restore: rejected because it leaves a visible stale-evidence gap in a trust-critical workflow.