@deepseek-ai/dsh-typert-protocol 0.1.6-alpha.2 → 0.1.7-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: e41fa9fa305d8f55ce55d3eace647ad5afcea0e3
-README.zh.md: e784e771016ebec0913e0ea847258fe653ae3bd0
+README.md: 8a97bb339d462c8dbea7666c7855a7e51ae9b113
+README.zh.md: 9bb2cae765ee5747bf11a92d44ec2bb201b0285d

package/README.md

@@ -44,6 +44,10 @@ 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.
@@ -89,7 +93,7 @@ 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
 
@@ -100,8 +104,9 @@ Every namespace, method, lookup, and Context segment must satisfy `isTypertRemot
 | 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

@@ -44,6 +44,10 @@ 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`，该码原样到达调用方。
@@ -89,7 +93,7 @@ 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 标识文法
 
@@ -100,8 +104,9 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 | 文件 | 职责 |
 |---|---|
 | [`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. */
 /**
@@ -68,6 +68,54 @@ 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
@@ -86,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.
@@ -96,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,
@@ -117,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);
@@ -212,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, TYPERT_OWNED_VALUE, TypertRemoteService, bindTypertRemote, isTypertOwnedValue, isTypertRemoteSegment, remoteErrorOf, remoteMethods, typertOwnedValue };
+export { Remote, RemoteError, RemoteScope, TYPERT_OWNED_VALUE, TypertRemoteService, bindTypertRemote, isRemoteJsonValue, isRemoteUplinkItem, isTypertOwnedValue, isTypertRemoteSegment, remoteErrorOf, remoteMethods, typertOwnedValue };

package/lib/types/index.d.ts

@@ -4,18 +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. */
@@ -46,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,9 +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.
@@ -18,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.
@@ -28,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. */
@@ -45,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/types.d.ts

@@ -4,6 +4,7 @@
  * @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;
@@ -70,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 {
 }
@@ -155,6 +201,19 @@ export type TypertCodec = {
     readonly typeSymbol: string;
     /** 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';
 };
@@ -191,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: {
@@ -211,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. */
@@ -221,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. */
@@ -453,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.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -31,10 +31,13 @@
     "lib/types/**/*.d.ts"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "0.1.7-alpha.2"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }