Plugin compatibility: engines, core drift, upgrade order

Plugin compatibility is not "the version numbers are close enough." Engines, core package versions and dependency resolution decide it together, and misreading one produces a plugin that installs but fails to load.

What decides compatibility

Three variables decide whether it runs.

Engines is a declaration, not a guarantee. It tells the installer what environment is required and does not repair a mismatch.

The core version decides interfaces. Methods a plugin calls change with the core, and a large gap leaves runtime calls missing.

Resolution decides instances. When the same core package is installed twice, plugin and host may each load one copy and behave differently (source).

Three incompatible symptoms

Different symptoms point in different directions.

1. Load failure: resolution error, missing entry point, or unsatisfied engines.
2. Broken features: it loads, then calls fail, typical of interface changes.
3. Inconsistent behavior: the same action gives different results, typical of duplicate cores.

Load failures point to versions first, broken features to the call stack, and inconsistency is hardest. Resolution errors are usually explicit in startup logs; missing methods mean changed interfaces while wrong arguments mean changed signatures, and the two fixes differ; for inconsistency, confirm only one core copy exists, which dsh --dump-config and the dependency tree reveal.

Finding version drift

Confirm drift in five steps instead of guessing.

1. Record the current core and plugin versions.
2. Read the declared compatibility range and check whether the version falls inside.
3. Inspect the dependency tree for duplicate or mismatched core packages.
4. Compare against the last upgrade to see whether it introduced the problem.
5. Retest with a minimal plugin set to exclude interference.

The compatibility range is the first test and the dependency tree the second. Falling outside does not guarantee failure, but it requires extra validation. Duplicate cores are a common root cause that upgrading the plugin alone cannot fix; the dependency declaration must change.

A minimal set is the third test. With several plugins installed, the combination may be the problem rather than any single one.

Upgrade order

Wrong order compounds compatibility problems.

1. Back up: record versions, plugin list and configuration.
2. Upgrade core: move to the target version and run minimal features.
3. Upgrade plugins: follow compatibility declarations one at a time.
4. Verify: run a minimal feature after each plugin.
5. Roll back: revert only that layer instead of reinstalling everything.

The core goes first because of interfaces. Plugins depend on core interfaces, and a plugin upgraded ahead of the core can still be incompatible.

One plugin at a time. Batch upgrades make the culprit unidentifiable; sequential upgrades keep the scope small.

For plugin authors

Reduce incompatibility through declarations and dependencies.

1. Declare engines: state the Node.js and core version ranges.
2. Use a peer dependency for the core: avoid bundling it and creating duplicates.
3. Declare dsh.bundle: let profiles recognize combination packages.
4. Avoid private APIs: call public interfaces only, reducing exposure to version changes.
5. Document compatibility: state supported ranges and known limits in the README.

The peer dependency is the key. It requires the host to provide the core instead of shipping another copy, and duplicate cores underlie many inconsistent behaviors.

Compatibility notes beat version numbers. Users can decide whether to install without guessing.

For users

Users do not need the source, but they need three habits.

1. Read compatibility before installing: check the supported range in the plugin notes.
2. Respect upgrade order: core first, plugins after.
3. Read logs when it breaks: the first failure is more useful than the last error.

Do not assume "latest" is safe. A new core with an old plugin, or an old core with a new plugin, can both fail; pair them per declarations.

Keep a rollback version. Record the pre-upgrade combination so you can return to it; without a record you start over.

Checklist

Follow the list so nothing is skipped.

1. What are the core and plugin versions?
2. Does the plugin engines and compatibility range cover the current version?
3. Is there exactly one core package in the dependency tree?
4. What is the first failure in the startup log?
5. Does the problem reproduce with a minimal plugin set?
6. Does rolling back to the previous combination restore it?

Passing all six usually locates the problem. The value of a checklist is a fixed order that stops you circling in the wrong direction.

Record the outcome. Versions, symptoms and the fix; the next occurrence becomes a quick lookup.

Next steps

Read declarations, then dependencies, then logs. For the specification, read DSH plugin version compatibility. For drift, read Fixing core package version drift. To build your first plugin, read Writing a first DSH plugin from the market model.

Sources: DeepSeek Harness docs: packaging and installing plugins, dsh CLI README, deepseek-harness repository