ChatGPTClaudeGrok / X / CursorGemini

Cordis Registry vs Service: Which Lookup Should You Use?

Plugin DevelopmentPublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH pluginCordis RegistryCordis Serviceplugins
Cordis Registry and Service both look up by name, but one manages a collection and one provides a capability. Compare lookup, lifecycle, and three examples.

Registry and Service both “find something by name,” which is why they get mixed up. Their centers differ: a Registry manages a collection under a key, while a Service provides one capability. Choosing wrong does not fail immediately; it shows up in multiple implementations, enumeration, or backend replacement (source).

DeepSeek Harness: Two primitives: collection vs capability

One sentence: a Registry answers “what exists,” a Service answers “which one to use.” A Registry cares about a set of entries, multiple implementations, scope enumeration, and filtering. A Service cares about a single capability: a consumer injects a name and gets a usable implementation. (source)

The shape follows:

  • Registry — entries are data, lookup returns a collection; the same key can have several entries, and order and scope matter.
  • Service — an entry is a capability, lookup returns one implementation; usually one provider is active per name.

Using a Service as a Registry means “the second registration overrides the first,” or consumers see only one. Using a Registry as a Service forces consumers to choose from a set every time.

Ask: does the consumer need to see several, or only one? Several means Registry; one means Service.

DeepSeek Harness: Lookup models

Different lookup models produce different consumer code. Compare (source):

DimensionRegistryService
ResultA collection, possibly emptyOne implementation or unavailable
Multiple per keyYesUsually no
EnumerationYesNot needed
Scope filteringYesAffected by injection scope
Consumer concernWhich entryIs a capability available

An empty Registry and an unavailable Service also mean different things: no matching entry versus no provider for the capability. Do not merge them while debugging.

The model also changes fallback. An empty Registry can degrade to a no-op; an unavailable Service usually rejects or waits, because the consumer has no alternative.

Lookup timing matters: a Registry often takes a snapshot at operation start, while a Service takes a stable handle at injection. Neither should look up on every call unless dynamic change is required.

DeepSeek Harness: Lifecycle

Both are side effects, but the undo granularity differs. In Cordis, registration is removed with the plugin fiber; a Registry removes one entry, a Service removes the provider for the whole capability (source).

Three consequences:

  1. Registry entries can be added and removed individually — useful for discovery and conditional registration.
  2. Service providers are usually replaced as a whole — remove the old provider, register the new one.
  3. Do not hold a registration handle outside apply — it creates “unloaded but still findable.”

Service replacement has a race: while old and new providers coexist, a consumer may get the old one. Remove first, then register, or make consumers wait during the switch.

Registry removal has a similar issue: without a consistent snapshot, a consumer can see an intermediate set. Consumers that need consistency should read once, not iterate while expecting stability.

DeepSeek Harness: Three examples

Three examples cover most choices. Compare the requirement to pick (source):

  1. Tool registration — each tool is an entry; the model needs all tools and calls by name. Use a Registry: multiple entries, enumerable, name lookup.
  2. Multiple backends — filesystem, shell, and terminal may have several providers, and the consumer uses the active one. Use a Service: one capability, one active provider, replaceable.
  3. Singleton service — settings, sessions, and credentials usually have one implementation. Use a Service: the consumer injects a name and does not care how many exist.

Tool registration is the most common wrong Service. Making tools a Service produces “only one tool” or “the second registration overrides the first.” Tools are a collection, not a singleton.

Multiple backends are the most common wrong Registry. A Registry forces the consumer to choose each time; if the deployment allows one backend, a Service is simpler.

A mixed case: the capability is a singleton, but it maintains a collection internally. For example, a “tool registry service” exposes lookup methods and stores entries in a Registry. Ask whether the consumer needs enumeration: if yes, expose an enumeration method on the Service rather than leaking the Registry.

DeepSeek Harness: Common misuses

Three misuses are common and recognizable. They save debugging time (source):

  • A Service used as a collection — later registrations override earlier ones; “one tool/plugin is missing.”
  • A Registry used as a singleton — consumers must choose and sometimes choose wrong; “the capability comes and goes.”
  • A registration handle held outside apply — findable after unload; “the plugin is disabled but the feature still works.”

All three confuse a collection with a capability. Ask “how many does the consumer need” before choosing.

A subtler misuse: storing mutable objects in a Registry and modifying them outside. A Registry manages registration and lookup, not object state; the provider should own state and expose methods through a Service.

DeepSeek Harness: Verify from the consumer

Verify the choice from the consumer, not the registration code. Three steps (source):

  1. Replacement — change the provider; does the consumer need code changes? A Service should not, a Registry usually does.
  2. Enumeration — does the consumer need all entries? Yes means Registry; no means Service.
  3. Unload — after removing the provider, does the consumer get an explicit unavailable or empty state? If it still holds the old object, a handle leaked.

All three mean the choice is sound. Passing only registration usually means “it runs, but breaks on another deployment.”

The existing develop-scope-registry covers scope and visibility, and develop-plugin-service-definition covers service splitting; this article covers the Registry-vs-Service choice. Separate collections from capabilities before discussing registration details.

One question decides the primitive: does the consumer need several entries or one capability? Answer that, and the code stops oscillating.

Consumer first, primitive second.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What is the core difference between a Cordis Registry and a Service in DeepSeek Harness?

In DeepSeek Harness, a Cordis Registry manages a keyed collection for multiple implementations and enumeration; a Service provides one named capability for a single or replaceable backend.

Should multiple implementations under one key use a Registry or a Service in DeepSeek Harness?

In DeepSeek Harness, use a Registry. A Cordis Registry supports multiple entries and enumeration; a Service fits one provider per capability, with backend selection rather than same-name overrides.

How is a Cordis Service registration removed when a DeepSeek Harness plugin unloads?

In DeepSeek Harness, a Service registration is a plugin side effect and is removed with the fiber. Do not keep a registration handle outside apply, or the service may remain findable after unload.

Why does a DeepSeek Harness Registry lookup return an empty array?

In DeepSeek Harness, a Cordis Registry filters by key and scope. An empty result can mean no match, the wrong scope, or a provider that has not loaded; it does not always mean registration failed.

Related Terms

Registry
A Registry is a Cordis primitive for managing multiple keyed registrations, useful for enumeration, multiple implementations, and scope filtering.— DeepSeek Harness reference - Plugin Registry
Service
A Service is a Cordis primitive that contributes one named capability to the shared context; consumers inject it and providers can be replaced.— DeepSeek Harness reference - Service
scope
Scope is a Cordis visibility boundary; lookups in both Registry and Service can depend on the active scope.— DeepSeek Harness reference - Plugin Registry
consumer
A consumer is the plugin or code that uses a capability; from its view, replaceability matters more than the registration primitive.— DeepSeek Harness reference - Service

Sources