@deepseek-ai/dsh-typert-registry 0.1.6-alpha.1 → 0.1.6-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/registry/README.md
-README.md: c1ab98ae8ebe720a29eb4fb339f39e00ce593120
-README.zh.md: 7bf90ff8fd02c4fb17c4f57d1af251a7a4bd3116
+README.md: 75a3d2bc495db97067818fe9c16e835e8e1f98bc
+README.zh.md: b47d735c17ca4e51f41c82916a4b402ddf84e853

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "The runtime Typert registry: stores generated package reflection, live Zod schemas, and Remote invocation descriptors, and resolves them for consumers."
+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"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-typert-registry` makes generated Typert artifacts queryable at runtime: each package's reflection — services, events, and objects — its live Zod schemas, and Remote invocation descriptors live under stable keys that consumers can query or resolve on demand. 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.
+`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
 
@@ -37,7 +37,7 @@ Load the registry plugin; the Client face is installed the same way by the Clien
 
 ### 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?)`. `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 a live Zod schema to JSON Schema without caching.
+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
 
@@ -72,7 +72,7 @@ Each sub-registry publishes `TypertRegistryChange` events to subscribed listener
 
 ### Identity and validation
 
-Keys are stable: `<package>#<face>` for reflection, `<package>#<name>` for schemas, and `<namespace>/<method>` 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; strict codecs must carry a parseable schema.
+Keys are stable: `<package>#<face>` for reflection, `<package>#<name>` for schemas, and `<namespace>/<method>` 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
 

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "运行时 Typert 注册表：保存生成的包反射、实时 Zod schema 与 Remote 调用描述符，并按需为消费方解析。"
+description: "运行时 Typert 注册表：保存生成的包反射、惰性 Zod schema factory 与 Remote 调用描述符，并按需为消费方解析。"
 kind: "package-reference"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-typert-registry` 让生成的 Typert 产物在运行时可按需查询：每个包的反射——服务、事件与对象——其实时 Zod schema 与 Remote 调用描述符都保存在稳定键下，消费方可以按需查询或解析。注册是原子且按 fiber 作用域的：贡献要么整体落地要么完全不落地，并在注册组件卸载时自动撤销。同一服务还托管 Remote 调用所经由的 lookup 与作用域 Context 提供方注册表。它不执行 TypeScript 分析，也不生成 schema；这些由生成器与 loader 负责。
+`dsh-typert-registry` 让生成的 Typert 产物在运行时可按需查询：每个包的反射、惰性 Zod schema factory 与 Remote 调用描述符都保存在稳定键下。消费方首次请求 schema 时才会物化并缓存它。注册是原子且按 fiber 作用域的：贡献要么整体落地要么完全不落地，并在注册组件卸载时自动撤销。同一服务还托管 Remote 调用所经由的 lookup 与作用域 Context 提供方注册表。它不执行 TypeScript 分析，也不生成 schema；这些由生成器与 loader 负责。
 
 ## 目录
 
@@ -37,7 +37,7 @@ kind: "package-reference"
 
 ### 查询 schema 与反射
 
-消费方用 `get(key)`、`resolve(key)` 或 `list(filter?)` 读取 schema，用 `getPackage(name, face?)` 或 `listPackages(filter?)` 读取包反射。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包，各自给出不同的错误。`toJSONSchema(key)` 把实时 Zod schema 投影为 JSON Schema，且不缓存结果。
+消费方用 `get(key)`、`resolve(key)` 或 `list(filter?)` 读取 schema，用 `getPackage(name, face?)` 或 `listPackages(filter?)` 读取包反射。首次读取会物化一个进程 realm 内的 schema 实例，后续读取复用该实例。`resolve()` 能区分格式错误的键、未注册的包，以及已注册但未以该名称提供 schema 的包，各自给出不同的错误。`toJSONSchema(key)` 把已物化的 Zod schema 投影为 JSON Schema，但不缓存该投影。
 
 ### 注册贡献
 
@@ -72,7 +72,7 @@ Remote 调用通过 `ctx.typert.lookups` 与 `ctx.typert.contexts` 解析 Host
 
 ### 标识与校验
 
-键是稳定的：反射用 `<package>#<face>`，schema 用 `<package>#<name>`，端点用 `<namespace>/<method>`。校验会拒绝含 `#` 的名称、超出 RPC 端点段文法的 wire 名称、重复键，以及在其注册表生命周期内改变 wire 声明的 lookup 定义；严格编解码器必须携带可解析的 schema。
+键是稳定的：反射用 `<package>#<face>`，schema 用 `<package>#<name>`，端点用 `<namespace>/<method>`。校验会拒绝含 `#` 的名称、超出 RPC 端点段文法的 wire 名称、重复键，以及在其注册表生命周期内改变 wire 声明的 lookup 定义；schema 条目与严格编解码器必须携带 factory。
 
 ### 源码地图
 

