dsh plugins vs Harness versions: compatibility matrix

A plugin can declare support for a DeepSeek Harness release, install cleanly, and still fail on the first real tool call. Compatibility is not one fact but four answers, and a DSH plugins matrix is where those answers get archived.

The DSH plugin upgrade that looked compatible until it wasn't

Version numbers that look close are a feeling, not evidence, and a DeepSeek Harness upgrade punishes that feeling quickly.

The upgrade usually begins well. The package installs, the plugin appears in the list, and the first session opens. Then a command that used to work returns an error, or a panel renders empty, or the host refuses to activate the plugin after a restart. Nothing in the install output predicted it.

The reason is that compatibility lives in several places at once. A plugin declares a host range, a runtime requirement and a set of behavior changes, and those declarations can disagree with each other. Reading one of them and skipping the rest produces false confidence.

The four questions are simple: what does the peer dependency allow, what do the engines require, what changed in the changelog, and can I get back? Answer them in that order and the upgrade stops being a gamble. Skip one and the missing answer tends to surface at the worst moment.

Question one: what do the DSH plugin peer dependencies allow?

Peer dependencies are the closest thing to a contract between a DSH plugin and the DeepSeek Harness core, so read the range rather than the installed version.

A peer dependency names the host versions a DeepSeek Harness plugin expects. A narrow range is a warning: the author tested against a small set of releases and does not claim more. A wide range is not automatically safer, because it may simply be old.

Resolution conflicts usually start here. The package manager may warn, or it may install anyway and leave the mismatch for runtime. Treat the warning as a question, not noise.

When the declared range excludes your core version, you have three honest choices: stay on the old core, move to a plugin version that declares support, or test the combination in an isolated profile. Installing and hoping is not one of them. Each choice has a cost, and naming it is part of the decision.

Write the range down. It becomes the first column of the answer set you will later archive in a matrix. The range is the first answer, not the whole answer.

Question two: do the engines match the DeepSeek Harness runtime?

Engines describe the environment a DSH plugin was built for, and an unsupported Node version fails in ways that look like plugin bugs.

The engines field is coarse. It filters obvious mismatches, such as a plugin that needs a newer Node than the one running the host. It does not prove that the plugin behaves correctly on a supported version.

Still, skipping it wastes time. A syntax error at load, a missing native module, or a crash before activation often traces back to a runtime the package never claimed to support. Checking the field takes a minute and removes a whole category of doubt.

Record the runtime alongside the core version. Two machines on the same core but different Node versions are not the same test environment, and a matrix that ignores this will produce results nobody can reproduce. A one-line environment header is enough.

Engines are a gate, not a guarantee. Once the gate passes, behavior still has to be tested with a real operation. Treat a passing gate as permission to test, not permission to ship.

Question three: what changed in the DSH plugin changelog?

The changelog is where a DSH plugins upgrade stops being a version comparison and becomes a description of what will break.

Peer dependencies and engines describe the shape of the package. The changelog describes the behavior inside it: renamed configuration keys, removed commands, changed defaults, new permissions. These are the changes users actually feel.

Read it for the versions between yours and the target, not just the target release. A breaking change introduced two versions ago is still breaking when you skip over it. The skipped releases are where the expensive surprises live.

Look specifically for migration notes. An author who documents a config rename has usually also documented the fallback. An author who does not has told you something about the risk.

If the changelog is missing or empty, lower your confidence rather than raising it. Silence is not a compatibility statement. An empty changelog is a reason to ask the author, not a reason to assume safety.

Question four: is there a DSH plugin rollback path?

A compatibility decision without a way back is not a decision; it is a commitment.

Before upgrading, confirm the current combination in DSH Plugin Hub and check that it can be restored. The old core version must still be installable, the old plugin version must still resolve, and the configuration must be readable by both. If any of those is false, the upgrade is one-way.

A lockfile helps with what installs, but it does not answer whether the result works. Keep the lockfile and the tested combination together, with a date. A lock without a test result is only a promise about bytes.

Then run the upgrade with the return path in hand. Keep the terminal output and the resulting version list. Both become evidence if the combination fails.

1. Save the current core, plugin and runtime versions.
2. Confirm the old packages still resolve.
3. Copy the profile or configuration you will need.
4. Upgrade one component at a time.
5. Run one real operation per plugin after each step.
6. If it fails, restore the saved combination before investigating.
7. Record which step broke and what the error was.

The discipline matters more than the exact order. What matters is that the return path was verified before the first package moved, not invented after the failure. A rollback plan written after the failure is a wish, not a plan.

The DSH plugins compatibility matrix is only an archive

The matrix does not create compatibility; it records answers you already found, which is why it belongs at the end of the process rather than the beginning.

Rows are core versions, columns are the plugins you actually run, and each cell is pass, fail or untested. A cell without a date and a symptom is a guess wearing a table's clothes. Keep the evidence next to the cell, not in someone's memory.

Keep it small. The last two stable core versions plus a candidate, and only the plugins in your daily profile, will answer more real questions than a complete grid nobody updates. A grid that grows faster than your testing habit stops being evidence.

The matrix is most useful when it is boring. If a cell changes, someone ran something and wrote it down; if nothing changes for months, that is information too. Either way, the dates tell you whether to trust the row.

The four questions remain the source. The matrix is the archive, and the upgrade decision is still yours to make with the evidence in front of you. Date the matrix so a future reader knows how old the evidence is.