Cordis Registry vs Service: Which Lookup Should You Use?
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):
| Dimension | Registry | Service |
|---|---|---|
| Result | A collection, possibly empty | One implementation or unavailable |
| Multiple per key | Yes | Usually no |
| Enumeration | Yes | Not needed |
| Scope filtering | Yes | Affected by injection scope |
| Consumer concern | Which entry | Is 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:
- Registry entries can be added and removed individually — useful for discovery and conditional registration.
- Service providers are usually replaced as a whole — remove the old provider, register the new one.
- 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):
- Tool registration — each tool is an entry; the model needs all tools and calls by name. Use a Registry: multiple entries, enumerable, name lookup.
- 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.
- 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):
- Replacement — change the provider; does the consumer need code changes? A Service should not, a Registry usually does.
- Enumeration — does the consumer need all entries? Yes means Registry; no means Service.
- 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.
FAQ
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.
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.
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.
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
- DeepSeek Harness reference - Plugin Registry· deepseek-harness
- DeepSeek Harness reference - Service· deepseek-harness