DSH plugin state homes: closure, Fiber, service, storage
Halfway through plugin development, where state lives matters more than the logic itself. The same counter resets on hot reload in a closure, survives until the provider unloads in a service, and only crosses a restart in storage. There is no default correct place in DSH plugin, only a place that matches the lifetime.
DSH plugin state: four homes, four lifetimes
Ask how long the state must live, then pick the home that matches. (source)
| Home | Lives until | Good for |
|---|---|---|
| apply closure | the current instance is unloaded | one-shot config, captured references |
variable inside ctx.effect | same, but cleanup has an owner | resource handles tied to setup |
| service instance field | its provider plugin stays ACTIVE | memory shared across callers |
| persistence | across processes and sessions | counters, cursors, grants, preferences |
The useful column is the middle one. Most "state disappeared" bugs are a first-row home used for a fourth-row requirement.
Note that row two does not extend lifetime. ctx.effect only guarantees someone runs cleanup; putting state there buys a teardown path, not a longer life.
Closure state: the cheapest DSH plugin state
Closure state travels with the instance, so every save resets it. (source)
HMR unloads the plugin, clears registrations, reloads code, and runs apply. The closure belonged to the old instance, so counters, caches, and dedupe sets return to their initial values on each save.
During development this looks like "the code is fine but behaves as if freshly started". A rate limiter that suddenly allows everything is the classic case. In production it looks like re-warming: the index cache is rebuilt on every restart.
One question decides whether a closure variable should move: would the user notice if it reset? If yes, it cannot live only in the closure.
Child Fibers and shared DSH plugin state
A child plugin has its own Fiber, and the parent cannot see inside it. (source)
ctx.plugin() creates a child Fiber that inherits context but has an independent lifecycle: unloading the parent recursively unloads the child, and the child can also be disposed on its own.
That rules out "the parent owns a global table the child reads". Sharing has exactly two routes: the parent provides a service the child injects, or the parent passes an object in when mounting the child.
The first fits the framework's dependency model and makes the relationship explicit; the second is lighter for tightly coupled internal modules. Neither should be replaced by a module-level variable, which breaks both unload semantics and hot reload.
DSH plugin service state: shared, tied to the provider
A service lifts state from one plugin to a group of callers, yet it is still not persistence. (source)
With a class-form provider, state lives in instance fields, and every injector holds the same reference, so all callers see one copy.
Two costs come with that. A required service disappearing unloads its dependents, and reloading the provider resets those fields. And the service's lifetime belongs to the provider, so one provider hot reload forces every caller to obtain it again.
Services are a good cache and a bad ledger.
When DSH plugin persistence is mandatory
State that must survive a process boundary goes to disk and comes back on startup. (source)
The test is three crossings: across processes, across sessions, across devices. Any one of them means persistence, whether that is the session log, a storage backend domain, or the plugin's own file.
Persistence adds three problems that belong in the design, not in a follow-up ticket:
- Write timing — write on every change or batch, and how much loss a crash may cost.
- Read validation — how old data is migrated and rejected when incompatible.
- Concurrency — who wins when two instances write the same record.
Moving state to disk without answering these usually produces bugs that are harder to diagnose than the original.
The DSH plugin state four-question checklist
Answer four questions and the home is usually obvious. (source)
- Would a user notice if it reset? If yes, not closure-only.
- Must another plugin read it? If yes, make it a service or pass it out.
- Must it survive a restart? If yes, persist it and answer the three problems above.
- Is it tied to a resource or is it a fact? Resource-bound handles belong in an effect with a disposer; facts like counters and grants move up by lifetime.
One "yes" is enough to move the state up one row. All four "no" means the closure is both cheapest and clearest.
Verification: one counter in four homes
The same logic in four places should lose state exactly where the table says. (source)
- Keep the counter in the apply closure, increment it, trigger a hot reload, and assert it resets.
- Move it into a service field, increment from an injector, unload the provider, and assert both the value and the caller reset.
- Mount a child with
ctx.plugin, give each its own counter, and assert the parent cannot read the child's. - Persist the counter, restart the process, and assert the value returns and old data still parses.
- Hold a resource handle inside an effect, unload, and assert the disposer ran and the handle is closed.
If step 2 leaves the caller running, it never declared the service as a required dependency, which is a separate latent bug.
Once lifetime is settled, the next question is usually cleanup, covered in cleanup order and reverse disposers; exposing state as a capability is covered in defining a service.
One line to close: closure lives to unload, effects only own cleanup, services live to provider disposal, persistence crosses restarts; pick by lifetime, and never let a counter and a ledger share a home.
FAQ
DSH plugin closure state vanishes because hot reload unloads the old instance and runs a new apply. HMR clears the old registrations and executes apply again, so counters, caches, and dedupe tables inside the closure reset on every save.
No: DSH plugin state is not shared with a ctx.plugin child. A child Fiber has its own lifecycle, so the parent cannot read the child's closure variables. Share through a service the parent provides, or hand an object into the child explicitly.
DSH plugin dependents unload too when the service provider disappears. A required service disappearing disposes the plugins that inject it, and they reload when it returns, so service fields behave like a cache rather than a ledger.
DSH plugin state that must survive a restart, a new session, or another device has to be persisted. In-memory state only covers the current instance, so counters, cursors, and grants belong in the session log or a storage backend and are read back at startup.
Related Terms
- Fiber
- Fiber is the lifecycle scope Cordis creates for each plugin instance; loading, activation, and unload happen inside it, and closure state shares its lifetime.— DeepSeek Harness reference - Plugins and lifecycle
- ctx.plugin
- ctx.plugin mounts a child plugin, creating a child Fiber that inherits the parent context but keeps an independent load and unload lifecycle.— DeepSeek Harness reference - Plugins and lifecycle
- Service
- Service is a named capability mounted on ctx; a class-form provider creates one instance per plugin, and injectors receive the same reference.— DeepSeek Harness reference - Services and dependencies
- HMR
- HMR is hot module replacement: editing a plugin source unloads the old instance, clears registrations, loads new code, and runs apply again.— DeepSeek Harness reference - Plugins and lifecycle
Sources
- DeepSeek Harness reference - Plugins and lifecycle· deepseek-ai
- DeepSeek Harness reference - Services and dependencies· deepseek-ai