针对 DSH 高频发布节奏的兼容性治理：升级门禁、兼容矩阵、按配置文件锁定

[Shizuku-keop]

DSH ships fast (4 releases in 12 days) and every compatibility break is paid for by users — the rc.8 storage-format change already wiped sessions with no migration path. The community holds this together with manual discipline (hand-maintained compat matrices, pinned commits, blog posts).

I built dsh-compat-guard (zero-dependency CLI + plugin) to turn that discipline into tooling, and I'm posting here as a governance proposal, not just a plugin showcase:

What it does

• dsh-guard preflight — an upgrade gate: per-plugin compatibility vs the target DSH version (compat registry > author dsh.compat metadata > untested), a storage-format fingerprint check (zstd/sqlite magic-byte scan, no decoding), and an automatic $DSH_HOME snapshot. Blocking changes refuse the upgrade (exit 1). This is the gate that would have caught the rc.8 session-loss incident before it ran.
• dsh-guard snapshot / verify / rollback — per-profile dsh.guard.lock.json (exact dsh + plugin versions, integrity, config hashes, storage facts) + tar snapshots. One-command rollback, safety snapshot first. Solves "works on my machine".
• dsh-guard migrate — session migration (sqlite -> zstd JSONL), backup-first, verify-then-rename, unknown formats backed up and refused.
• A machine-readable compat matrix: plugins declare dsh.compat, a reusable CI workflow + local runner produce per-version install/boot-smoke results into a registry (Blue-Whale-Harness/compat) consumed by preflight. First results: dsh-better-sidebar & dsh-mnemon pass 8/8 across 0.1.0-rc.7 .. 0.1.1-rc.2.

Two small metadata PRs are open upstream (please take a look, they are 1-file, no behavior change):

• chore(compat): declare dsh.compat metadata omdsh-dev/DSH-better-sidebar#384 — adds dsh.compat to package.json
• chore(compat): declare dsh.compat metadata omdsh-dev/dsh-mnemon#75 — adds dsh.compat to package.json

Repo: https://github.com/Shizuku-keop/dsh-compat-guard (MIT, 17 unit tests, v0.1.1)

Suggestions for upstream (happy to discuss):

1. A pre-hook on dsh plugin add/update/install would let the gate run automatically instead of via a wrapper alias — the launcher currently has no hook point.
2. Versioned storage-format declarations per release (like the projcache unit.version already used internally) would let tools fingerprint upgrades before they run, instead of the community reverse-engineering formats after data loss.
3. Dist-tag hygiene (next/latest drift) would help users know what they are on.

The plugin API surface has been stable across rc.7 -> rc.2 for the two biggest web plugins — the pain is in data-layer changes and release logistics, which is where governance tooling helps most.