package/lib/client.js

@@ -1211,20 +1211,21 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			/**
 			* Look up one schema by `<package>#<name>`.
 			* @param key - global schema key.
-			* @returns the live schema record, or `undefined` when absent.
+			* @returns a record containing the cached schema, or `undefined` when absent.
 			*/
 			get(key) {
-				return this.schemas.get(key);
+				const record = this.schemas.get(key);
+				return record === void 0 ? void 0 : materializeSchema(record);
 			}
 			/**
 			* Resolve one required schema.
 			* @param key - global schema key.
-			* @returns the live schema record.
+			* @returns a record containing the cached schema.
 			* @throws when the key is malformed, the package face is absent, or the schema is not contributed.
 			*/
 			resolve(key) {
 				const record = this.schemas.get(key);
-				if (record !== void 0) return record;
+				if (record !== void 0) return materializeSchema(record);
 				const hash = key.indexOf("#");
 				if (hash <= 0 || hash === key.length - 1) throw new Error(`typert: invalid schema key "${key}" — expected "<package>#<name>"`);
 				const packageName = key.slice(0, hash);
@@ -1234,10 +1235,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			/**
 			* Enumerate live schemas in registration order.
 			* @param filter - optional package and face restriction.
-			* @returns matching schema records.
+			* @returns matching records containing the cached schemas.
 			*/
 			list(filter = {}) {
-				return [...this.schemas.values()].filter((record) => matches(record, filter));
+				return [...this.schemas.values()].filter((record) => matches(record, filter)).map(materializeSchema);
 			}
 			/**
 			* Look up generated reflection for one package face.
@@ -1283,6 +1284,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				const batch = /* @__PURE__ */ new Set();
 				for (const schema of contribution.schemas) {
 					validateSegment("schema name", schema.name);
+					if (typeof schema.create !== "function") throw new Error(`typert: schema "${schema.name}" has no create() factory`);
 					const key = typertKey(contribution.package, schema.name);
 					if (batch.has(key) || this.schemas.has(key)) throw new Error(`typert: schema "${key}" is already registered`);
 					batch.add(key);
@@ -1296,6 +1298,16 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				return records;
 			}
 		};
+		function materializeSchema(record) {
+			const schema = record.value ??= record.create();
+			return {
+				name: record.name,
+				schema,
+				package: record.package,
+				face: record.face,
+				key: record.key
+			};
+		}
 		function matches(record, filter) {
 			return (filter.package === void 0 || record.package === filter.package) && (filter.face === void 0 || record.face === filter.face);
 		}
@@ -1339,7 +1351,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		function validateCodec(codec, subject) {
 			if (codec.mode === "src-json") return;
 			validateNonempty(`${subject} type symbol`, codec.typeSymbol);
-			if (typeof codec.schema.parse !== "function") throw new Error(`typert: ${subject} strict codec has no parse() method`);
+			if (typeof codec.create !== "function") throw new Error(`typert: ${subject} strict codec has no create() factory`);
 		}
 		function validateWireName(subject, value) {
 			if (value === "." || value === ".." || !/^[A-Za-z0-9_$.-]+$/.test(value)) throw new Error(`typert: invalid ${subject} "${value}" — must contain only RPC endpoint segment characters`);

package/lib/index.js

@@ -419,20 +419,21 @@ var TypertRegistry = class extends Service {
 	/**
 	* Look up one schema by `<package>#<name>`.
 	* @param key - global schema key.
-	* @returns the live schema record, or `undefined` when absent.
+	* @returns a record containing the cached schema, or `undefined` when absent.
 	*/
 	get(key) {
-		return this.schemas.get(key);
+		const record = this.schemas.get(key);
+		return record === void 0 ? void 0 : materializeSchema(record);
 	}
 	/**
 	* Resolve one required schema.
 	* @param key - global schema key.
-	* @returns the live schema record.
+	* @returns a record containing the cached schema.
 	* @throws when the key is malformed, the package face is absent, or the schema is not contributed.
 	*/
 	resolve(key) {
 		const record = this.schemas.get(key);
-		if (record !== void 0) return record;
+		if (record !== void 0) return materializeSchema(record);
 		const hash = key.indexOf("#");
 		if (hash <= 0 || hash === key.length - 1) throw new Error(`typert: invalid schema key "${key}" — expected "<package>#<name>"`);
 		const packageName = key.slice(0, hash);
@@ -442,10 +443,10 @@ var TypertRegistry = class extends Service {
 	/**
 	* Enumerate live schemas in registration order.
 	* @param filter - optional package and face restriction.
-	* @returns matching schema records.
+	* @returns matching records containing the cached schemas.
 	*/
 	list(filter = {}) {
-		return [...this.schemas.values()].filter((record) => matches(record, filter));
+		return [...this.schemas.values()].filter((record) => matches(record, filter)).map(materializeSchema);
 	}
 	/**
 	* Look up generated reflection for one package face.
@@ -491,6 +492,7 @@ var TypertRegistry = class extends Service {
 		const batch = /* @__PURE__ */ new Set();
 		for (const schema of contribution.schemas) {
 			validateSegment("schema name", schema.name);
+			if (typeof schema.create !== "function") throw new Error(`typert: schema "${schema.name}" has no create() factory`);
 			const key = typertKey(contribution.package, schema.name);
 			if (batch.has(key) || this.schemas.has(key)) throw new Error(`typert: schema "${key}" is already registered`);
 			batch.add(key);
@@ -504,6 +506,16 @@ var TypertRegistry = class extends Service {
 		return records;
 	}
 };
+function materializeSchema(record) {
+	const schema = record.value ??= record.create();
+	return {
+		name: record.name,
+		schema,
+		package: record.package,
+		face: record.face,
+		key: record.key
+	};
+}
 function matches(record, filter) {
 	return (filter.package === void 0 || record.package === filter.package) && (filter.face === void 0 || record.face === filter.face);
 }
@@ -547,7 +559,7 @@ function validateInvocation(descriptor) {
 function validateCodec(codec, subject) {
 	if (codec.mode === "src-json") return;
 	validateNonempty(`${subject} type symbol`, codec.typeSymbol);
-	if (typeof codec.schema.parse !== "function") throw new Error(`typert: ${subject} strict codec has no parse() method`);
+	if (typeof codec.create !== "function") throw new Error(`typert: ${subject} strict codec has no create() factory`);
 }
 function validateWireName(subject, value) {
 	if (value === "." || value === ".." || !/^[A-Za-z0-9_$.-]+$/.test(value)) throw new Error(`typert: invalid ${subject} "${value}" — must contain only RPC endpoint segment characters`);

package/lib/types/service.d.ts

@@ -60,20 +60,20 @@ export declare class TypertRegistry extends Service implements TypertRegistryCon
     /**
      * Look up one schema by `<package>#<name>`.
      * @param key - global schema key.
-     * @returns the live schema record, or `undefined` when absent.
+     * @returns a record containing the cached schema, or `undefined` when absent.
      */
     get(key: string): TypertSchemaRecord | undefined;
     /**
      * Resolve one required schema.
      * @param key - global schema key.
-     * @returns the live schema record.
+     * @returns a record containing the cached schema.
      * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
      */
     resolve(key: string): TypertSchemaRecord;
     /**
      * Enumerate live schemas in registration order.
      * @param filter - optional package and face restriction.
-     * @returns matching schema records.
+     * @returns matching records containing the cached schemas.
      */
     list(filter?: TypertSchemaFilter): TypertSchemaRecord[];
     /**

package/lib/types/service.js

@@ -417,21 +417,22 @@ export class TypertRegistry extends Service {
     /**
      * Look up one schema by `<package>#<name>`.
      * @param key - global schema key.
-     * @returns the live schema record, or `undefined` when absent.
+     * @returns a record containing the cached schema, or `undefined` when absent.
      */
     get(key) {
-        return this.schemas.get(key);
+        const record = this.schemas.get(key);
+        return record === undefined ? undefined : materializeSchema(record);
     }
     /**
      * Resolve one required schema.
      * @param key - global schema key.
-     * @returns the live schema record.
+     * @returns a record containing the cached schema.
      * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
      */
     resolve(key) {
         const record = this.schemas.get(key);
         if (record !== undefined)
-            return record;
+            return materializeSchema(record);
         const hash = key.indexOf('#');
         if (hash <= 0 || hash === key.length - 1) {
             throw new Error(`typert: invalid schema key "${key}" — expected "<package>#<name>"`);
@@ -445,10 +446,10 @@ export class TypertRegistry extends Service {
     /**
      * Enumerate live schemas in registration order.
      * @param filter - optional package and face restriction.
-     * @returns matching schema records.
+     * @returns matching records containing the cached schemas.
      */
     list(filter = {}) {
-        return [...this.schemas.values()].filter(record => matches(record, filter));
+        return [...this.schemas.values()].filter(record => matches(record, filter)).map(materializeSchema);
     }
     /**
      * Look up generated reflection for one package face.
@@ -498,6 +499,9 @@ export class TypertRegistry extends Service {
         const batch = new Set();
         for (const schema of contribution.schemas) {
             validateSegment('schema name', schema.name);
+            if (typeof schema.create !== 'function') {
+                throw new Error(`typert: schema "${schema.name}" has no create() factory`);
+            }
             const key = typertKey(contribution.package, schema.name);
             if (batch.has(key) || this.schemas.has(key)) {
                 throw new Error(`typert: schema "${key}" is already registered`);
@@ -513,6 +517,16 @@ export class TypertRegistry extends Service {
         return records;
     }
 }
+function materializeSchema(record) {
+    const schema = record.value ??= record.create();
+    return {
+        name: record.name,
+        schema,
+        package: record.package,
+        face: record.face,
+        key: record.key,
+    };
+}
 function matches(record, filter) {
     return (filter.package === undefined || record.package === filter.package)
         && (filter.face === undefined || record.face === filter.face);
@@ -578,8 +592,8 @@ function validateCodec(codec, subject) {
     if (codec.mode === 'src-json')
         return;
     validateNonempty(`${subject} type symbol`, codec.typeSymbol);
-    if (typeof codec.schema.parse !== 'function') {
-        throw new Error(`typert: ${subject} strict codec has no parse() method`);
+    if (typeof codec.create !== 'function') {
+        throw new Error(`typert: ${subject} strict codec has no create() factory`);
     }
 }
 function validateWireName(subject, value) {

package/lib/types/types.d.ts

@@ -60,22 +60,25 @@ export interface TypertPackageModel {
     readonly events: readonly TypertEventModel[];
     readonly objects: readonly TypertObjectModel[];
 }
-/** One generated live Zod schema. */
-export interface TypertSchema {
+/** One generated Zod schema factory. */
+export interface TypertSchemaFactory {
     readonly name: string;
-    readonly schema: z.ZodType;
+    /** Materialize and return the process-realm schema on first use. */
+    readonly create: () => z.ZodType;
 }
 /** One generated package contribution registered and withdrawn atomically. */
 export interface TypertContribution {
     readonly package: string;
     readonly face: TypertFace;
-    readonly schemas: readonly TypertSchema[];
+    readonly schemas: readonly TypertSchemaFactory[];
     readonly model: TypertPackageModel;
     /** Host invocation definitions, empty when the package exports no Remote methods. */
     readonly invocations: readonly InvocationDescriptor[];
 }
 /** A live schema plus its contribution identity. */
-export interface TypertSchemaRecord extends TypertSchema {
+export interface TypertSchemaRecord {
+    readonly name: string;
+    readonly schema: z.ZodType;
     readonly package: string;
     readonly face: TypertFace;
     readonly key: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-registry",
   "description": "Runtime registry for generated package reflection and Zod schemas",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -50,8 +50,8 @@
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2"
   },
   "scripts": {
     "bundle": "tsdown",