deepseek-harness/packages/typert/registry/README.md

---

description: "The runtime Typert registry: stores generated package reflection, lazy Zod schema factories, and Remote invocation descriptors, and resolves them for consumers."

kind: "package-reference"

@deepseek-ai/dsh-typert-registry

English | 中文

Summary

dsh-typert-registry makes generated Typert artifacts queryable at runtime: each package's reflection, lazy Zod schema factories, and Remote invocation descriptors live under stable keys. A schema is materialized and cached when a consumer first requests it. Registrations are atomic and fiber-scoped: a contribution lands whole or not at all and is withdrawn automatically when the registering component unloads. The same service hosts the lookup and scoped-Context provider registries that Remote calls resolve through. It performs no TypeScript analysis and generates no schemas; the generator and the loader handle those.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Mount the registry in any Host or Client composition that stores or consumes generated Typert artifacts; it provides ctx.typert. There is no configuration.

Minimal setup

Load the registry plugin; the Client face is installed the same way by the Client runtime's own metadata, and both faces run the same implementation:

- name: '@deepseek-ai/dsh-typert-registry'

Querying schemas and reflection

Consumers read schemas with get(key), resolve(key), or list(filter?) and package reflection with getPackage(name, face?) or listPackages(filter?). The first schema read materializes one process-realm instance; later reads reuse it. resolve() distinguishes a malformed key, an absent package, and a registered package that contributes no schema under that name, each with its own error. toJSONSchema(key) projects the materialized Zod schema to JSON Schema without caching the projection.

Registering a contribution

Generated artifacts register through the loader in Loader compositions; any other owner calls ctx.typert.register(contribution) directly and receives the exact disposer that withdraws it. Duplicate package-face identities, schema keys, invocation ids, or endpoints reject the whole batch before anything is committed.

Lookup and Context providers

Remote calls resolve Host objects and scoped Contexts through ctx.typert.lookups and ctx.typert.contexts. registerHost() installs the Host wire declaration and its wire-to-Context resolver, while configureHost() replaces only that resolver. registerClient() installs the bidirectional Client adapter for the same merge-declared kind. Host-to-Client event sources carry their domain identity explicitly instead of projecting it back from a Context.

---

Understand the implementation

Implementation internals — click to expand

This section explains how the registry stores and owns contributions; the consumer API is covered in [Use this package](#use-this-package). ### Design concept The registry is built on one principle: a contribution is one atomic, fiber-owned commit. `register()` validates the package-face identity, schemas, and invocation descriptors first, then commits everything under a single Cordis effect whose disposer withdraws exactly that contribution. Duplicate identities fail at the owning operation boundary before any state changes. ### Sub-registries - `ctx.typert.local` — current-environment invocation definitions, including `hasSeen()` history for source-mode fallback. - `ctx.typert.remotes` — consumer-selected contributions mounted in the calling fiber. - `ctx.typert.lookups` — lookup providers plus composition-owned resolver overrides per key. - `ctx.typert.contexts` — Host Context providers and Client Context binders per scoped key. Each sub-registry publishes `TypertRegistryChange` events to subscribed listeners; a throwing listener is logged and does not stop later listeners. ### Identity and validation Keys are stable: `#` for reflection, `#` for schemas, and `/` for endpoints. Validation rejects names containing `#`, wire names outside the RPC segment grammar, duplicate keys, and lookup definitions whose wire declaration changes during the registry lifetime; schema entries and strict codecs must carry a factory. ### Source map | File | Role | |---|---| | [`src/service.ts`](src/service.ts) | `TypertRegistry` service, stores, validation, effect wiring | | [`src/types.ts`](src/types.ts) | Contribution, record, and filter types | | [`src/client/index.ts`](src/client/index.ts) | Client face installing the same registry | | — | No runtime invariant companion is published; schema and package-reflection records mutate together inside register/dispose, with no independent event or second data source to cross-check; duplicate identities fail at the owning operation boundary. |

---

Further Exploration

Read these pages when the package-level contract is not enough; they move from the registry to what feeds it and what consumes it.

• Typert loader — automatic registration of generated host artifacts.
• Typert generator — what produces the contributions the registry stores.
• Typert protocol — the descriptors, codecs, and provider contracts the registry serves.
• Typert subsystem reference — the literal ctx.typert contract.
• API Gateway reference — the main consumer of invocation descriptors and providers.

---

Model Experience

None, as this runtime type registry's consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.

KV Cache effect

No direct effect; a consumer that places reflection or schemas in a request owns the resulting prefix change.

Known Limitations and Deferred Work

These limits define what the registry stores and rejects; they are current package constraints, not a task backlog.

• No graph merging — the registry stores generated reflection per face but does not merge host and client graphs or resolve TypeScript references; those are analyzer and emitter concerns.
• Schema keys omit the face — host and client run in separate contexts, so registering same-named schemas from both faces into one context is rejected as a duplicate.
• JSON Schema projection is uncached — toJSONSchema() returns a fresh document per call; consumers that project repeatedly own caching.

Dev Note

Working context for maintainers — click to expand

None.