DSH plugin rollback: restore a known-good profile

Know which layer changed

Rollback scope should match the change. Removing one plugin is different from downgrading DSH, restoring a profile manifest, or restoring session storage after a format migration.

Preserve the failed state first

Before restoring anything, snapshot the failed profile, exact versions, lockfile, error output, and storage files. This keeps the incident reproducible and prevents a successful rollback from erasing the evidence needed for a bug report.

Restore into a comparison location

Whenever possible, restore the backup into a new DSH home or profile and run the baseline there first. Only replace the working location after the copied state proves it can compose and boot. This turns rollback into a comparison instead of a blind overwrite.

Reapply the exact plugin graph

Use the recorded artifact versions and integrity or commit identifiers. Do not reinstall latest while attempting to restore an older state; the package name may be the same while its bytes and compatibility evidence have changed.

• Restore the host version before plugins that depend on its peer contracts.
• Restore the profile bundle order and overrides.
• Confirm the package graph resolves one runtime copy where identity matters.
• Keep network credentials out of a diagnostic restore unless the smoke test requires them.

Prove the rollback

Run the exact pre-change controls: DSH version, profile dump, boot, and one deterministic capability test per required plugin. Compare the outputs with the baseline rather than accepting a successful process exit as proof.

dsh --version
dsh --profile web --dump-config

Return to the upgrade gate

After service is restored, mark the failed combination with exact artifacts and environment. Wait for fresh evidence or reproduce a fix in the comparison profile before attempting the upgrade again.