ChatGPTClaudeGrok / X / CursorGemini

DSH plugin scope registry: keys, contexts, layer visibility

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessscope registryScopeLayervisibility
A service behaving differently across scopes is usually layering. Covers ScopeKey, Scoped carriers, Scope teardown, and merge order.

The same registration code resolving differently in two scopes is working as designed, not buggy. DSH plugin's scope package uses a small vocabulary to put per-agent visibility and shared lifecycle ownership into one registration context. The bug is usually that you registered into layer A while believing you were in layer B.

Why scope is a library, not a service

The scope package supplies identity, carrier, and layer vocabulary but no runtime state, so it is deliberately a primitive.(source)

Two consequences follow. There is no ctx.scope service to fetch a “scope manager” from, and lifecycle rationale lives in the agent-scope runtime design reference while callable API and filtering semantics live in the package README.

The source is split in two: packages/core/scope/src/index.ts for identity and context primitives, and packages/core/scope/src/store.ts for the registry layers. Keep those apart, or you will confuse “creating a scope” with “registering an entry into a layer”.

ScopeKey and Scoped: who versus where

ScopeKey answers “who”, Scoped answers “addressed to whom”, and neither carries business data.(source)

ScopeKey is an opaque, identity-compared key. The shipped agent loop uses the live Agent object as its key, but the primitive never inspects it: no id, no status, only reference identity.

ts
type ScopeKey = object

Scoped<T> is a compile-time brand applied to the opaque routing receiver returned by scopeTarget(base, key). Scope-filtered event declarations require that carrier as this, while the real subject arrives as an explicit parameter.

ts
type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }

That type is easy to misread. The carrier exposes none of the subject's properties; it records the subject type for dispatch checking, and the payload holds the actual subject. Trying to read fields from Scoped<T> is intentionally blocked by the type system.

Scope's three faces: ctx, rawDispose, dispose

One Scope answers where to register, how to nest, and how to wait for full quiescence.(source)

ts
interface Scope {
  ctx: Context
  rawDispose: () => Promise<void> | void
  dispose(): Promise<void>
}

ctx is the scope-owned registration context, and everything registered through it belongs to that scope. rawDispose retains the exact Cordis disposer identity so the scope can be nested into an ordered composite effect. dispose() is the public quiescent boundary for direct and racing callers; racing calls await the same completion.

That is why you cannot just collect dispose() into an array when tearing down scopes: composite effects need exact identity, not “something that stops”. Conversely, when concurrent callers need proof that everything stopped, dispose() is the right await.

ScopeLayer and ScopedLayers: global versus lazy scoped

Layers aggregate contributions; the global layer exists immediately, scoped layers appear on first registration.(source)

ScopeLayer represents one registry's complete contribution at the global or one exact scope level. A layer may aggregate several named and anonymous tables, and emptiness is answered by a single method:

ts
interface ScopeLayer {
  isEmpty(): boolean
}

ScopedLayers<L> owns the immediately created global layer plus lazily created exact-scope layers. Three rules matter:

  1. Reads never create layers — peek(undefined) means no scoped override exists, not “an empty layer exists”.
  2. Merge order is fixed — merge() materializes global named entries in insertion order, then overlays scoped shadows.
  3. Registration uses one context — visibility and Cordis effect ownership come from the same ctx, taking a synchronous revoke before optional notification.

The registration return is also specific: it returns the raw Cordis disposer and reclaims the scoped layer only when the complete ScopeLayer is empty. Clearing a single table therefore does not drag its siblings down, which decides whether your unload order is safe.

NamedEntries versus AnonymousEntries

Named tables look up by insertion order; anonymous tables give each append its own identity.(source)

NamedEntries<V> provides insertion-order lookup and dynamic iteration, and duplicate errors are handled by the caller: the layer does not make deduplication decisions for you.

AnonymousEntries<V> assigns a unique identity per append, so equal values remain independent entries.

Iteration semantics match across both: within one non-empty table lifetime, iterators can observe later changes; once the table is cleared, existing iterators stop observing new insertions. That boundary is how you detect “is anything still writing after unload”.

Both return idempotent revokers that map exactly to their entry. Their shared implementation interface EntryValues is not public, so do not try to bypass entry identity through types.

Three different things called scope

Same word, different meanings: confirm which one you are reading.(source)

  • The registry layer here in packages/core/scope decides visibility and lifecycle ownership by ScopeKey;
  • The settings scope is a SettingsNamespace concept about which namespace owns a configuration key;
  • The client Slot scope governs where an injected component is visible.

All three are called scope, but one manages registry entries, one manages config keys, and one manages UI injection. When something “registered but is not visible”, first ask whether a registry-layer shadow, a missing config value, or a slot scope mismatch is responsible.

Validating two scopes with the same service

Do not guess visibility; register twice and read the merged result.(source)

  1. Create two Scope instances from two distinct ScopeKey objects and confirm their ctx are independent.
  2. Register a named service in the global layer and assert peek(undefined) reflects reality before and after.
  3. Register a same-name service only in scope A, call merge(), and assert A sees the shadow while B still sees the global entry.
  4. Clear A's same-name table and assert its sibling tables stay readable when the layer is not empty.
  5. Call dispose() and assert A's entries disappear while global entries remain; race a second call and confirm both await the same completion.

If step 3 comes out reversed, you probably forgot the merge order: global named entries first, scoped shadows after.

One line to close: identity via ScopeKey, carrier via Scoped, registration through Scope.ctx, merge order from merge(), and teardown only through dispose().

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why is the scope package not a Cordis service in DSH plugin?

Because it only supplies identity, carrier, and layer vocabulary, not runtime state. DSH plugin treats scope as a library primitive; lifecycle design belongs to the agent-scope runtime, while callable API and filtering semantics come from the package README.

What does an empty peek(undefined) mean in DSH plugin?

It means no scoped override layer exists, and reading never creates one. DSH plugin builds exact-scope layers lazily on registration only, so peek reflects real state rather than a placeholder.

Does an empty layer reclaim sibling tables in DSH plugin?

No. DSH plugin reclaims a scoped layer only when the complete ScopeLayer is empty. DSH plugin checks isEmpty() on the whole layer, so one empty table never takes its siblings down.

Does DSH plugin AnonymousEntries deduplicate equal values?

No. DSH plugin assigns a unique identity to every append, so equal values stay independent. DSH plugin NamedEntries looks up by insertion order and leaves duplicate errors to the caller.

Related Terms

ScopeKey
ScopeKey is DSH plugin's opaque identity-compared scope key; the primitive never inspects the object itself.— packages/core/scope/src/index.ts
Scoped<T>
Scoped<T> is a compile-time brand on the opaque routing receiver returned by scopeTarget(base, key); it checks dispatch and exposes no subject properties.— packages/core/scope/src/index.ts
rawDispose
rawDispose is the exact Cordis disposer retained on Scope, used when nesting the scope inside an ordered composite effect.— packages/core/scope/src/index.ts
ScopedLayers<L>
ScopedLayers<L> owns an immediately created global layer and lazily created exact-scope layers; merge materializes global named entries first, then scoped shadows.— packages/core/scope/src/store.ts

Sources