DSH plugin capability evolution: adding without breaking
By the second year of a plugin, the expensive work is no longer writing features; it is not breaking someone else's plugin. The moment another plugin injects your service, your code is a shared contract: renaming one field can leave their plugin stuck at load time. The DSH plugin rule for evolution is simple -- add freely, subtract on a schedule.
Three kinds of DSH plugin breaking change
Renames, signature changes, and result-shape changes are the three quiet ways to break downstream. (source)
- Rename -- a method, field, or service name. TypeScript catches some of it at compile time; at runtime it is simply undefined.
- Signature change -- parameter order, requiredness, or a narrower type. Old callers keep passing arguments by the old convention and explode halfway through.
- Result-shape change -- an array becomes an object, an optional becomes required, a field disappears. Callers may not throw at all; they just quietly lose data.
The third is the most dangerous because it rarely raises. Downstream simply gets less than it expects, and the investigation costs far more than a clean error would.
One question decides whether a change is breaking: would a caller that edits nothing behave the same? If not, it is breaking.
Adding fields: DSH plugin optional plus default
Fields only get added, and additions are optional -- a compatibility line that costs nearly nothing. (source)
Three moves belong together when extending a request or result:
- Declare it optional --
foo?: string, so a caller that omits it is still valid. - Default on the consuming side -- missing means old behavior, not an undefined branch.
- Document it -- record the version it appeared in and what absence means.
Going the other direction is breaking: turning optional into required leaves old callers with no value. If tightening is truly necessary, route it through a deprecation window rather than editing the type in place.
There is a subtler case: adding a value to an enum. A consumer with an exhaustive switch sends the new value into the default branch, where behavior may differ completely. That is not a pure addition; announce it.
DSH plugin adding methods and default implementations
A new method is invisible to old callers; a new required parameter is not. (source)
Appending a method to a service is the safest form of evolution available, provided existing methods stay untouched.
Two caveats. If the new method demands a precondition, such as "call init first", it is not a pure addition and the precondition must be documented. And do not ship two entries for one concept -- if the old method can already cover the case, resist adding a near-synonym.
When replacing a method, run three steps:
- Ship the new method with the same behavior as the old one.
- Keep the old method and have it delegate to the new one, logging a warning per call.
- Remove the old method across a major version once callers have migrated.
Both paths then behave identically, and you avoid the bizarre class of bug where old and new disagree.
DSH plugin deprecation windows and migration hints
Deprecation is not deletion; it keeps the old path working while telling callers to move. (source)
A workable window has four parts:
- Mark -- type comments and docs state "deprecated, use X instead".
- Warn -- the old method logs once per call so you can count remaining users.
- Coexist -- both paths live, with identical behavior.
- Remove -- after confirming no callers remain, delete it across a major version.
There is no universal length, but the window must outlast other people's release cadence. Plugins are installed by their users and do not follow your version automatically, so the wait before deletion is usually longer than library authors expect.
DSH plugin versions and change logs
The version number is an index; the change log is the migration guide. (source)
The convention can stay simple: minor for features, patch for fixes, major for removals or behavior changes. But semantic versioning alone never tells a caller which line of their code to edit.
Every change log entry needs three sections:
- What was added -- methods and fields, with the version they became available.
- What changed -- behavioral differences, especially new defaults.
- What was removed -- the replacement and the migration steps.
With all three written, a caller can judge in a minute whether an upgrade touches them.
DSH plugin self-check before you publish
One pass before release blocks most upgrade-day outages. (source)
- List every public method, field, and service name you touched, and ask of each: does an unchanged caller still work?
- Check for newly required fields and for optionals that became required.
- Check whether an enum gained values and whether exhaustive consumers will notice.
- Check that every deprecation has a marker, a warning, and a replacement.
- Check that the change log covers added, changed, and removed.
Verification: old and new callers side by side
Call the same service under the old and new conventions; the results should match. (source)
- Keep a caller that builds requests only from old fields and assert it still works after the upgrade.
- Build a request with new fields and assert the new behavior applies while omitted old fields take the default path.
- Call a deprecated method and assert it still works, matches the new method's behavior, and emits one warning.
- Add a value to an enum and assert existing consumers do not crash and the new value has a defined path.
- Delete an old method, reload the old caller, and assert the failure names the missing method instead of returning undefined.
A failure in step 1 means an optional field was written as required. An undefined-only error in step 5 means there is no type or runtime check to help the caller diagnose itself.
Config evolution follows a parallel set of rules in evolving configuration; the full pattern for publishing capability as a service is in custom services.
One line to close: additions are free when fields are optional and methods are new, removals wait their turn through marking, coexistence, and a major version, and every breaking change ships with a migration path written into the change log.
FAQ
Because older callers never send it, and a DSH plugin required field makes missing illegal. DSH plugins collaborate through TypeScript interfaces and nothing fills in a default at runtime, so the compatible move is to declare the field optional and define the behavior when it is absent.
No: DSH plugin callers only break when existing signatures change. Callers in DSH only use the methods they inject for, so a new method is a pure addition. What actually breaks callers is renaming, reordering parameters, or changing the result shape, and those three need a deprecation path.
DSH plugin deprecation keeps the old method, marks it deprecated, ships the new one, and logs a warning when the old path runs. DSH has no enforced deprecation mechanism, so the contract lives in docs and type comments; remove the old method only after confirming nobody calls it, and never within the same minor.
A DSH plugin capability change needs a major bump when it removes or changes existing behavior. DSH plugins are installed by their users and never follow upstream automatically, so a major bump must spell out migration steps in the change log instead of trusting the version number alone.
Related Terms
- Service
- A Service is a named capability mounted on ctx; plugins publish methods through it, and a consumer that declares the dependency through inject receives the same instance.— DeepSeek Harness Docs - Services and Dependencies
- inject
- inject is the field that lists the services a plugin requires; the framework waits for them before running apply and unloads the consumer if one disappears.— DeepSeek Harness Docs - Services and Dependencies
- breaking change
- A breaking change is any edit that makes existing callers fail without touching their code, typically a rename, a signature change, or a different result shape.— DeepSeek Harness Docs - Services and Dependencies
- deprecation window
- The deprecation window spans from marking a capability deprecated to deleting it, with both paths live so callers can migrate on their own schedule.— DeepSeek Harness Docs - Plugins and Lifecycle
Sources
- DeepSeek Harness Docs - Services and Dependencies· deepseek-ai
- DeepSeek Harness Docs - Plugins and Lifecycle· deepseek-ai