@deepseek-ai/dsh-typert-generator 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/generator/README.md
-README.md: 399e4fe622a785d68452ffeae79e106246941fa1
-README.zh.md: 1fd19fd76ab804013a8741cb90522e9fd3f608d3
+README.md: 9c207574e9bb576a965ab1a91576a3b5a9db397e
+README.zh.md: 9a6fa9e81d7950efb4d4b76df6921bc5a83b6adf

package/README.md

@@ -79,12 +79,14 @@ The generator is built on one separation: extraction and emission are decoupled
 
 ### Analysis and faces
 
-Host and Client are independent TypeScript programs. Direct project references establish compiler-face membership, while `dsh.client` package subpaths establish runtime-face contribution; `package.json#exports` marks every cross-package public boundary, and imports or re-exports are the only cross-face edges. A relative import that resolves inside the referencing package is followed through that module's re-exports until a package specifier appears, so package-local forwarding modules keep their original declaration references; a relative import that resolves into another package fails. `check` mode fails on syntax or semantic diagnostics, missing public annotations, private cross-package references, and reachable declaration merges the model cannot retain losslessly; `write` mode inserts checker-derived annotations and returns a clean check-mode model. Types owned by NPM dependencies remain `external` references instead of being expanded.
+Host and Client are independent TypeScript programs. Direct project references establish compiler-face membership, while `dsh.client` package subpaths establish runtime-face contribution; `package.json#exports` marks every cross-package public boundary, and imports or re-exports are the only cross-face edges. A relative import that resolves inside the referencing package is followed through that module's re-exports until a package specifier appears, so package-local forwarding modules keep their original declaration references; a relative import that resolves into another package fails. `check` mode fails on syntax or semantic diagnostics, missing public annotations, private cross-package references, and reachable declaration merges the model cannot retain losslessly; `write` mode inserts checker-derived annotations and returns a clean check-mode model. Types owned by NPM dependencies remain `external` references instead of being expanded. A stream method's return type may be `Iterable<Out>`, `AsyncIterable<Out>`, or the protocol's `RemoteStream<Out, In>`, recognized by symbol and declaring package like the standard-library wrappers; a second type argument other than `never` yields the descriptor's uplink codec, and the generated Client signature returns `RemoteStreamHandle<Out, In>`.
 
 ### Emission and publication contract
 
 `FaceModelEmitter` emits executable JavaScript containing success-cached Zod schema factories and the `TYPERT` contribution, plus a declaration file whose factories return `z.ZodType<SourceType>` through the package's public export; unsupported Zod projections fail. The Host face with Remote methods additionally emits `typert.remote-client.*` projections of Host Remote contracts for the Client. `WorkspaceTypertGenerator` validates each contributor's `package.json`: `./typert` and `./client/typert` (and `./remote` when Remote methods exist) must point at the exact generated files, and the `files` list must include them.
 
+[Unary binary results](../protocol/README.md) are recognized after generic type resolution. Their codecs validate the byte-array type and JSON metadata without iterating, copying, or freezing the byte payload; generated Client declarations retain the authored metadata and narrow the byte backing to `ArrayBuffer`.
+
 ### Catalog projection
 
 The runtime type closure indexes exported workspace declarations and referenced framework enums. Vendored declarations stay outside business API discovery; their enums remain available when a public result refers to them.

package/README.zh.md

@@ -79,12 +79,14 @@ files:
 
 ### 分析与 face
 
-Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定编译器 face 的成员归属，`dsh.client` 包子路径则确定运行时 face 的贡献；`package.json#exports` 划定所有跨包公开边界，跨 face 的边只能来自导入或重新导出。解析到本包内部模块的相对导入会沿该模块的重新导出继续追踪，直到出现包说明符，因此包内转发模块保留原始声明引用；解析到其他包的相对导入会失败。`check` 模式遇到语法或语义诊断、缺失的公开类型标注、跨包私有引用，以及模型无法无损保留的可达声明合并时都会失败；`write` 模式插入类型检查器推导出的标注，并返回无诊断的 check 模式模型。NPM 依赖拥有的类型继续以 `external` 引用表示，不会被展开。
+Host 与 Client 是两个独立的 TypeScript 程序。直接项目引用确定编译器 face 的成员归属，`dsh.client` 包子路径则确定运行时 face 的贡献；`package.json#exports` 划定所有跨包公开边界，跨 face 的边只能来自导入或重新导出。解析到本包内部模块的相对导入会沿该模块的重新导出继续追踪，直到出现包说明符，因此包内转发模块保留原始声明引用；解析到其他包的相对导入会失败。`check` 模式遇到语法或语义诊断、缺失的公开类型标注、跨包私有引用，以及模型无法无损保留的可达声明合并时都会失败；`write` 模式插入类型检查器推导出的标注，并返回无诊断的 check 模式模型。NPM 依赖拥有的类型继续以 `external` 引用表示，不会被展开。流方法的返回类型可以是 `Iterable<Out>`、`AsyncIterable<Out>` 或协议包的 `RemoteStream<Out, In>`，后者与标准库包装器一样按符号名与声明所在包识别；第二个类型参数不为 `never` 时产出描述符的上行编解码器，生成的 Client 签名则返回 `RemoteStreamHandle<Out, In>`。
 
 ### 生成与发布约定
 
 `FaceModelEmitter` 输出包含只缓存成功结果的 Zod schema factory 与 `TYPERT` 贡献的可执行 JavaScript，以及把 factory 通过包的公开导出标注为返回 `z.ZodType<SourceType>` 的声明文件；不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`：`./typert` 与 `./client/typert`（存在 Remote 方法时还有 `./remote`）必须指向精确的生成文件，且 `files` 清单必须包含它们。
 
+[一元二进制结果](../protocol/README.zh.md)在泛型类型解析后被识别。其 codec 校验字节数组类型与 JSON 元数据，不遍历、复制或冻结字节载荷；生成的 Client 声明保留原有元数据类型，并将字节的底层缓冲区收窄为 `ArrayBuffer`。
+
 ### 目录投影
 
 运行时类型闭包索引导出的 workspace 声明和被引用的框架 enum。Vendor 声明不参与业务 API 发现；公共结果引用其中 enum 时，目录仍提供其定义。

package/lib/index.js

@@ -774,7 +774,8 @@ var FaceAnalyzer = class {
 			}
 		}
 		const mode = invocation.kind === "direct" ? invocation.mode : void 0;
-		const resultType = this.remoteResultType(method, mode);
+		const { result: resultType, uplink: uplinkType } = this.remoteResultType(method, mode);
+		const uplink = uplinkType === void 0 ? void 0 : { boundary: this.remoteBoundary(uplinkType, `${registration.name}#${binding.namespace}/${exportedMethod}:uplink`, false, "undefined") };
 		return {
 			id: `${registration.name}#${binding.namespace}/${exportedMethod}`,
 			service: binding.service,
@@ -785,8 +786,9 @@ var FaceAnalyzer = class {
 			invocation: receiver,
 			...scope === void 0 ? {} : { scope },
 			parameters,
+			...uplink === void 0 ? {} : { uplink },
 			...cancellation === void 0 ? {} : { cancellation },
-			result: this.remoteBoundary(resultType, `${registration.name}#${binding.namespace}/${exportedMethod}:result`, false, "undefined-or-void"),
+			result: this.remoteBoundary(resultType, `${registration.name}#${binding.namespace}/${exportedMethod}:result`, false, "undefined-or-void", false, mode === void 0),
 			location: this.location(method.name)
 		};
 	}
