@deepseek-ai/dsh-typert-protocol 0.1.5-rc.2 → 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/protocol/README.md
-README.md: 43147c2c2f1746ff0c806c0842b5dba65457775a
-README.zh.md: 0633db1a9e95d9abda8131fec0f1cf659c484910
+README.md: e41fa9fa305d8f55ce55d3eace647ad5afcea0e3
+README.zh.md: e784e771016ebec0913e0ea847258fe653ae3bd0

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-With `dsh-typert-protocol`, business packages can expose Host methods to Remote clients: mark a method with `@Remote` (or `@RemoteScope` for scoped receivers), bind the service to a wire namespace, and associate Host objects and scoped Contexts with wire identities through the merge-extensible protocol maps. Generated artifacts, the Host Gateway, and the Client API consume the same invocation descriptors, codecs, and provider contracts, so one declaration set stays in sync across every face. The package registers no Cordis service and runs no TypeScript analysis; it declares types and decorator markers only.
+With `dsh-typert-protocol`, business packages can expose Host methods to Remote clients: mark a method with `@Remote` (or `@RemoteScope` for scoped receivers), bind the service to a wire namespace, and associate Host objects and scoped Contexts with wire identities through the merge-extensible protocol maps. Generated artifacts, the Host Gateway, and the Client API consume the same invocation descriptors, codecs, and provider contracts. Invocation-owned values transfer cleanup to Gateway without adding a reference count. The package registers no Cordis service and runs no TypeScript analysis.
 
 ## Table of Contents
 
@@ -48,6 +48,8 @@ Generation turns the method into a wire endpoint under the service's namespace;
 
 Complex Host objects cannot cross the wire directly. A business package declares the association through the merge-extensible `TypertLookupMap` and `TypertContextMap`. A Host Context adapter owns the stable wire declaration and resolves wire identities to live Contexts. A Client Context adapter maps in both directions because scoped calls originate from a Client Context and forwarded Host events resolve their explicit wire identity there. Host composition may override its synchronous or asynchronous resolver. A resolver that refuses on policy grounds throws `RemoteError` with its own code, which reaches the caller unchanged.
 
+Client Context resolution is synchronous. `typertOwnedValue(value, release)` transfers a non-throwing, idempotent cleanup to the invocation owner; Gateway calls it after handler and reply settlement. A borrowed Context requires no cleanup wrapper. The shared `TYPERT_OWNED_VALUE` symbol and `isTypertOwnedValue` recognizer work across independently bundled providers and Gateway; the wrapper itself does not retain a resource.
+
 ### Reporting and reading a Remote failure
 
 One class carries every Remote failure: `RemoteError`, holding a stable `<domain>/<reason>` code and the details typed for that code. This package declares the universal carrier codes (`gateway/bad-request`, `gateway/cancelled`, `gateway/internal`) and owns `RemoteErrorDetailsMap`, the merge-extensible table every other package extends beside its own throwing code:
@@ -91,7 +93,7 @@ The merge-extensible protocol maps keep static associations in the type system,
 
 ### Wire identity grammar
 
-Every namespace, method, lookup, and Context segment must satisfy `isTypertRemoteSegment()`, so generated names cross the shared RPC carrier unchanged. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
+Every namespace, method, lookup, and Context segment must satisfy `isTypertRemoteSegment()`, so generated names cross the shared RPC carrier unchanged. Strict codecs carry generated schema factories; `src-json` codecs identify the weaker source-launch path.
 
 ### Source map
 

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-借助 `dsh-typert-protocol`，业务包可以向 Remote 客户端暴露 Host 方法：用 `@Remote`（作用域接收者用 `@RemoteScope`）标记方法，把服务绑定到 wire 命名空间，并通过可合并扩展的协议映射把 Host 对象与作用域 Context 关联到 wire identity。生成产物、Host Gateway 与 Client API 消费同一套调用描述符、编解码器与提供方约定，因此一套声明在每个 face 上保持一致。本包不注册任何 Cordis 服务，也不运行 TypeScript 分析；它只声明类型与装饰器标记。
+借助 `dsh-typert-protocol`，业务包可以向 Remote 客户端暴露 Host 方法：用 `@Remote`（作用域接收者用 `@RemoteScope`）标记方法，把服务绑定到 wire 命名空间，并通过可合并扩展的协议映射把 Host 对象与作用域 Context 关联到 wire identity。生成产物、Host Gateway 与 Client API 消费同一套调用描述符、编解码器与提供方约定。调用持有的值把清理责任交给 Gateway，不另增引用计数。本包不注册任何 Cordis 服务，也不运行 TypeScript 分析。
 
 ## 目录
 
