@deepseek-ai/dsh-typert-protocol 0.1.6-alpha.1 → 0.1.7-alpha.1

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: c88432ff3587cba1a3222a3a4d75cd8fe0e2d514
+README.md: 8a97bb339d462c8dbea7666c7855a7e51ae9b113
+README.zh.md: 9bb2cae765ee5747bf11a92d44ec2bb201b0285d

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
 
@@ -44,10 +44,16 @@ export class GoalService extends TypertRemoteService {
 
 Generation turns the method into a wire endpoint under the service's namespace; Clients call it as a typed method through `ctx.remote` (see the [API Gateway reference](../../../docs/api-gateway.md)). A method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter — the signal is injected, never a JSON parameter or lookup field.
 
+A unary method can return `Uint8Array` directly or within nested objects, arrays, tuples, optional fields, unions, and recursive types. Generation supplies optional result codec `encode()` and `decode()` functions: encoding visits only subtrees whose types can contain bytes, while decoding validates reconstructed values; Client declarations use `Uint8Array<ArrayBuffer>` at every byte position while retaining other field types. Pure JSON results pass through without Host byte detection or Client parsing. Parameters, events, and stream items remain JSON-only; runtime object cycles are unsupported.
+
+A stream method (`@Remote({ mode: 'stream' })`) returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`. `In` declares the items the Client may send back on the same logical stream; the method reads them through `this.ctx.invocation.uplink<In>()`, and the descriptor carries their codec. `RemoteInvocation` also names the receiving `service`, the calling `peer` (a `PeerScope` the connection layer admitted), and the carrier `signal`; `ctx.invocation` is `undefined` on a Context no Remote call derived: the first `bindTypertRemote()` binding in a tree, which every `TypertRemoteService` constructor makes, registers that accessor on the root. A generated Client stream method returns `RemoteStreamHandle<Out, In>`: the handle with `send`, `end`, and `dispose` beside the downlink iteration. Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through.
+
 ### Associating Host objects and Contexts with wire identities
 
 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:
@@ -87,19 +93,20 @@ The package keeps strict reflection in the compiler: decorator initializers reta
 
 ### Protocol maps and descriptors
 
-The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, cancellation, and result codecs.
+The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, the uplink codec, cancellation, and result codecs.
 
 ### 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
 
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Decorators, Gateway bindings, `remoteMethods`, segment validation |
+| [`src/json-value.ts`](src/json-value.ts) | `isRemoteJsonValue` and `isRemoteUplinkItem`, the lossless JSON checks every carrier shares |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` and the structural `remoteErrorOf` recognizer |
-| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
+| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `RemoteStream`, `RemoteStreamHandle`, `PeerScope`, `RemoteInvocation`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
 | — | No runtime invariant companion is published; decorators retain private immutable declarations and bindings are frozen values with no independent event stream to cross-check. |
 
 </details>

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 分析。
 
 ## 目录
 
@@ -44,10 +44,16 @@ export class GoalService extends TypertRemoteService {
 
 生成会把方法变为服务命名空间下的 wire 端点；Client 通过 `ctx.remote` 以类型化方法调用它（见 [API Gateway 参考](../../../docs/api-gateway.zh.md)）。方法把 `signal: AbortSignal` 声明为最后一个参数即可选择协作式取消——该信号是注入的，绝不会成为 JSON 参数或查找字段。
 
+一元方法可以直接返回 `Uint8Array`，也可以将其放在嵌套对象、数组、元组、可选字段、联合类型和递归类型中。生成器提供可选的结果 codec `encode()` 和 `decode()`：编码仅访问类型可能包含字节的子树，解码则校验还原后的值；Client 声明在每个字节位置使用 `Uint8Array<ArrayBuffer>`，同时保留其他字段类型。纯 JSON 结果不经 Host 字节识别或 Client 解析直接传递。参数、事件与流条目仍仅支持 JSON；不支持运行时对象循环。
+
+流方法（`@Remote({ mode: 'stream' })`）返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out, In>`。`In` 声明 Client 可以在同一条逻辑流上回送的项；方法通过 `this.ctx.invocation.uplink<In>()` 读取它们，描述符携带其 codec。`RemoteInvocation` 还给出接收服务 `service`、发起调用的 `peer`（连接层接纳的一个 `PeerScope`）与载体 `signal`；非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`：树中第一个 `bindTypertRemote()` 绑定（每个 `TypertRemoteService` 构造函数都会建立一个）在根上注册该 accessor。生成的 Client 流方法返回 `RemoteStreamHandle<Out, In>`：在下行迭代之外提供 `send`、`end` 与 `dispose` 的句柄。上行项在 Host 逐项校验，因为它们来自浏览器；下行项是 Host 方法产出的值，原样透传。
+
 ### 把 Host 对象与 Context 关联到 wire identity
 
 复杂的 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 失败
 
 所有 Remote 失败都由一个类承载：`RemoteError`，携带稳定的 `<domain>/<reason>` 码，以及按该码定型的 details。本包声明通用载体码（`gateway/bad-request`、`gateway/cancelled`、`gateway/internal`），并拥有 `RemoteErrorDetailsMap`——可合并扩展的码表，其他每个包都在自己的抛出点旁扩展它：
@@ -87,19 +93,20 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 ### 协议映射与描述符
 
-可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、取消与结果编解码器。
+可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、上行编解码器、取消与结果编解码器。
 
 ### Wire 标识文法
 
-每个命名空间、方法、查找与 Context 段都必须满足 `isTypertRemoteSegment()`，生成的名字才能原样跨共享 RPC 载体传输。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+每个命名空间、方法、查找与 Context 段都必须满足 `isTypertRemoteSegment()`，生成的名字才能原样跨共享 RPC 载体传输。严格编解码器携带生成的 schema factory；`src-json` 编解码器标识约束更弱的源码启动路径。
 
 ### 源码地图
 
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 装饰器、Gateway 绑定、`remoteMethods`、段校验 |
+| [`src/json-value.ts`](src/json-value.ts) | 各载体共享的无损 JSON 校验 `isRemoteJsonValue` 与 `isRemoteUplinkItem` |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` 与结构式识别函数 `remoteErrorOf` |
-| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
+| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`RemoteStream`、`RemoteStreamHandle`、`PeerScope`、`RemoteInvocation`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
 | — | 不发布运行时不变量伴生入口；decorator 只保留私有不可变声明，binding 也是冻结值，没有可供交叉核对的独立事件流。 |
 
 </details>

package/lib/index.js

@@ -1,4 +1,4 @@
-import { Service } from "@deepseek-ai/cordis";
+import { Context, Service } from "@deepseek-ai/cordis";
 //#region lib/types/remote-error.js
 /** The one Remote failure class shared by owners, the Gateway, and consumers. */
 /**
@@ -37,6 +37,85 @@ 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/json-value.js
+/**
+* Lossless JSON checks every Remote carrier shares: the Client handle before it
+* queues an uplink item, the Gateway at its wire and codec-less uplink
+* boundaries, and the in-process mock.
+*/
+/**
+* Test whether a value crosses JSON transport without coercion or omission.
+* @param value - candidate boundary value.
+* @returns whether the value is losslessly JSON-compatible.
+*/
+function isRemoteJsonValue(value) {
+	return visitJsonValue(value, /* @__PURE__ */ new Set());
+}
+/**
+* Test whether a value may travel as one uplink item: a lossless JSON value, or
+* a top-level `undefined`, which the wire carries as an `item` frame without
+* `value`. Nested `undefined`, `NaN`, and infinities stay rejected.
+* @param value - candidate uplink item.
+* @returns whether the item crosses every carrier unchanged.
+*/
+function isRemoteUplinkItem(value) {
+	return value === void 0 || isRemoteJsonValue(value);
+}
+function visitJsonValue(value, ancestors) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0);
+	if (typeof value !== "object") return false;
+	if (ancestors.has(value)) return false;
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			if (Object.getPrototypeOf(value) !== Array.prototype || Reflect.ownKeys(value).length !== value.length + 1) return false;
+			for (let index = 0; index < value.length; index++) if (!Object.hasOwn(value, index) || !visitJsonValue(value[index], ancestors)) return false;
+			return true;
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) return false;
+		for (const key of Reflect.ownKeys(value)) {
+			if (typeof key !== "string") return false;
+			if (Object.getOwnPropertyDescriptor(value, key)?.enumerable !== true || !visitJsonValue(Reflect.get(value, key), ancestors)) return false;
+		}
+		return true;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Remote decorators and explicit Gateway bindings backed by versioned
@@ -55,7 +134,10 @@ function isTypertRemoteSegment(value) {
 }
 const REMOTE_METHOD_DESCRIPTOR = "@deepseek-ai/dsh-typert-protocol/remote-methods";
 /**
-* Bind one visible Service field to a Cordis key and Remote namespace.
+* Bind one visible Service field to a Cordis key and Remote namespace. A
+* service that owns a Cordis Context also gives its tree `ctx.invocation`,
+* `undefined` outside a Remote call, so no `TypertRemoteService` is needed for
+* a Host composition to read it.
 * @param service - owning Service instance, normally `this`.
 * @param serviceKey - exact Cordis service key.
 * @param options - optional distinct wire namespace.
@@ -65,6 +147,8 @@ function bindTypertRemote(service, serviceKey, options = {}) {
 	validateName("service key", serviceKey);
 	const namespace = options.namespace ?? serviceKey;
 	validateName("namespace", namespace);
+	const ctx = Reflect.get(service, "ctx");
+	if (ctx instanceof Context) provideInvocationAccessor(ctx);
 	return Object.freeze({
 		service,
 		serviceKey,
@@ -86,6 +170,16 @@ var TypertRemoteService = class extends Service {
 		this.typertRemote = bindTypertRemote(this, this.name, options);
 	}
 };
+/**
+* Make `ctx.invocation` read as `undefined` outside a Remote call instead of the
+* reflect service's "cannot get property" error; a call-derived Context shadows
+* the accessor with its own property. The first Remote Service constructed in a
+* tree registers it on the root, where it outlives any one Service.
+*/
+function provideInvocationAccessor(ctx) {
+	if (Object.hasOwn(ctx.root.reflect.props, "invocation")) return;
+	ctx.root.accessor("invocation", { get: () => void 0 });
+}
 function Remote(methodExportOrOptions, context) {
 	if (typeof methodExportOrOptions === "string") {
 		validateName("Remote export name", methodExportOrOptions);
@@ -181,4 +275,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, isRemoteJsonValue, isRemoteUplinkItem, isTypertOwnedValue, isTypertRemoteSegment, remoteErrorOf, remoteMethods, typertOwnedValue };

package/lib/types/index.d.ts

@@ -4,16 +4,19 @@
  * remains a Typert compiler responsibility.
  * @module @deepseek-ai/dsh-typert-protocol
  */
-import { Service, type Context } from '@deepseek-ai/cordis';
+import { Context, Service } 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';
+export { isRemoteJsonValue, isRemoteUplinkItem } from './json-value.ts';
 /**
  * Test one generated Remote name against the Connection endpoint grammar.
  * @param value - namespace, method, lookup, or Context segment.
  * @returns whether the value can cross the shared RPC carrier unchanged.
  */
 export declare function isTypertRemoteSegment(value: string): boolean;
-export type { InvocationDescriptor, InvocationParameterDescriptor, InvocationSourceLocation, RemoteErrorCode, RemoteErrorDetailsMap, RemoteFailure, RemoteResult, TypertClientEventListener, TypertClientRemote, TypertClientContextAdapter, TypertCodec, TypertContext, TypertContextMap, TypertContextRegistry, TypertContextWire, TypertDisposer, TypertForwardableEvent, TypertForwardableEventEntry, TypertHostContextAdapter, TypertHostContextResolver, TypertLocalRegistry, TypertLookup, TypertLookupDefinition, TypertLookupHost, TypertLookupMap, TypertLookupProvider, TypertLookupResolver, TypertLookupRegistry, TypertLookupWire, TypertRemoteScopeApi, TypertRemoteScopeMap, TypertRemoteScopeNamespace, TypertRemoteContribution, TypertRemoteEvent, TypertRemoteEventSelection, TypertRemoteMap, TypertRemoteNamespace, TypertRemoteNamespaceMap, TypertRemoteRegistry, TypertRegistryChange, TypertRegistryListener, TypertSchema, TypertRegistryContract, } from './types.ts';
+export type { InvocationDescriptor, InvocationParameterDescriptor, InvocationSourceLocation, PeerId, PeerScope, RemoteErrorCode, RemoteErrorDetailsMap, RemoteFailure, RemoteInvocation, RemoteResult, RemoteStream, RemoteStreamHandle, TypertClientEventListener, TypertClientRemote, TypertClientContextAdapter, TypertCodec, TypertContext, TypertContextMap, TypertContextRegistry, TypertContextWire, TypertDisposer, TypertForwardableEvent, TypertForwardableEventEntry, TypertHostContextAdapter, TypertHostContextResolver, TypertLocalRegistry, TypertLookup, TypertLookupDefinition, TypertLookupHost, TypertLookupMap, TypertLookupProvider, TypertLookupResolver, TypertLookupRegistry, TypertLookupWire, TypertRemoteScopeApi, TypertRemoteScopeMap, TypertRemoteScopeNamespace, TypertRemoteContribution, TypertRemoteEvent, TypertRemoteEventSelection, TypertRemoteMap, TypertRemoteNamespace, TypertRemoteNamespaceMap, TypertRemoteRegistry, TypertRegistryChange, TypertRegistryListener, TypertSchema, TypertRegistryContract, } from './types.ts';
 /** Options for an explicit Service-to-Gateway binding. */
 export interface TypertGatewayBindingOptions {
     /** Wire namespace; defaults to the Cordis service key. */
@@ -44,12 +47,15 @@ export interface RemoteMethodMarker {
 }
 /** Options for a non-unary Remote method. */
 export interface RemoteMethodOptions {
-    /** Deliver each Iterable item over the shared logical-stream carrier. */
+    /** `stream`: deliver each Iterable item over the shared logical-stream carrier. */
     readonly mode: 'stream';
 }
 type RemoteMethodDecorator = <This extends object, Args extends unknown[], Result>(method: (this: This, ...args: Args) => Result, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void;
 /**
- * Bind one visible Service field to a Cordis key and Remote namespace.
+ * Bind one visible Service field to a Cordis key and Remote namespace. A
+ * service that owns a Cordis Context also gives its tree `ctx.invocation`,
+ * `undefined` outside a Remote call, so no `TypertRemoteService` is needed for
+ * a Host composition to read it.
  * @param service - owning Service instance, normally `this`.
  * @param serviceKey - exact Cordis service key.
  * @param options - optional distinct wire namespace.

package/lib/types/index.js

@@ -4,8 +4,10 @@
  * remains a Typert compiler responsibility.
  * @module @deepseek-ai/dsh-typert-protocol
  */
-import { Service } from '@deepseek-ai/cordis';
+import { Context, Service } from '@deepseek-ai/cordis';
 export { RemoteError, remoteErrorOf } from "./remote-error.js";
+export { TYPERT_OWNED_VALUE, isTypertOwnedValue, typertOwnedValue } from "./owned-value.js";
+export { isRemoteJsonValue, isRemoteUplinkItem } from "./json-value.js";
 const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 /**
  * Test one generated Remote name against the Connection endpoint grammar.
@@ -17,7 +19,10 @@ export function isTypertRemoteSegment(value) {
 }
 const REMOTE_METHOD_DESCRIPTOR = '@deepseek-ai/dsh-typert-protocol/remote-methods';
 /**
- * Bind one visible Service field to a Cordis key and Remote namespace.
+ * Bind one visible Service field to a Cordis key and Remote namespace. A
+ * service that owns a Cordis Context also gives its tree `ctx.invocation`,
+ * `undefined` outside a Remote call, so no `TypertRemoteService` is needed for
+ * a Host composition to read it.
  * @param service - owning Service instance, normally `this`.
  * @param serviceKey - exact Cordis service key.
  * @param options - optional distinct wire namespace.
@@ -27,6 +32,9 @@ export function bindTypertRemote(service, serviceKey, options = {}) {
     validateName('service key', serviceKey);
     const namespace = options.namespace ?? serviceKey;
     validateName('namespace', namespace);
+    const ctx = Reflect.get(service, 'ctx');
+    if (ctx instanceof Context)
+        provideInvocationAccessor(ctx);
     return Object.freeze({ service, serviceKey, namespace });
 }
 /** Cordis Service base that exposes its registered name through Typert Gateway. */
@@ -44,6 +52,17 @@ export class TypertRemoteService extends Service {
         this.typertRemote = bindTypertRemote(this, this.name, options);
     }
 }
+/**
+ * Make `ctx.invocation` read as `undefined` outside a Remote call instead of the
+ * reflect service's "cannot get property" error; a call-derived Context shadows
+ * the accessor with its own property. The first Remote Service constructed in a
+ * tree registers it on the root, where it outlives any one Service.
+ */
+function provideInvocationAccessor(ctx) {
+    if (Object.hasOwn(ctx.root.reflect.props, 'invocation'))
+        return;
+    ctx.root.accessor('invocation', { get: () => undefined });
+}
 export function Remote(methodExportOrOptions, context) {
     if (typeof methodExportOrOptions === 'string') {
         validateName('Remote export name', methodExportOrOptions);

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

@@ -0,0 +1,20 @@
+/**
+ * Lossless JSON checks every Remote carrier shares: the Client handle before it
+ * queues an uplink item, the Gateway at its wire and codec-less uplink
+ * boundaries, and the in-process mock.
+ */
+/**
+ * Test whether a value crosses JSON transport without coercion or omission.
+ * @param value - candidate boundary value.
+ * @returns whether the value is losslessly JSON-compatible.
+ */
+export declare function isRemoteJsonValue(value: unknown): boolean;
+/**
+ * Test whether a value may travel as one uplink item: a lossless JSON value, or
+ * a top-level `undefined`, which the wire carries as an `item` frame without
+ * `value`. Nested `undefined`, `NaN`, and infinities stay rejected.
+ * @param value - candidate uplink item.
+ * @returns whether the item crosses every carrier unchanged.
+ */
+export declare function isRemoteUplinkItem(value: unknown): boolean;
+//# sourceMappingURL=json-value.d.ts.map

package/lib/types/json-value.js

@@ -0,0 +1,61 @@
+/**
+ * Lossless JSON checks every Remote carrier shares: the Client handle before it
+ * queues an uplink item, the Gateway at its wire and codec-less uplink
+ * boundaries, and the in-process mock.
+ */
+/**
+ * Test whether a value crosses JSON transport without coercion or omission.
+ * @param value - candidate boundary value.
+ * @returns whether the value is losslessly JSON-compatible.
+ */
+export function isRemoteJsonValue(value) {
+    return visitJsonValue(value, new Set());
+}
+/**
+ * Test whether a value may travel as one uplink item: a lossless JSON value, or
+ * a top-level `undefined`, which the wire carries as an `item` frame without
+ * `value`. Nested `undefined`, `NaN`, and infinities stay rejected.
+ * @param value - candidate uplink item.
+ * @returns whether the item crosses every carrier unchanged.
+ */
+export function isRemoteUplinkItem(value) {
+    return value === undefined || isRemoteJsonValue(value);
+}
+function visitJsonValue(value, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value) && !Object.is(value, -0);
+    if (typeof value !== 'object')
+        return false;
+    if (ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getPrototypeOf(value) !== Array.prototype
+                || Reflect.ownKeys(value).length !== value.length + 1)
+                return false;
+            for (let index = 0; index < value.length; index++) {
+                if (!Object.hasOwn(value, index) || !visitJsonValue(value[index], ancestors))
+                    return false;
+            }
+            return true;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== 'string')
+                return false;
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor?.enumerable !== true || !visitJsonValue(Reflect.get(value, key), ancestors))
+                return false;
+        }
+        return true;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+//# sourceMappingURL=json-value.js.map

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,8 @@
  * @module @deepseek-ai/dsh-typert-protocol/types
  */
 import type { Context, Events } from '@deepseek-ai/cordis';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+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;
@@ -69,6 +71,51 @@ export type RemoteResult<T> = {
     readonly ok: false;
     readonly error: RemoteFailure;
 };
+declare const STREAM_UPLINK: unique symbol;
+/**
+ * One Remote stream as a Host method returns it: the items it yields to the
+ * Client, iterated as a plain `AsyncIterable<Out>`. `In` is the type of the
+ * items the Client may send back on the same logical stream, read through
+ * `RemoteInvocation.uplink()`; it is carried only as a type-level marker. The
+ * default `never` declares a method that reads none, and its descriptor
+ * carries no uplink codec. A generated Client stream method returns the same
+ * stream as a `RemoteStreamHandle<Out, In>`.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+export type RemoteStream<Out, In = never> = AsyncIterable<Out> & {
+    readonly [STREAM_UPLINK]?: In;
+};
+/**
+ * One open Remote stream as the Client holds it: the downlink items as an
+ * `AsyncIterable`, plus the uplink and cancellation of the same logical
+ * stream. A generated Client stream method returns it, and calling that
+ * method opens the stream: a holder that neither iterates nor disposes the
+ * handle keeps the Host stream alive. A handle stands for one generation:
+ * when the carrier is lost, iteration fails with the carrier error and the
+ * handle is finished.
+ * @template Out - item type the Host method yields.
+ * @template In - item type the Client may send; `never` when the method reads none.
+ */
+export interface RemoteStreamHandle<Out, In> extends AsyncIterable<Out> {
+    /**
+     * Send one uplink item. Items sent before the stream has opened are queued
+     * and sent once the `open` frame is on the wire. A top-level `undefined`
+     * travels as an `item` frame without `value`.
+     * @param item - item the Host validates against the method's uplink codec.
+     * @throws {Error} when the item is not a lossless JSON value, when `end()`
+     * was called, or once the stream has terminated.
+     */
+    send(item: In): void;
+    /** Half-close the uplink: the Host's `uplink()` iteration ends. Idempotent; ignored after termination. */
+    end(): void;
+    /**
+     * Cancel the logical stream: send `cancel` unless a terminal frame has
+     * arrived, and end the downlink iterator quietly. Breaking out of
+     * `for await` early does the same.
+     */
+    dispose(): void;
+}
 /** Merge-extensible scoped Remote method signatures generated for consumers. */
 export interface TypertRemoteScopeMap {
 }
@@ -152,7 +199,21 @@ 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;
+    /**
+     * Decode a unary result whose fields require type-specific handling.
+     * @param value - result reconstructed by the RPC carrier.
+     * @returns the validated result, retaining native byte views.
+     */
+    readonly decode?: (value: unknown) => unknown;
+    /**
+     * Project typed binary fields into RPC result attachments.
+     * @param value - native unary result.
+     * @param writeBytes - records a byte view at its result-relative path and returns its JSON placeholder.
+     * @returns JSON metadata with untouched JSON subtrees retained.
+     */
+    readonly encode?: (value: unknown, writeBytes: (bytes: Uint8Array, path: readonly (string | number)[]) => null) => unknown;
 } | {
     readonly mode: 'src-json';
 };
@@ -189,7 +250,7 @@ export interface InvocationDescriptor {
     readonly method: string;
     /** Service member invoked when the exported method name is an alias. */
     readonly implementation?: string;
-    /** Absent for unary calls; stream calls validate and deliver every yielded item. */
+    /** Absent for unary calls; stream calls deliver every yielded item as the Host produced it. */
     readonly mode?: 'stream';
     /** Receiver selection mode. */
     readonly invocation: {
@@ -209,6 +270,16 @@ export interface InvocationDescriptor {
     };
     /** Ordered business parameters. */
     readonly parameters: readonly InvocationParameterDescriptor[];
+    /**
+     * Client-to-Host items of the same logical stream, generated from the `In`
+     * type argument of the method's `RemoteStream<Out, In>` return type; absent
+     * when `In` is `never`. The method reads the items through
+     * `RemoteInvocation.uplink()`, so nothing enters the parameter list.
+     */
+    readonly uplink?: {
+        /** Codec validating every uplink item before `uplink()` delivers it. */
+        readonly codec: TypertCodec;
+    };
     /** Transport cancellation injected after business parameters instead of entering wire args. */
     readonly cancellation?: {
         /** Reserved final Host method parameter. */
@@ -219,6 +290,56 @@ export interface InvocationDescriptor {
     /** Source declaration used only for diagnostics. */
     readonly sourceLocation?: InvocationSourceLocation;
 }
+/**
+ * Opaque identity of one Peer: a party admitted to this Host by the connection
+ * layer. "Peer" is a connection-layer word; the browser application keeps the
+ * word "Client".
+ */
+export type PeerId = Branded<'PeerId'>;
+/**
+ * One Peer's session on this Host. Connection owns it: `ctx` is the Cordis
+ * scope that owns connection-lifetime registrations and is disposed with the
+ * Peer. Who the Peer is and what it may do are not recorded here.
+ */
+export interface PeerScope {
+    readonly id: PeerId;
+    readonly ctx: Context;
+    /**
+     * Tear down every registration made through `ctx`.
+     * @returns settles once the scope has quiesced; racing calls share one completion.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * The context of one Remote call, reachable inside the receiving method as
+ * `this.ctx.invocation`. The Gateway derives the receiver from a Context that
+ * carries it, so no parameter is injected and nothing crosses the wire.
+ */
+export interface RemoteInvocation {
+    readonly request: {
+        readonly namespace: string;
+        readonly method: string;
+        readonly args: Readonly<Record<string, unknown>>;
+    };
+    /** Cordis service key of the receiving Service. */
+    readonly service: string;
+    /** Peer the call speaks for; an in-process carrier speaks for the operator. */
+    readonly peer: PeerScope;
+    /** Carrier cancellation: Client cancel, socket close, or an uplink failure. */
+    readonly signal: AbortSignal;
+    /**
+     * The Client's uplink items for this call. Available once; a second call
+     * throws. With an uplink codec on the descriptor every item is decoded to
+     * `In`; without one items arrive as `unknown` after a JSON-safety check.
+     * Iteration ends when the Client ends its uplink; when the method finishes
+     * its downlink the Gateway calls the iterator's `return()` and unread items
+     * are dropped. `In` is the caller's assertion: the runtime decodes by the
+     * descriptor and does not cross-check it.
+     * @template In - item type the caller reads; the descriptor codec decides what arrives.
+     * @returns the single-consumer uplink iterable.
+     */
+    uplink<In = unknown>(): AsyncIterable<In>;
+}
 /** Generated Host contract selected explicitly by a Client assembly. */
 export interface TypertRemoteContribution {
     /** npm package that owns the Remote methods. */
@@ -305,11 +426,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 {
@@ -451,6 +572,12 @@ export interface TypertRegistryContract {
 declare module '@deepseek-ai/cordis' {
     interface Context {
         typert: TypertRegistryContract;
+        /**
+         * The Remote call this Context was derived for, or `undefined` on a
+         * Context no Remote call derived. A Service method reads it as
+         * `this.ctx.invocation`.
+         */
+        readonly invocation: RemoteInvocation | undefined;
     }
 }
 export {};

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.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -31,10 +31,13 @@
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "^0.1.7-alpha.1"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   }
 }