@@ -865,10 +867,11 @@ var FaceAnalyzer = class {
 					if (!ts.isObjectLiteralExpression(argument) || argument.properties.length !== 1) this.fail(argument, "Remote() options must contain exactly mode: \"stream\"");
 					const [property] = argument.properties;
 					if (property === void 0) this.fail(argument, "Remote() options must contain exactly mode: \"stream\"");
-					if (!ts.isPropertyAssignment(property) || memberName(property.name) !== "mode" || stringLiteralValue(property.initializer) !== "stream") this.fail(property, "Remote() options must contain exactly mode: \"stream\"");
+					const mode = ts.isPropertyAssignment(property) && memberName(property.name) === "mode" ? stringLiteralValue(property.initializer) : void 0;
+					if (mode !== "stream") this.fail(property, "Remote() options must contain exactly mode: \"stream\"");
 					marker = {
 						kind: "direct",
-						mode: "stream"
+						mode
 					};
 				}
 			} else if (ts.isCallExpression(expression) && this.isTypeMetaSymbol(expression.expression, "RemoteScope")) {
@@ -889,18 +892,33 @@ var FaceAnalyzer = class {
 		}
 		return found;
 	}
+	/**
+	* The item types a Remote method's authored return type declares. Unary
+	* methods unwrap `Promise<T>`; stream methods unwrap `Iterable<Out>`,
+	* `AsyncIterable<Out>`, or the protocol's `RemoteStream<Out, In>`, whose
+	* second type argument is the uplink item type unless it is `never`.
+	*/
 	remoteResultType(method, mode) {
 		const authored = this.requiredType(method, method.type, "return");
 		if (ts.isTypeReferenceNode(authored)) {
 			const symbol = this.checker.getSymbolAtLocation(authored.typeName);
 			const resolved = symbol === void 0 ? void 0 : this.resolveSymbol(symbol);
-			const resultType = authored.typeArguments?.[0];
-			const wrappers = mode === "stream" ? ["Iterable", "AsyncIterable"] : ["Promise"];
 			const declaration = resolved === void 0 ? void 0 : preferredDeclaration(resolved);
-			if (resolved !== void 0 && wrappers.includes(resolved.name) && resultType !== void 0 && authored.typeArguments?.length === 1 && declaration !== void 0 && isStandardLibraryFile(declaration.getSourceFile().fileName)) return resultType;
+			const [result, uplink] = authored.typeArguments ?? [];
+			const arity = authored.typeArguments?.length ?? 0;
+			if (resolved !== void 0 && declaration !== void 0 && result !== void 0) {
+				if (isStandardLibraryFile(declaration.getSourceFile().fileName) && (mode === void 0 ? ["Promise"] : ["Iterable", "AsyncIterable"]).includes(resolved.name) && arity === 1) return { result };
+				if (mode !== void 0 && resolved.name === "RemoteStream" && this.isTypeMetaSymbol(authored.typeName, "RemoteStream") && arity <= 2) return uplink === void 0 || this.isNeverType(uplink) ? { result } : {
+					result,
+					uplink
+				};
+			}
 		}
-		if (mode === "stream") this.fail(method, "stream Remote methods must return Iterable<T> or AsyncIterable<T>");
-		return authored;
+		if (mode !== void 0) this.fail(method, "stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>");
+		return { result: authored };
+	}
+	isNeverType(type) {
+		return (this.checker.getTypeFromTypeNode(type).flags & ts.TypeFlags.Never) !== 0;
 	}
 	isGlobalAbortSignal(type) {
 		const symbol = this.symbolAtType(type);
@@ -963,11 +981,11 @@ var FaceAnalyzer = class {
 		}
 		return result;
 	}
-	remoteBoundary(authoredType, fallbackTypeSymbol, requireNamed, topLevelAbsence = "reject", optional = false) {
+	remoteBoundary(authoredType, fallbackTypeSymbol, requireNamed, topLevelAbsence = "reject", optional = false, allowBytes = false) {
 		const type = this.convertType(authoredType);
 		const declaredType = this.checker.getTypeFromTypeNode(authoredType);
 		const resolvedType = optional ? this.checker.getNullableType(declaredType, ts.TypeFlags.Undefined) : declaredType;
-		const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence);
+		const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes);
 		const acceptsUndefined = topLevelAbsence !== "reject" && this.includesRemoteAbsence(resolvedType);
 		const rootSymbol = this.namedWorkspaceType(authoredType);
 		const imports = /* @__PURE__ */ new Map();
@@ -1012,8 +1030,8 @@ var FaceAnalyzer = class {
 	* validated without teaching the compiler-independent emitter TypeScript's
 	* type evaluator.
 	*/
-	resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence) {
-		this.assertRemoteJsonType(resolvedType, authoredType, /* @__PURE__ */ new Set(), topLevelAbsence !== "reject", topLevelAbsence === "undefined-or-void");
+	resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes) {
+		this.assertRemoteJsonType(resolvedType, authoredType, /* @__PURE__ */ new Set(), topLevelAbsence !== "reject", topLevelAbsence === "undefined-or-void", allowBytes);
 		const completed = /* @__PURE__ */ new Map();
 		const active = /* @__PURE__ */ new Map();
 		const recursiveDeclarations = /* @__PURE__ */ new Map();
@@ -1044,6 +1062,15 @@ var FaceAnalyzer = class {
 					return id;
 				};
 				const flags = type.flags;
+				if (this.isRemoteByteArray(type)) return add({
+					kind: "reference",
+					name: "Uint8Array",
+					target: {
+						kind: "standard",
+						name: "Uint8Array"
+					},
+					arguments: []
+				});
 				if ((flags & ts.TypeFlags.Any) !== 0) return add({
 					kind: "keyword",
 					name: "any"
@@ -1127,7 +1154,7 @@ var FaceAnalyzer = class {
 					types: type.types.map(convert)
 				});
 				if ((flags & ts.TypeFlags.TypeParameter) !== 0) this.fail(authoredType, "Remote codec contains an unresolved type parameter");
-				if ((flags & ts.TypeFlags.Object) === 0) this.fail(authoredType, `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`);
+				if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) this.fail(authoredType, `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`);
 				if (this.checker.isTupleType(type)) {
 					const reference = type;
 					const target = reference.target;
@@ -1136,7 +1163,10 @@ var FaceAnalyzer = class {
 						elements: this.checker.getTypeArguments(reference).map((argument, index) => {
 							const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required;
 							return {
-								type: convert(argument),
+								type: (elementFlags & ts.ElementFlags.Rest) !== 0 ? this.addNode(authoredType, {
+									kind: "array",
+									element: convert(argument)
+								}) : convert(argument),
 								optional: (elementFlags & ts.ElementFlags.Optional) !== 0,
 								rest: (elementFlags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0
 							};
@@ -1210,25 +1240,29 @@ var FaceAnalyzer = class {
 		};
 		return convert(resolvedType);
 	}
-	assertRemoteJsonType(type, site, active, allowUndefined, allowVoid) {
+	assertRemoteJsonType(type, site, active, allowUndefined, allowVoid, allowBytes = false) {
 		const flags = type.flags;
 		if ((flags & ts.TypeFlags.Undefined) !== 0 && allowUndefined) return;
 		if ((flags & ts.TypeFlags.Void) !== 0 && allowVoid) return;
 		if ((flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) !== 0) this.fail(site, `Remote boundary contains unconstrained ${this.checker.typeToString(type)} data`);
 		if ((flags & (ts.TypeFlags.BigIntLike | ts.TypeFlags.ESSymbolLike | ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0) this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`);
 		if ((flags & (ts.TypeFlags.StringLike | ts.TypeFlags.NumberLike | ts.TypeFlags.BooleanLike | ts.TypeFlags.Null | ts.TypeFlags.Never)) !== 0) return;
+		if (this.isRemoteByteArray(type)) {
+			if (allowBytes) return;
+			this.fail(site, "Remote Uint8Array is only supported in unary results");
+		}
 		if (type.isUnion()) {
-			for (const member of type.types) this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid);
+			for (const member of type.types) this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid, allowBytes);
 			return;
 		}
 		if (type.isIntersection()) {
 			const material = type.types.filter((member) => !this.isRemotePhantomConstraint(member));
 			if (material.length === 0) this.fail(site, "Remote boundary contains a symbol-only object");
-			for (const member of material) this.assertRemoteJsonType(member, site, active, false, false);
+			for (const member of material) this.assertRemoteJsonType(member, site, active, false, false, allowBytes);
 			return;
 		}
 		if ((flags & ts.TypeFlags.TypeParameter) !== 0) this.fail(site, "Remote boundary contains an unresolved type parameter");
-		if ((flags & ts.TypeFlags.Object) === 0) this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`);
+		if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`);
 		const symbol = type.getSymbol();
 		const declaration = symbol?.valueDeclaration ?? symbol?.declarations?.[0];
 		if (declaration !== void 0 && (ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration))) this.fail(site, `Remote boundary contains class instance ${symbol?.name ?? this.checker.typeToString(type)}`);
@@ -1241,14 +1275,14 @@ var FaceAnalyzer = class {
 				const target = reference.target;
 				this.checker.getTypeArguments(reference).forEach((argument, index) => {
 					const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required;
-					this.assertRemoteJsonType(argument, site, active, (elementFlags & ts.ElementFlags.Optional) !== 0, false);
+					this.assertRemoteJsonType(argument, site, active, (elementFlags & ts.ElementFlags.Optional) !== 0, false, allowBytes);
 				});
 				return;
 			}
 			if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
 				const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number);
 				if (element === void 0) this.fail(site, "Remote boundary array has no element type");
-				this.assertRemoteJsonType(element, site, active, false, false);
+				this.assertRemoteJsonType(element, site, active, false, false, allowBytes);
 				return;
 			}
 			const properties = this.checker.getPropertiesOfType(type);
@@ -1256,16 +1290,20 @@ var FaceAnalyzer = class {
 			for (const property of properties) {
 				const propertyDeclaration = property.valueDeclaration ?? property.declarations?.[0];
 				const propertyType = this.checker.getTypeOfSymbolAtLocation(property, propertyDeclaration ?? site);
-				this.assertRemoteJsonType(propertyType, site, active, (property.flags & ts.SymbolFlags.Optional) !== 0, false);
+				this.assertRemoteJsonType(propertyType, site, active, (property.flags & ts.SymbolFlags.Optional) !== 0, false, allowBytes);
 			}
 			for (const info of this.checker.getIndexInfosOfType(type)) {
 				if ((info.keyType.flags & ts.TypeFlags.ESSymbolLike) !== 0) this.fail(site, "Remote boundary contains a symbol index signature");
-				this.assertRemoteJsonType(info.type, site, active, false, false);
+				this.assertRemoteJsonType(info.type, site, active, false, false, allowBytes);
 			}
 		} finally {
 			active.delete(type);
 		}
 	}
+	isRemoteByteArray(type) {
+		const symbol = type.getSymbol();
+		return symbol?.name === "Uint8Array" && symbol.declarations?.some((declaration) => isStandardLibraryFile(declaration.getSourceFile().fileName)) === true;
+	}
 	includesRemoteAbsence(type) {
 		if ((type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0) return true;
 		return type.isUnion() && type.types.some((member) => this.includesRemoteAbsence(member));
@@ -2904,8 +2942,13 @@ var FaceModelEmitter = class {
 			lines.push("    },");
 		});
 		lines.push("  ],");
+		if (invocation.uplink !== void 0) {
+			lines.push("  uplink: {");
+			lines.push(`    codec: ${indent(strictCodec(invocation.uplink.boundary, schemas.boundary(uplinkBoundaryKey(invocation))), 4).trimStart()},`);
+			lines.push("  },");
+		}
 		if (invocation.cancellation !== void 0) lines.push("  cancellation: { parameter: 'signal' },");
-		lines.push(`  result: ${indent(strictCodec(invocation.result, schemas.boundary(resultBoundaryKey(invocation))), 2).trimStart()},`);
+		lines.push(`  result: ${indent(strictCodec(invocation.result, schemas.boundary(resultBoundaryKey(invocation)), schemas.encoder(resultBoundaryKey(invocation))), 2).trimStart()},`);
 		lines.push(`  sourceLocation: ${JSON.stringify(invocation.location)},`);
 		lines.push("}");
 		return lines.join("\n");
@@ -2926,6 +2969,7 @@ var FaceModelEmitter = class {
 			"/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */",
 			"import type {",
 			"  RemoteResult,",
+			...packageModel.invocations.some((invocation) => invocation.mode === "stream") ? ["  RemoteStreamHandle,"] : [],
 			"  TypertRemoteContribution,",
 			"} from '@deepseek-ai/dsh-typert-protocol'"
 		];
@@ -2935,6 +2979,12 @@ var FaceModelEmitter = class {
 			lines.push(`import type { ${names.join(", ")} } from ${quote$1(specifier)}`);
 		}
 		lines.push("");
+		if (packageModel.invocations.some((invocation) => containsBytes(this.renderer, invocation.result.codecType))) {
+			lines.push("type RemoteDecoded<Value> = Value extends Uint8Array ? Uint8Array<ArrayBuffer>");
+			lines.push("  : Value extends string | number | boolean | null | undefined ? Value");
+			lines.push("  : { [Key in keyof Value]: RemoteDecoded<Value[Key]> }");
+			lines.push("");
+		}
 		lines.push("declare module '@deepseek-ai/dsh-typert-protocol' {");
 		const direct = packageModel.invocations.filter((invocation) => invocation.invocation.kind === "direct");
 		const scoped = packageModel.invocations.filter((invocation) => invocation.invocation.kind === "context" || invocation.scope !== void 0);
@@ -3005,8 +3055,12 @@ var FaceModelEmitter = class {
 	remoteFunctionType(invocation, referenceNames, scoped) {
 		const parameters = invocation.parameters.filter((parameter) => !scoped || invocation.invocation.kind === "context" || parameter.wire !== invocation.scope?.wire).map((parameter) => `${safeIdentifier(parameter.wire)}${parameter.optional === true ? "?" : ""}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`);
 		if (invocation.cancellation !== void 0) parameters.push("signal?: AbortSignal");
-		const result = this.renderer.renderType(invocation.result.type, referenceNames);
-		if (invocation.mode === "stream") return `(${parameters.join(", ")}) => AsyncIterable<${result}>`;
+		const authoredResult = this.renderer.renderType(invocation.result.type, referenceNames);
+		const result = containsBytes(this.renderer, invocation.result.codecType) ? `RemoteDecoded<${authoredResult}>` : authoredResult;
+		if (invocation.mode === "stream") {
+			const uplink = invocation.uplink === void 0 ? "never" : this.renderer.renderType(invocation.uplink.boundary.type, referenceNames);
+			return `(${parameters.join(", ")}) => RemoteStreamHandle<${result}, ${uplink}>`;
+		}
 		return `(${parameters.join(", ")}) => Promise<RemoteResult<${result}>>`;
 	}
 };
@@ -3021,6 +3075,100 @@ function uniqueNamespaces(invocations) {
 function remoteNamespaceInterface(namespace) {
 	return `TypertRemoteNamespace$${Buffer.from(namespace, "utf8").toString("hex")}`;
 }
+var ResultEncoderEmitter = class {
+	renderer;
+	names = /* @__PURE__ */ new Map();
+	bodies = /* @__PURE__ */ new Map();
+	constructor(renderer) {
+		this.renderer = renderer;
+	}
+	reference(id) {
+		if (!containsBytes(this.renderer, id)) return void 0;
+		const existing = this.names.get(id);
+		if (existing !== void 0) return existing;
+		const name = `$encode${this.names.size}`;
+		this.names.set(id, name);
+		const node = this.renderer.node(id);
+		const container = node.kind === "object" || node.kind === "array" || node.kind === "tuple";
+		const body = container || node.kind === "union" || node.kind === "intersection" ? `return $resultContainer(value, path, ancestors, value => {\n${indent(this.body(id), 2)}\n}, ${container})` : this.body(id);
+		this.bodies.set(id, `const ${name} = (value, writeBytes, path, ancestors) => {\n${indent(body, 2)}\n}`);
+		return name;
+	}
+	definitions() {
+		return this.bodies.size === 0 ? [] : [RESULT_SNAPSHOT, ...this.bodies.values()];
+	}
+	call(id, value, path = "path") {
+		const reference = this.reference(id);
+		return reference === void 0 ? value : `${reference}(${value}, writeBytes, ${path}, ancestors)`;
+	}
+	body(id) {
+		const node = this.renderer.node(id);
+		switch (node.kind) {
+			case "reference":
+				if (node.target.kind === "standard" && node.target.name === "Uint8Array") return "return value instanceof Uint8Array ? writeBytes(value, path) : value";
+				if (node.target.kind === "declaration") {
+					const type = this.renderer.declaration(node.target.symbol).type;
+					if (type !== void 0) return `return ${this.call(type, "value")}`;
+				}
+				break;
+			case "union":
+			case "intersection": return [...node.types.filter((type) => containsBytes(this.renderer, type)).map((type) => `value = ${this.call(type, "value")}`), "return value"].join("\n");
+			case "array": return [
+				"if (!Array.isArray(value)) return value",
+				`for (let index = 0; index < value.length; index++) value[index] = ${this.call(node.element, "value[index]", "[...path, index]")}`,
+				"return value"
+			].join("\n");
+			case "tuple": {
+				const lines = ["if (!Array.isArray(value)) return value"];
+				for (const [index, element] of node.elements.entries()) {
+					if (!containsBytes(this.renderer, element.type)) continue;
+					if (element.rest) {
+						const rest = this.renderer.node(element.type);
+						if (rest.kind !== "array") break;
+						lines.push(`for (let index = ${index}; index < value.length; index++) value[index] = ${this.call(rest.element, "value[index]", "[...path, index]")}`);
+					} else lines.push(`if (value.length > ${index}) value[${index}] = ${this.call(element.type, `value[${index}]`, `[...path, ${index}]`)}`);
+				}
+				return [...lines, "return value"].join("\n");
+			}
+			case "object": {
+				const lines = ["if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Uint8Array) return value"];
+				for (const member of node.members) if (member.kind === "property" && containsBytes(this.renderer, member.type)) {
+					const key = quote$1(member.name);
+					lines.push(`if (Object.hasOwn(value, ${key})) value[${key}] = ${this.call(member.type, `value[${key}]`, `[...path, ${key}]`)}`);
+				} else if (member.kind === "index" && containsBytes(this.renderer, member.signature.returns)) lines.push(`for (const key of Object.keys(value)) value[key] = ${this.call(member.signature.returns, "value[key]", "[...path, key]")}`);
+				return [...lines, "return value"].join("\n");
+			}
+			default: break;
+		}
+		throw new TypertEmitError(`typert result encoder: ${node.kind} has no binary field projection`);
+	}
+};
+const RESULT_SNAPSHOT = `const $resultSnapshot = (input, path) => {
+  if (input === null || typeof input !== 'object' || input instanceof Uint8Array) return input
+  const toJSON = input.toJSON
+  const value = typeof toJSON === 'function' ? toJSON.call(input, path.at(-1)?.toString() ?? 'value') : input
+  if (value === null || typeof value !== 'object' || value instanceof Uint8Array) return value
+  if (Array.isArray(value)) {
+    const items = []
+    for (let index = 0, length = value.length; index < length; index++) items.push(value[index])
+    return items
+  }
+  const fields = {}
+  for (const key of Object.keys(value)) {
+    const item = key === 'toJSON' && value === input ? toJSON : value[key]
+    if (key === 'toJSON' && typeof item === 'function') continue
+    Object.defineProperty(fields, key, { value: item, enumerable: true, writable: true, configurable: true })
+  }
+  return fields
+}
+const $resultContainer = (input, path, ancestors, project, snapshot) => {
+  if (input === null || typeof input !== 'object') return project(input)
+  const owner = !ancestors.has(input)
+  if (!owner && ancestors.get(input) !== path.length) throw new TypeError('Remote result contains a circular object')
+  if (owner) ancestors.set(input, path.length)
+  try { return project(snapshot ? $resultSnapshot(input, path) : input) }
+  finally { if (owner) ancestors.delete(input) }
+}`;
 var SchemaEmitter = class {
 	renderer;
 	schemas;
@@ -3056,10 +3204,15 @@ var SchemaEmitter = class {
 	}
 	emit() {
 		const definitions = this.declarations.map((declaration) => this.declarationDefinition(declaration));
+		const encoder = new ResultEncoderEmitter(this.renderer);
+		const encoders = /* @__PURE__ */ new Map();
 		for (const boundary of this.boundaries) {
+			const encode = encoder.reference(boundary.type);
+			if (encode !== void 0) encoders.set(boundary.key, encode);
 			const name = this.boundaryName(boundary.key);
 			definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`);
 		}
+		definitions.push(...encoder.definitions());
 		return {
 			definitions,
 			exports: this.schemas.map((model) => ({
@@ -3067,7 +3220,8 @@ var SchemaEmitter = class {
 				exportName: safeIdentifier(model.export.name),
 				internalName: this.exportSchemaName(model)
 			})),
-			boundary: (key) => this.boundaryName(key)
+			boundary: (key) => this.boundaryName(key),
+			encoder: (key) => encoders.get(key)
 		};
 	}
 	declarationDefinition(declaration) {
@@ -3156,6 +3310,7 @@ var SchemaEmitter = class {
 				return `z.record(${this.typeSchema(key, substitutions)}, ${this.typeSchema(value, substitutions)})`;
 			}
 			case "Date": return "z.date()";
+			case "Uint8Array": return "z.instanceof(Uint8Array)";
 			default: this.fail(node.name, `standard type ${node.target.name} has no Zod projection`);
 		}
 		this.fail(node.name, `${node.target.kind} reference has no Zod projection`);
@@ -3200,7 +3355,8 @@ var SchemaEmitter = class {
 				continue;
 			}
 			if (member.kind !== "property") this.fail(subject, `${member.kind} member ${member.name} is not data-schema projectable`);
-			const property = this.describe(this.optional(this.readonly(this.typeSchema(member.type, substitutions), member.readonly), member.optional), member);
+			const schema = this.readonly(this.typeSchema(member.type, substitutions), member.readonly && !containsBytes(this.renderer, member.type, false));
+			const property = this.describe(this.optional(schema, member.optional), member);
 			properties.push(`${quote$1(member.jsonName ?? member.name)}: ${property}`);
 		}
 		if (indices.length > 1) this.fail(subject, "object type has more than one JSON index signature");
@@ -3279,6 +3435,10 @@ function invocationBoundaryRoots(invocations) {
 				type: parameter.boundary.codecType
 			});
 		});
+		if (invocation.uplink !== void 0) result.push({
+			key: uplinkBoundaryKey(invocation),
+			type: invocation.uplink.boundary.codecType
+		});
 		result.push({
 			key: resultBoundaryKey(invocation),
 			type: invocation.result.codecType
@@ -3289,18 +3449,38 @@ function invocationBoundaryRoots(invocations) {
 function contextBoundaryKey(invocation) {
 	return `${invocation.id}:context`;
 }
+function uplinkBoundaryKey(invocation) {
+	return `${invocation.id}:uplink`;
+}
 function parameterBoundaryKey(invocation, index) {
 	return `${invocation.id}:parameter:${String(index)}`;
 }
 function resultBoundaryKey(invocation) {
 	return `${invocation.id}:result`;
 }
-function strictCodec(boundary, schema) {
+function containsBytes(renderer, id, nested = true, visited = /* @__PURE__ */ new Set()) {
+	if (visited.has(id)) return false;
+	visited.add(id);
+	const node = renderer.node(id);
+	if (node.kind === "reference") {
+		if (node.target.kind === "standard" && node.target.name === "Uint8Array") return true;
+		if (node.target.kind === "declaration") {
+			const declaration = renderer.declaration(node.target.symbol);
+			if (declaration.type !== void 0 && containsBytes(renderer, declaration.type, nested, visited)) return true;
+		}
+		if (!nested) return false;
+	}
+	if (!nested && node.kind !== "reference" && node.kind !== "parenthesized" && node.kind !== "union" && node.kind !== "intersection") return false;
+	if (node.kind === "object" && node.members.some((member) => containsBytes(renderer, member.kind === "property" ? member.type : member.signature.returns, nested, visited))) return true;
+	return childTypeNodeIds(node).some((child) => containsBytes(renderer, child, nested, visited));
+}
+function strictCodec(boundary, schema, encoder) {
 	return [
 		"{",
 		"  mode: 'strict',",
 		`  typeSymbol: ${quote$1(boundary.typeSymbol)},`,
 		`  create: ${schema},`,
+		...encoder === void 0 ? [] : [`  decode: value => ${schema}().parse(value),`, `  encode: (value, writeBytes) => ${encoder}(value, writeBytes, [], new Map()),`],
 		"}"
 	].join("\n");
 }
@@ -3316,12 +3496,19 @@ function remoteImports(invocations) {
 	for (const invocation of invocations) {
 		if (invocation.invocation.kind === "context") add(invocation.invocation.boundary);
 		for (const parameter of invocation.parameters) add(parameter.boundary);
+		if (invocation.uplink !== void 0) add(invocation.uplink.boundary);
 		add(invocation.result);
 	}
 	return [...imports.values()].sort((left, right) => left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name));
 }
 function allocateRemoteImportNames(imports) {
-	const used = new Set(["TypertRemoteContribution", "TYPERT_REMOTE"]);
+	const used = new Set([
+		"RemoteDecoded",
+		"RemoteResult",
+		"RemoteStreamHandle",
+		"TypertRemoteContribution",
+		"TYPERT_REMOTE"
+	]);
 	const names = /* @__PURE__ */ new Map();
 	for (const imported of imports) {
 		const base = safeIdentifier(imported.name);

package/lib/types/analyzer.js

@@ -965,7 +965,12 @@ class FaceAnalyzer {
             }
         }
         const mode = invocation.kind === 'direct' ? invocation.mode : undefined;
-        const resultType = this.remoteResultType(method, mode);
+        const { result: resultType, uplink: uplinkType } = this.remoteResultType(method, mode);
+        const uplink = uplinkType === undefined
+            ? undefined
+            : {
+                boundary: this.remoteBoundary(uplinkType, `${registration.name}#${binding.namespace}/${exportedMethod}:uplink`, false, 'undefined'),
+            };
         return {
             id: `${registration.name}#${binding.namespace}/${exportedMethod}`,
             service: binding.service,
@@ -976,8 +981,9 @@ class FaceAnalyzer {
             invocation: receiver,
             ...(scope === undefined ? {} : { scope }),
             parameters,
+            ...(uplink === undefined ? {} : { uplink }),
             ...(cancellation === undefined ? {} : { cancellation }),
-            result: this.remoteBoundary(resultType, `${registration.name}#${binding.namespace}/${exportedMethod}:result`, false, 'undefined-or-void'),
+            result: this.remoteBoundary(resultType, `${registration.name}#${binding.namespace}/${exportedMethod}:result`, false, 'undefined-or-void', false, mode === undefined),
             location: this.location(method.name),
         };
     }
@@ -1098,12 +1104,12 @@ class FaceAnalyzer {
                     const [property] = argument.properties;
                     if (property === undefined)
                         this.fail(argument, 'Remote() options must contain exactly mode: "stream"');
-                    if (!ts.isPropertyAssignment(property)
-                        || memberName(property.name) !== 'mode'
-                        || stringLiteralValue(property.initializer) !== 'stream') {
+                    const mode = ts.isPropertyAssignment(property) && memberName(property.name) === 'mode'
+                        ? stringLiteralValue(property.initializer)
+                        : undefined;
+                    if (mode !== 'stream')
                         this.fail(property, 'Remote() options must contain exactly mode: "stream"');
-                    }
-                    marker = { kind: 'direct', mode: 'stream' };
+                    marker = { kind: 'direct', mode };
                 }
             }
             else if (ts.isCallExpression(expression)
@@ -1131,27 +1137,40 @@ class FaceAnalyzer {
         }
         return found;
     }
+    /**
+     * The item types a Remote method's authored return type declares. Unary
+     * methods unwrap `Promise<T>`; stream methods unwrap `Iterable<Out>`,
+     * `AsyncIterable<Out>`, or the protocol's `RemoteStream<Out, In>`, whose
+     * second type argument is the uplink item type unless it is `never`.
+     */
     remoteResultType(method, mode) {
         const authored = this.requiredType(method, method.type, 'return');
         if (ts.isTypeReferenceNode(authored)) {
             const symbol = this.checker.getSymbolAtLocation(authored.typeName);
             const resolved = symbol === undefined ? undefined : this.resolveSymbol(symbol);
-            const resultType = authored.typeArguments?.[0];
-            const wrappers = mode === 'stream' ? ['Iterable', 'AsyncIterable'] : ['Promise'];
             const declaration = resolved === undefined ? undefined : preferredDeclaration(resolved);
-            if (resolved !== undefined
-                && wrappers.includes(resolved.name)
-                && resultType !== undefined
-                && authored.typeArguments?.length === 1
-                && declaration !== undefined
-                && isStandardLibraryFile(declaration.getSourceFile().fileName)) {
-                return resultType;
+            const [result, uplink] = authored.typeArguments ?? [];
+            const arity = authored.typeArguments?.length ?? 0;
+            if (resolved !== undefined && declaration !== undefined && result !== undefined) {
+                const standard = isStandardLibraryFile(declaration.getSourceFile().fileName);
+                const wrappers = mode === undefined ? ['Promise'] : ['Iterable', 'AsyncIterable'];
+                if (standard && wrappers.includes(resolved.name) && arity === 1)
+                    return { result };
+                if (mode !== undefined
+                    && resolved.name === 'RemoteStream'
+                    && this.isTypeMetaSymbol(authored.typeName, 'RemoteStream')
+                    && arity <= 2) {
+                    return uplink === undefined || this.isNeverType(uplink) ? { result } : { result, uplink };
+                }
             }
         }
-        if (mode === 'stream') {
-            this.fail(method, 'stream Remote methods must return Iterable<T> or AsyncIterable<T>');
+        if (mode !== undefined) {
+            this.fail(method, 'stream Remote methods must return Iterable<Out>, AsyncIterable<Out>, or RemoteStream<Out, In>');
         }
-        return authored;
+        return { result: authored };
+    }
+    isNeverType(type) {
+        return (this.checker.getTypeFromTypeNode(type).flags & ts.TypeFlags.Never) !== 0;
     }
     isGlobalAbortSignal(type) {
         const symbol = this.symbolAtType(type);
@@ -1248,7 +1267,7 @@ class FaceAnalyzer {
         }
         return result;
     }
-    remoteBoundary(authoredType, fallbackTypeSymbol, requireNamed, topLevelAbsence = 'reject', optional = false) {
+    remoteBoundary(authoredType, fallbackTypeSymbol, requireNamed, topLevelAbsence = 'reject', optional = false, allowBytes = false) {
         const type = this.convertType(authoredType);
         const declaredType = this.checker.getTypeFromTypeNode(authoredType);
         // An optional parameter's authored node carries no `undefined`; the codec
@@ -1256,7 +1275,7 @@ class FaceAnalyzer {
         const resolvedType = optional
             ? this.checker.getNullableType(declaredType, ts.TypeFlags.Undefined)
             : declaredType;
-        const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence);
+        const codecType = this.resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes);
         const acceptsUndefined = topLevelAbsence !== 'reject' && this.includesRemoteAbsence(resolvedType);
         const rootSymbol = this.namedWorkspaceType(authoredType);
         const imports = new Map();
@@ -1306,8 +1325,8 @@ class FaceAnalyzer {
      * validated without teaching the compiler-independent emitter TypeScript's
      * type evaluator.
      */
-    resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence) {
-        this.assertRemoteJsonType(resolvedType, authoredType, new Set(), topLevelAbsence !== 'reject', topLevelAbsence === 'undefined-or-void');
+    resolvedRemoteCodecType(authoredType, resolvedType, topLevelAbsence, allowBytes) {
+        this.assertRemoteJsonType(resolvedType, authoredType, new Set(), topLevelAbsence !== 'reject', topLevelAbsence === 'undefined-or-void', allowBytes);
         const completed = new Map();
         const active = new Map();
         const recursiveDeclarations = new Map();
@@ -1338,6 +1357,9 @@ class FaceAnalyzer {
                     return id;
                 };
                 const flags = type.flags;
+                if (this.isRemoteByteArray(type)) {
+                    return add({ kind: 'reference', name: 'Uint8Array', target: { kind: 'standard', name: 'Uint8Array' }, arguments: [] });
+                }
                 if ((flags & ts.TypeFlags.Any) !== 0)
                     return add({ kind: 'keyword', name: 'any' });
                 if ((flags & ts.TypeFlags.Unknown) !== 0)
@@ -1386,7 +1408,7 @@ class FaceAnalyzer {
                 if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
                     this.fail(authoredType, 'Remote codec contains an unresolved type parameter');
                 }
-                if ((flags & ts.TypeFlags.Object) === 0) {
+                if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) {
                     this.fail(authoredType, `Remote codec type ${this.checker.typeToString(type, authoredType, ts.TypeFormatFlags.NoTruncation)} has no concrete Zod projection`);
                 }
                 if (this.checker.isTupleType(type)) {
@@ -1398,7 +1420,9 @@ class FaceAnalyzer {
                         elements: arguments_.map((argument, index) => {
                             const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required;
                             return {
-                                type: convert(argument),
+                                type: (elementFlags & ts.ElementFlags.Rest) !== 0
+                                    ? this.addNode(authoredType, { kind: 'array', element: convert(argument) })
+                                    : convert(argument),
                                 optional: (elementFlags & ts.ElementFlags.Optional) !== 0,
                                 rest: (elementFlags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0,
                             };
@@ -1472,7 +1496,7 @@ class FaceAnalyzer {
         };
         return convert(resolvedType);
     }
-    assertRemoteJsonType(type, site, active, allowUndefined, allowVoid) {
+    assertRemoteJsonType(type, site, active, allowUndefined, allowVoid, allowBytes = false) {
         const flags = type.flags;
         if ((flags & ts.TypeFlags.Undefined) !== 0 && allowUndefined)
             return;
@@ -1490,9 +1514,14 @@ class FaceAnalyzer {
             | ts.TypeFlags.Null
             | ts.TypeFlags.Never)) !== 0)
             return;
+        if (this.isRemoteByteArray(type)) {
+            if (allowBytes)
+                return;
+            this.fail(site, 'Remote Uint8Array is only supported in unary results');
+        }
         if (type.isUnion()) {
             for (const member of type.types) {
-                this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid);
+                this.assertRemoteJsonType(member, site, active, allowUndefined, allowVoid, allowBytes);
             }
             return;
         }
@@ -1501,13 +1530,13 @@ class FaceAnalyzer {
             if (material.length === 0)
                 this.fail(site, 'Remote boundary contains a symbol-only object');
             for (const member of material)
-                this.assertRemoteJsonType(member, site, active, false, false);
+                this.assertRemoteJsonType(member, site, active, false, false, allowBytes);
             return;
         }
         if ((flags & ts.TypeFlags.TypeParameter) !== 0) {
             this.fail(site, 'Remote boundary contains an unresolved type parameter');
         }
-        if ((flags & ts.TypeFlags.Object) === 0) {
+        if ((flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)) === 0) {
             this.fail(site, `Remote boundary contains non-JSON type ${this.checker.typeToString(type)}`);
         }
         const symbol = type.getSymbol();
@@ -1528,7 +1557,7 @@ class FaceAnalyzer {
                 const arguments_ = this.checker.getTypeArguments(reference);
                 arguments_.forEach((argument, index) => {
                     const elementFlags = target.elementFlags[index] ?? ts.ElementFlags.Required;
-                    this.assertRemoteJsonType(argument, site, active, (elementFlags & ts.ElementFlags.Optional) !== 0, false);
+                    this.assertRemoteJsonType(argument, site, active, (elementFlags & ts.ElementFlags.Optional) !== 0, false, allowBytes);
                 });
                 return;
             }
@@ -1536,7 +1565,7 @@ class FaceAnalyzer {
                 const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number);
                 if (element === undefined)
                     this.fail(site, 'Remote boundary array has no element type');
-                this.assertRemoteJsonType(element, site, active, false, false);
+                this.assertRemoteJsonType(element, site, active, false, false, allowBytes);
                 return;
             }
             const properties = this.checker.getPropertiesOfType(type);
@@ -1546,19 +1575,24 @@ class FaceAnalyzer {
             for (const property of properties) {
                 const propertyDeclaration = property.valueDeclaration ?? property.declarations?.[0];
                 const propertyType = this.checker.getTypeOfSymbolAtLocation(property, propertyDeclaration ?? site);
-                this.assertRemoteJsonType(propertyType, site, active, (property.flags & ts.SymbolFlags.Optional) !== 0, false);
+                this.assertRemoteJsonType(propertyType, site, active, (property.flags & ts.SymbolFlags.Optional) !== 0, false, allowBytes);
             }
             for (const info of this.checker.getIndexInfosOfType(type)) {
                 if ((info.keyType.flags & ts.TypeFlags.ESSymbolLike) !== 0) {
                     this.fail(site, 'Remote boundary contains a symbol index signature');
                 }
-                this.assertRemoteJsonType(info.type, site, active, false, false);
+                this.assertRemoteJsonType(info.type, site, active, false, false, allowBytes);
             }
         }
         finally {
             active.delete(type);
         }
     }
+    isRemoteByteArray(type) {
+        const symbol = type.getSymbol();
+        return symbol?.name === 'Uint8Array'
+            && symbol.declarations?.some(declaration => isStandardLibraryFile(declaration.getSourceFile().fileName)) === true;
+    }
     includesRemoteAbsence(type) {
         if ((type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Void)) !== 0)
             return true;

package/lib/types/emitter.js

@@ -7,6 +7,7 @@ import { Buffer } from 'node:buffer';
 import { posix } from 'node:path';
 import { GenMapping, addMapping, toEncodedMap } from '@jridgewell/gen-mapping';
 import { TypeGraphRenderer } from "./renderer.js";
+import { childTypeNodeIds } from "./model.js";
 /** Failure to project a modeled construct into an emitted artifact. */
 export class TypertEmitError extends Error {
     name = 'TypertEmitError';
@@ -231,10 +232,15 @@ export class FaceModelEmitter {
             lines.push('    },');
         });
         lines.push('  ],');
+        if (invocation.uplink !== undefined) {
+            lines.push('  uplink: {');
+            lines.push(`    codec: ${indent(strictCodec(invocation.uplink.boundary, schemas.boundary(uplinkBoundaryKey(invocation))), 4).trimStart()},`);
+            lines.push('  },');
+        }
         if (invocation.cancellation !== undefined) {
             lines.push("  cancellation: { parameter: 'signal' },");
         }
-        lines.push(`  result: ${indent(strictCodec(invocation.result, schemas.boundary(resultBoundaryKey(invocation))), 2).trimStart()},`);
+        lines.push(`  result: ${indent(strictCodec(invocation.result, schemas.boundary(resultBoundaryKey(invocation)), schemas.encoder(resultBoundaryKey(invocation))), 2).trimStart()},`);
         lines.push(`  sourceLocation: ${JSON.stringify(invocation.location)},`);
         lines.push('}');
         return lines.join('\n');
@@ -251,10 +257,13 @@ export class FaceModelEmitter {
             });
             grouped.set(imported.specifier, values);
         }
+        // A stream method's Client signature returns the handle; `RemoteStream` names
+        // what the Host method returns.
         const lines = [
             '/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */',
             'import type {',
             '  RemoteResult,',
+            ...packageModel.invocations.some(invocation => invocation.mode === 'stream') ? ['  RemoteStreamHandle,'] : [],
             '  TypertRemoteContribution,',
             '} from \'@deepseek-ai/dsh-typert-protocol\'',
         ];
@@ -264,6 +273,12 @@ export class FaceModelEmitter {
             lines.push(`import type { ${names.join(', ')} } from ${quote(specifier)}`);
         }
         lines.push('');
+        if (packageModel.invocations.some(invocation => containsBytes(this.renderer, invocation.result.codecType))) {
+            lines.push('type RemoteDecoded<Value> = Value extends Uint8Array ? Uint8Array<ArrayBuffer>');
+            lines.push('  : Value extends string | number | boolean | null | undefined ? Value');
+            lines.push('  : { [Key in keyof Value]: RemoteDecoded<Value[Key]> }');
+            lines.push('');
+        }
         lines.push('declare module \'@deepseek-ai/dsh-typert-protocol\' {');
         const direct = packageModel.invocations.filter(invocation => invocation.invocation.kind === 'direct');
         const scoped = packageModel.invocations.filter(invocation => invocation.invocation.kind === 'context' || invocation.scope !== undefined);
@@ -342,9 +357,15 @@ export class FaceModelEmitter {
         const parameters = invocation.parameters.filter(parameter => !scoped || invocation.invocation.kind === 'context' || parameter.wire !== invocation.scope?.wire).map(parameter => `${safeIdentifier(parameter.wire)}${parameter.optional === true ? '?' : ''}: ${this.renderer.renderType(parameter.boundary.type, referenceNames)}`);
         if (invocation.cancellation !== undefined)
             parameters.push('signal?: AbortSignal');
-        const result = this.renderer.renderType(invocation.result.type, referenceNames);
+        const authoredResult = this.renderer.renderType(invocation.result.type, referenceNames);
+        const result = containsBytes(this.renderer, invocation.result.codecType)
+            ? `RemoteDecoded<${authoredResult}>`
+            : authoredResult;
         if (invocation.mode === 'stream') {
-            return `(${parameters.join(', ')}) => AsyncIterable<${result}>`;
+            const uplink = invocation.uplink === undefined
+                ? 'never'
+                : this.renderer.renderType(invocation.uplink.boundary.type, referenceNames);
+            return `(${parameters.join(', ')}) => RemoteStreamHandle<${result}, ${uplink}>`;
         }
         // The unary Client Remote face delivers the carrier's outcome, so every
         // generated consumer signature resolves to a result the caller reads.
@@ -364,6 +385,121 @@ function uniqueNamespaces(invocations) {
 function remoteNamespaceInterface(namespace) {
     return `TypertRemoteNamespace$${Buffer.from(namespace, 'utf8').toString('hex')}`;
 }
+class ResultEncoderEmitter {
+    renderer;
+    names = new Map();
+    bodies = new Map();
+    constructor(renderer) {
+        this.renderer = renderer;
+    }
+    reference(id) {
+        if (!containsBytes(this.renderer, id))
+            return undefined;
+        const existing = this.names.get(id);
+        if (existing !== undefined)
+            return existing;
+        const name = `$encode${this.names.size}`;
+        this.names.set(id, name);
+        const node = this.renderer.node(id);
+        const container = node.kind === 'object' || node.kind === 'array' || node.kind === 'tuple';
+        const body = container || node.kind === 'union' || node.kind === 'intersection'
+            ? `return $resultContainer(value, path, ancestors, value => {\n${indent(this.body(id), 2)}\n}, ${container})`
+            : this.body(id);
+        this.bodies.set(id, `const ${name} = (value, writeBytes, path, ancestors) => {\n${indent(body, 2)}\n}`);
+        return name;
+    }
+    definitions() {
+        return this.bodies.size === 0 ? [] : [RESULT_SNAPSHOT, ...this.bodies.values()];
+    }
+    call(id, value, path = 'path') {
+        const reference = this.reference(id);
+        return reference === undefined ? value : `${reference}(${value}, writeBytes, ${path}, ancestors)`;
+    }
+    body(id) {
+        const node = this.renderer.node(id);
+        switch (node.kind) {
+            case 'reference': {
+                if (node.target.kind === 'standard' && node.target.name === 'Uint8Array') {
+                    return 'return value instanceof Uint8Array ? writeBytes(value, path) : value';
+                }
+                if (node.target.kind === 'declaration') {
+                    const type = this.renderer.declaration(node.target.symbol).type;
+                    if (type !== undefined)
+                        return `return ${this.call(type, 'value')}`;
+                }
+                break;
+            }
+            case 'union':
+            case 'intersection': return [
+                ...node.types.filter(type => containsBytes(this.renderer, type)).map(type => `value = ${this.call(type, 'value')}`),
+                'return value',
+            ].join('\n');
+            case 'array': return [
+                'if (!Array.isArray(value)) return value',
+                `for (let index = 0; index < value.length; index++) value[index] = ${this.call(node.element, 'value[index]', '[...path, index]')}`,
+                'return value',
+            ].join('\n');
+            case 'tuple': {
+                const lines = ['if (!Array.isArray(value)) return value'];
+                for (const [index, element] of node.elements.entries()) {
+                    if (!containsBytes(this.renderer, element.type))
+                        continue;
+                    if (element.rest) {
+                        const rest = this.renderer.node(element.type);
+                        if (rest.kind !== 'array')
+                            break;
+                        lines.push(`for (let index = ${index}; index < value.length; index++) value[index] = ${this.call(rest.element, 'value[index]', '[...path, index]')}`);
+                    }
+                    else {
+                        lines.push(`if (value.length > ${index}) value[${index}] = ${this.call(element.type, `value[${index}]`, `[...path, ${index}]`)}`);
+                    }
+                }
+                return [...lines, 'return value'].join('\n');
+            }
+            case 'object': {
+                const lines = ["if (value === null || typeof value !== 'object' || Array.isArray(value) || value instanceof Uint8Array) return value"];
+                for (const member of node.members) {
+                    if (member.kind === 'property' && containsBytes(this.renderer, member.type)) {
+                        const key = quote(member.name);
+                        lines.push(`if (Object.hasOwn(value, ${key})) value[${key}] = ${this.call(member.type, `value[${key}]`, `[...path, ${key}]`)}`);
+                    }
+                    else if (member.kind === 'index' && containsBytes(this.renderer, member.signature.returns)) {
+                        lines.push(`for (const key of Object.keys(value)) value[key] = ${this.call(member.signature.returns, 'value[key]', '[...path, key]')}`);
+                    }
+                }
+                return [...lines, 'return value'].join('\n');
+            }
+            default: break;
+        }
+        throw new TypertEmitError(`typert result encoder: ${node.kind} has no binary field projection`);
+    }
+}
+const RESULT_SNAPSHOT = `const $resultSnapshot = (input, path) => {
+  if (input === null || typeof input !== 'object' || input instanceof Uint8Array) return input
+  const toJSON = input.toJSON
+  const value = typeof toJSON === 'function' ? toJSON.call(input, path.at(-1)?.toString() ?? 'value') : input
+  if (value === null || typeof value !== 'object' || value instanceof Uint8Array) return value
+  if (Array.isArray(value)) {
+    const items = []
+    for (let index = 0, length = value.length; index < length; index++) items.push(value[index])
+    return items
+  }
+  const fields = {}
+  for (const key of Object.keys(value)) {
+    const item = key === 'toJSON' && value === input ? toJSON : value[key]
+    if (key === 'toJSON' && typeof item === 'function') continue
+    Object.defineProperty(fields, key, { value: item, enumerable: true, writable: true, configurable: true })
+  }
+  return fields
+}
+const $resultContainer = (input, path, ancestors, project, snapshot) => {
+  if (input === null || typeof input !== 'object') return project(input)
+  const owner = !ancestors.has(input)
+  if (!owner && ancestors.get(input) !== path.length) throw new TypeError('Remote result contains a circular object')
+  if (owner) ancestors.set(input, path.length)
+  try { return project(snapshot ? $resultSnapshot(input, path) : input) }
+  finally { if (owner) ancestors.delete(input) }
+}`;
 class SchemaEmitter {
     renderer;
     schemas;
@@ -409,10 +545,16 @@ class SchemaEmitter {
     }
     emit() {
         const definitions = this.declarations.map(declaration => this.declarationDefinition(declaration));
+        const encoder = new ResultEncoderEmitter(this.renderer);
+        const encoders = new Map();
         for (const boundary of this.boundaries) {
+            const encode = encoder.reference(boundary.type);
+            if (encode !== undefined)
+                encoders.set(boundary.key, encode);
             const name = this.boundaryName(boundary.key);
             definitions.push(`let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.typeSchema(boundary.type)})`);
         }
+        definitions.push(...encoder.definitions());
         const exports = this.schemas.map((model) => ({
             model,
             exportName: safeIdentifier(model.export.name),
@@ -422,6 +564,7 @@ class SchemaEmitter {
             definitions,
             exports,
             boundary: key => this.boundaryName(key),
+            encoder: key => encoders.get(key),
         };
     }
     declarationDefinition(declaration) {
@@ -531,6 +674,7 @@ class SchemaEmitter {
                     return `z.record(${this.typeSchema(key, substitutions)}, ${this.typeSchema(value, substitutions)})`;
                 }
                 case 'Date': return 'z.date()';
+                case 'Uint8Array': return 'z.instanceof(Uint8Array)';
                 default: this.fail(node.name, `standard type ${node.target.name} has no Zod projection`);
             }
         }
@@ -592,7 +736,9 @@ class SchemaEmitter {
             }
             if (member.kind !== 'property')
                 this.fail(subject, `${member.kind} member ${member.name} is not data-schema projectable`);
-            const property = this.describe(this.optional(this.readonly(this.typeSchema(member.type, substitutions), member.readonly), member.optional), member);
+            // Freezing a union may freeze its populated Uint8Array member.
+            const schema = this.readonly(this.typeSchema(member.type, substitutions), member.readonly && !containsBytes(this.renderer, member.type, false));
+            const property = this.describe(this.optional(schema, member.optional), member);
             properties.push(`${quote(member.jsonName ?? member.name)}: ${property}`);
         }
         if (indices.length > 1)
@@ -677,6 +823,9 @@ function invocationBoundaryRoots(invocations) {
         invocation.parameters.forEach((parameter, index) => {
             result.push({ key: parameterBoundaryKey(invocation, index), type: parameter.boundary.codecType });
         });
+        if (invocation.uplink !== undefined) {
+            result.push({ key: uplinkBoundaryKey(invocation), type: invocation.uplink.boundary.codecType });
+        }
         result.push({ key: resultBoundaryKey(invocation), type: invocation.result.codecType });
     }
     return result;
@@ -684,18 +833,48 @@ function invocationBoundaryRoots(invocations) {
 function contextBoundaryKey(invocation) {
     return `${invocation.id}:context`;
 }
+function uplinkBoundaryKey(invocation) {
+    return `${invocation.id}:uplink`;
+}
 function parameterBoundaryKey(invocation, index) {
     return `${invocation.id}:parameter:${String(index)}`;
 }
 function resultBoundaryKey(invocation) {
     return `${invocation.id}:result`;
 }
-function strictCodec(boundary, schema) {
+function containsBytes(renderer, id, nested = true, visited = new Set()) {
+    if (visited.has(id))
+        return false;
+    visited.add(id);
+    const node = renderer.node(id);
+    if (node.kind === 'reference') {
+        if (node.target.kind === 'standard' && node.target.name === 'Uint8Array')
+            return true;
+        if (node.target.kind === 'declaration') {
+            const declaration = renderer.declaration(node.target.symbol);
+            if (declaration.type !== undefined && containsBytes(renderer, declaration.type, nested, visited))
+                return true;
+        }
+        if (!nested)
+            return false;
+    }
+    if (!nested && node.kind !== 'reference' && node.kind !== 'parenthesized'
+        && node.kind !== 'union' && node.kind !== 'intersection')
+        return false;
+    if (node.kind === 'object' && node.members.some(member => containsBytes(renderer, member.kind === 'property' ? member.type : member.signature.returns, nested, visited)))
+        return true;
+    return childTypeNodeIds(node).some(child => containsBytes(renderer, child, nested, visited));
+}
+function strictCodec(boundary, schema, encoder) {
     return [
         '{',
         '  mode: \'strict\',',
         `  typeSymbol: ${quote(boundary.typeSymbol)},`,
         `  create: ${schema},`,
+        ...(encoder === undefined ? [] : [
+            `  decode: value => ${schema}().parse(value),`,
+            `  encode: (value, writeBytes) => ${encoder}(value, writeBytes, [], new Map()),`,
+        ]),
         '}',
     ].join('\n');
 }
@@ -716,12 +895,20 @@ function remoteImports(invocations) {
             add(invocation.invocation.boundary);
         for (const parameter of invocation.parameters)
             add(parameter.boundary);
+        if (invocation.uplink !== undefined)
+            add(invocation.uplink.boundary);
         add(invocation.result);
     }
     return [...imports.values()].sort((left, right) => left.specifier.localeCompare(right.specifier) || left.name.localeCompare(right.name));
 }
 function allocateRemoteImportNames(imports) {
-    const used = new Set(['TypertRemoteContribution', 'TYPERT_REMOTE']);
+    const used = new Set([
+        'RemoteDecoded',
+        'RemoteResult',
+        'RemoteStreamHandle',
+        'TypertRemoteContribution',
+        'TYPERT_REMOTE',
+    ]);
     const names = new Map();
     for (const imported of imports) {
         const base = safeIdentifier(imported.name);

package/lib/types/model.d.ts

@@ -117,6 +117,10 @@ export interface InvocationModel {
         readonly wire: string;
     };
     readonly parameters: readonly InvocationParameterModel[];
+    /** Per-item boundary of the Client uplink, from the `In` type argument of `RemoteStream<Out, In>`; absent when the method reads none. */
+    readonly uplink?: {
+        readonly boundary: RemoteBoundaryModel;
+    };
     readonly cancellation?: {
         readonly parameter: 'signal';
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-typert-generator",
   "description": "TypeScript project analyzer and model-driven Typert artifact generator",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -36,12 +36,12 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-tool-cordis": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-tool-cordis": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-typert-registry": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   }
 }