@@ -46,7 +46,9 @@ export class GoalService extends TypertRemoteService {
 
 ### 把 Host 对象与 Context 关联到 wire identity
 
-复杂的 Host 对象不能直接跨 wire 传输。业务包通过可合并扩展的 `TypertLookupMap` 与 `TypertContextMap` 声明关联。Host Context adapter 拥有稳定 wire 声明，并把 wire identity 解析为活跃 Context。Client Context adapter 需要双向映射，因为作用域调用从 Client Context 发起，而转发的 Host 事件要在 Client 侧解析其显式 wire identity。Host 组合可以覆盖其同步或异步 resolver。因策略而拒绝的 resolver 抛出带自有码的 `RemoteError`，该码原样到达调用方。
+复杂的 Host 对象不能直接跨 wire 传输。业务包通过可合并扩展的 `TypertLookupMap` 与 `TypertContextMap` 声明关联。Host Context 适配器拥有稳定 wire 声明，并把 wire identity 解析为活跃 Context。Client Context 适配器需要双向映射，因为作用域调用从 Client Context 发起，而转发的 Host 事件要在 Client 侧解析其显式 wire identity。Host 组合可以覆盖其同步或异步解析器。因策略原因拒绝解析的解析器会抛出带有自身错误码的 `RemoteError`，该码原样到达调用方。
+
+Client Context 解析保持同步。`typertOwnedValue(value, release)` 把不抛异常、幂等的清理交给调用 owner；Gateway 在处理器和回复均结束后调用它。借用的 Context 不需要清理包装层。共享的 `TYPERT_OWNED_VALUE` symbol 与 `isTypertOwnedValue` 识别函数可跨独立打包的提供方与 Gateway 使用；包装层自身不会 retain 资源。
 
 ### 报告与读取 Remote 失败
 
@@ -65,7 +67,7 @@ throw new RemoteError('goal/not-found', `goal "${id}" does not exist`, { goalId:
 
 ### 在 Client 侧接收转发的 Host 事件
 
-Host 装配以转发给消费端的 Cordis 事件扩展 `TypertRemoteEventSelection`，从而收窄 `ctx.remote.$on` 的键集。`TypertForwardableEvent` 接受无作用域且返回 `void` 的通知，以及最后一个 `next()` 回调返回事件结果类型的异步作用域 waterfall。`TypertClientEventListener` 从同一条 `Events` 成员派生 Client listener，并保留 signal、可选和只读字段、数组、回调与结果类型。`TypertClientRemote` 只公开 `$mount()` 与 `$on()`；事件传输仍由 Gateway 私有持有。
+Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelection`，从而收窄 `ctx.remote.$on` 的键集。`TypertForwardableEvent` 接受无作用域且返回 `void` 的通知，以及最后一个 `next()` 回调返回事件结果类型的异步作用域 waterfall（瀑布式事件）。`TypertClientEventListener` 从同一条 `Events` 成员派生 Client listener，并保留 signal、可选和只读字段、数组、回调与结果类型。`TypertClientRemote` 只公开 `$mount()` 与 `$on()`；事件传输仍由 Gateway 私有持有。
 
 -----
 
@@ -83,7 +85,7 @@ Host 装配以转发给消费端的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 ### Remote 标记
 
-`@Remote` 与 `@RemoteScope` 调度一个初始化器，把方法名、可选导出名与调用模式追加到原型描述符；`remoteMethods(service)` 校验其版本，并返回与已存描述符分离、按声明顺序排列的快照，供 Gateway 的源码模式回退读取。标记要求公开、非静态、具名字符串的实例方法，同一方法上的冲突标记会被拒绝。
+`@Remote` 与 `@RemoteScope` 调度一个初始化器，把方法名、可选导出名与调用模式追加到原型描述符；`remoteMethods(service)` 校验其版本，并返回与已存描述符分离、按声明顺序排列的快照，供 Gateway 的源码模式回退读取。标记要求名称为字符串的公开、非静态实例方法，同一方法上的冲突标记会被拒绝。
 
 ### 协议映射与描述符
 
@@ -91,7 +93,7 @@ Host 装配以转发给消费端的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 ### Wire 标识文法
 
-每个命名空间、方法、查找与 Context 段都必须满足 `isTypertRemoteSegment()`，生成的名字才能原样跨共享 RPC 载体传输。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+每个命名空间、方法、查找与 Context 段都必须满足 `isTypertRemoteSegment()`，生成的名字才能原样跨共享 RPC 载体传输。严格编解码器携带生成的 schema factory；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ### 源码地图
 

package/lib/index.js

@@ -37,6 +37,37 @@ function remoteErrorOf(value) {
 	if (typeof value === "object" && value !== null && value.isDSHRemoteError === true && typeof value.code === "string") return value;
 }
 //#endregion
+//#region lib/types/owned-value.js
+/** Generic invocation-owned values returned by synchronous Client Context resolvers. */
+/** Shared identity across independently bundled Context providers and Gateway. */
+const TYPERT_OWNED_VALUE = Symbol.for("dsh.typert.owned-value");
+/**
+* Transfer cleanup ownership without adding another resource reference count.
+* @param value - resolved payload passed to the invocation.
+* @param release - non-throwing synchronous release, called at most once.
+* @returns an owned payload disposed after invocation and reply settlement.
+*/
+function typertOwnedValue(value, release) {
+	let active = true;
+	return {
+		[TYPERT_OWNED_VALUE]: true,
+		value,
+		[Symbol.dispose]() {
+			if (!active) return;
+			active = false;
+			release();
+		}
+	};
+}
+/**
+* Identify invocation-owned values using the shared marker.
+* @param value - borrowed or owned resolver result.
+* @returns whether the result carries invocation cleanup.
+*/
+function isTypertOwnedValue(value) {
+	return typeof value === "object" && value !== null && TYPERT_OWNED_VALUE in value && value[TYPERT_OWNED_VALUE] === true;
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Remote decorators and explicit Gateway bindings backed by versioned
@@ -181,4 +212,4 @@ function validateName(subject, value) {
 	if (!isTypertRemoteSegment(value)) throw new TypeError(`typert-protocol: ${subject} must contain only RPC endpoint segment characters`);
 }
 //#endregion
-export { Remote, RemoteError, RemoteScope, TypertRemoteService, bindTypertRemote, isTypertRemoteSegment, remoteErrorOf, remoteMethods };
+export { Remote, RemoteError, RemoteScope, TYPERT_OWNED_VALUE, TypertRemoteService, bindTypertRemote, isTypertOwnedValue, isTypertRemoteSegment, remoteErrorOf, remoteMethods, typertOwnedValue };

package/lib/types/index.d.ts

@@ -7,6 +7,8 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import type { TypertContextMap } from './types.ts';
 export { RemoteError, remoteErrorOf } from './remote-error.ts';
+export { TYPERT_OWNED_VALUE, isTypertOwnedValue, typertOwnedValue } from './owned-value.ts';
+export type { TypertOwnedValue } from './owned-value.ts';
 /**
  * Test one generated Remote name against the Connection endpoint grammar.
  * @param value - namespace, method, lookup, or Context segment.

package/lib/types/index.js

@@ -6,6 +6,7 @@
  */
 import { Service } from '@deepseek-ai/cordis';
 export { RemoteError, remoteErrorOf } from "./remote-error.js";
+export { TYPERT_OWNED_VALUE, isTypertOwnedValue, typertOwnedValue } from "./owned-value.js";
 const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 /**
  * Test one generated Remote name against the Connection endpoint grammar.

package/lib/types/owned-value.d.ts

@@ -0,0 +1,22 @@
+/** Generic invocation-owned values returned by synchronous Client Context resolvers. */
+/** Shared identity across independently bundled Context providers and Gateway. */
+export declare const TYPERT_OWNED_VALUE: unique symbol;
+/** A borrowed payload paired with the invocation owner's idempotent cleanup. */
+export interface TypertOwnedValue<Value> extends Disposable {
+    readonly [TYPERT_OWNED_VALUE]: true;
+    readonly value: Value;
+}
+/**
+ * Transfer cleanup ownership without adding another resource reference count.
+ * @param value - resolved payload passed to the invocation.
+ * @param release - non-throwing synchronous release, called at most once.
+ * @returns an owned payload disposed after invocation and reply settlement.
+ */
+export declare function typertOwnedValue<Value>(value: Value, release: () => void): TypertOwnedValue<Value>;
+/**
+ * Identify invocation-owned values using the shared marker.
+ * @param value - borrowed or owned resolver result.
+ * @returns whether the result carries invocation cleanup.
+ */
+export declare function isTypertOwnedValue(value: unknown): value is TypertOwnedValue<unknown>;
+//# sourceMappingURL=owned-value.d.ts.map

package/lib/types/owned-value.js

@@ -0,0 +1,32 @@
+/** Generic invocation-owned values returned by synchronous Client Context resolvers. */
+/** Shared identity across independently bundled Context providers and Gateway. */
+export const TYPERT_OWNED_VALUE = Symbol.for('dsh.typert.owned-value');
+/**
+ * Transfer cleanup ownership without adding another resource reference count.
+ * @param value - resolved payload passed to the invocation.
+ * @param release - non-throwing synchronous release, called at most once.
+ * @returns an owned payload disposed after invocation and reply settlement.
+ */
+export function typertOwnedValue(value, release) {
+    let active = true;
+    return {
+        [TYPERT_OWNED_VALUE]: true,
+        value,
+        [Symbol.dispose]() {
+            if (!active)
+                return;
+            active = false;
+            release();
+        },
+    };
+}
+/**
+ * Identify invocation-owned values using the shared marker.
+ * @param value - borrowed or owned resolver result.
+ * @returns whether the result carries invocation cleanup.
+ */
+export function isTypertOwnedValue(value) {
+    return typeof value === 'object' && value !== null
+        && TYPERT_OWNED_VALUE in value && value[TYPERT_OWNED_VALUE] === true;
+}
+//# sourceMappingURL=owned-value.js.map

package/lib/types/types.d.ts

@@ -4,6 +4,7 @@
  * @module @deepseek-ai/dsh-typert-protocol/types
  */
 import type { Context, Events } from '@deepseek-ai/cordis';
+import type { TypertOwnedValue } from './owned-value.ts';
 declare const LOOKUP_HOST: unique symbol;
 declare const LOOKUP_WIRE: unique symbol;
 declare const CONTEXT_WIRE: unique symbol;
@@ -152,7 +153,8 @@ export interface TypertSchema<Output = unknown> {
 export type TypertCodec = {
     readonly mode: 'strict';
     readonly typeSymbol: string;
-    readonly schema: TypertSchema;
+    /** Materialize and return the process-realm schema on first boundary use. */
+    readonly create: () => TypertSchema;
 } | {
     readonly mode: 'src-json';
 };
@@ -305,11 +307,11 @@ export interface TypertClientContextAdapter<Wire = unknown> {
      */
     identity(ctx: Context): Wire | undefined;
     /**
-     * Resolve a wire identity from the Client's currently materialized Contexts.
+     * Resolve a validated identity synchronously for one Client invocation.
      * @param id - validated wire identity.
-     * @returns the Client Context, or `undefined` when unavailable.
+     * @returns a borrowed or invocation-owned Client Context, or undefined when unavailable.
      */
-    resolve(id: Wire): Context | undefined;
+    resolve(id: Wire): Context | TypertOwnedValue<Context> | undefined;
 }
 /** Notification emitted after a Typert runtime registry changes. */
 export interface TypertRegistryChange {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-protocol",
   "description": "Compiler-independent Remote metadata and Typert provider protocols",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },