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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/typert/generator/README.md
-README.md: 7177e6a34520ab07645727edb15c5a726b9a2a4c
-README.zh.md: c1add1907c7c14ee7dd440dfaceee0ece0aa036e
+README.md: 9c207574e9bb576a965ab1a91576a3b5a9db397e
+README.zh.md: 9a6fa9e81d7950efb4d4b76df6921bc5a83b6adf

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-typert-generator` lets maintainers turn public TypeScript types into build artifacts and compiler-independent models. Packages opt in through the `./typert` and optional `./client/typert` exports, and generation rejects declarations, publish lists, Remote exports, or Zod projections that it cannot represent correctly. Repository builds can emit executable schemas and matching declarations, while tools can call `WorkspaceAnalyzer` for inspection or catalog generation without publishing artifacts. Generation runs only at build time and never in a live agent session.
+`dsh-typert-generator` lets maintainers turn public TypeScript types into build artifacts and compiler-independent models. Packages opt in through the `./typert` and optional `./client/typert` exports, and generation rejects declarations, publish lists, Remote exports, or Zod projections that it cannot represent correctly. Repository builds emit executable schema factories and matching declarations, while tools can call `WorkspaceAnalyzer` for inspection or catalog generation without publishing artifacts. Generation runs only at build time and never in a live agent session.
 
 ## Table of Contents
 
@@ -79,14 +79,18 @@ 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 supported Zod schemas and the `TYPERT` contribution, plus a declaration file whose schemas are typed `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.
+`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.
+
 The root export includes the model-driven extraction, completeness checks, and deterministic text renderers used by this repository's Cordis catalogs. They accept a `CordisCatalogPolicy`; repository-owned type links, foundation and exemption classifications, and inherited Cordis entries stay in `scripts/gen-cordis-catalog.ts` and are passed in explicitly, so this package contains projection mechanics, not a hidden copy of the repository's documentation taxonomy.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-typert-generator` 让维护者把公开的 TypeScript 类型转换为构建产物和与编译器无关的模型。包通过 `./typert` 和可选的 `./client/typert` 导出选择加入；如果声明、发布清单、Remote 导出或 Zod 投影无法被正确表示，生成过程就会失败。仓库构建可以生成可执行 schema 与配套声明，工具也可以调用 `WorkspaceAnalyzer` 完成检查或目录生成而不发布产物。生成过程只在构建时运行，绝不会进入实时 agent（智能体）会话。
+`dsh-typert-generator` 让维护者把公开的 TypeScript 类型转换为构建产物和与编译器无关的模型。包通过 `./typert` 和可选的 `./client/typert` 导出选择加入；如果声明、发布清单、Remote 导出或 Zod 投影无法被正确表示，生成过程就会失败。仓库构建会生成可执行 schema factory 与配套声明，工具也可以调用 `WorkspaceAnalyzer` 完成检查或目录生成而不发布产物。生成过程只在构建时运行，绝不会进入实时 agent（智能体）会话。
 
 ## 目录
 
@@ -79,14 +79,18 @@ 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 与 `TYPERT` 贡献的可执行 JavaScript，以及把 schema 通过包的公开导出标注为 `z.ZodType<SourceType>` 的声明文件；不支持的 Zod 投影会失败。含 Remote 方法的 Host face 还会额外为 Client 生成 Host Remote 约定的 `typert.remote-client.*` 投影。`WorkspaceTypertGenerator` 校验每个贡献方的 `package.json`：`./typert` 与 `./client/typert`（存在 Remote 方法时还有 `./remote`）必须指向精确的生成文件，且 `files` 清单必须包含它们。
+`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 时，目录仍提供其定义。
+
 根导出包含本仓库 Cordis 目录使用的模型驱动提取逻辑、完整性检查与确定性文本渲染器。它们接受 `CordisCatalogPolicy`；由仓库持有的类型链接、基础类型／豁免分类与继承的 Cordis 条目仍位于 `scripts/gen-cordis-catalog.ts`，由调用方显式传入，因此本包只包含投影机制，不会隐式复制仓库的文档分类体系。
 
 </details>

package/lib/index.js

@@ -238,7 +238,7 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 	indexSourceDeclarations() {
 		const selected = this.options.packages === void 0 ? void 0 : new Set(this.options.packages);
 		const declarations = [];
-		for (const registration of this.loadRegistrations()) {
+		for (const registration of this.loadRegistrations(true)) {
 			if (!this.options.faces.includes(registration.face) || selected !== void 0 && !selected.has(registration.name)) continue;
 			for (const file of registration.config.parsed.fileNames) {
 				const relativeFile = slash(relative(this.options.root, file));
@@ -264,8 +264,8 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 		}
 		return uniqueBy(declarations, (declaration) => `${declaration.face}\0${declaration.location.file}\0${String(declaration.location.line)}\0${declaration.name}`).sort((left, right) => left.face.localeCompare(right.face) || left.location.file.localeCompare(right.location.file) || left.location.line - right.location.line);
 	}
-	loadRegistrations() {
-		const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}`;
+	loadRegistrations(includeVendor = false) {
+		const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}\0${String(includeVendor)}`;
 		const cached = this.caches.registrations.get(inventoryKey);
 		if (cached !== void 0) return cached;
 		const registrations = [];
@@ -276,7 +276,7 @@ var WorkspaceAnalyzer = class WorkspaceAnalyzer {
 			for (const reference of aggregate.parsed.projectReferences ?? []) {
 				const configPath = projectConfigPath(reference.path);
 				const packageRoot = dirname(configPath);
-				if (!isWithin(realPath(packageRoot), join(this.options.root, "packages"))) continue;
+				if (!isWithin(realPath(packageRoot), join(this.options.root, "packages")) && !(includeVendor && isWithin(realPath(packageRoot), join(this.options.root, "vendor")))) continue;
 				const manifestPath = join(packageRoot, "package.json");
 				if (!existsSync(manifestPath)) continue;
 				const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -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));
@@ -2821,7 +2859,7 @@ var FaceModelEmitter = class {
 		lines.push(`  package: ${quote$1(packageModel.name)},`);
 		lines.push(`  face: ${quote$1(this.face.face)},`);
 		lines.push("  schemas: [");
-		for (const schema of schemas.exports) lines.push(`    { name: ${quote$1(schema.exportName)}, schema: ${schema.exportName} },`);
+		for (const schema of schemas.exports) lines.push(`    { name: ${quote$1(schema.exportName)}, create: ${schema.exportName} },`);
 		lines.push("  ],");
 		lines.push("  invocations: [");
 		for (const invocation of packageModel.invocations) lines.push(`${indent(this.invocationLiteral(invocation, schemas), 4)},`);
@@ -2842,7 +2880,7 @@ var FaceModelEmitter = class {
 		if (schemas.exports.length > 0) lines.splice(1, 0, "import type { z } from 'zod'");
 		for (const [specifier, names] of [...imports].sort(([left], [right]) => left.localeCompare(right))) lines.push(`import type { ${names.sort().join(", ")} } from ${quote$1(specifier)}`);
 		lines.push("");
-		for (const schema of schemas.exports) lines.push(`export declare const ${schema.exportName}: z.ZodType<${schema.exportName}$source>`);
+		for (const schema of schemas.exports) lines.push(`export declare const ${schema.exportName}: () => z.ZodType<${schema.exportName}$source>`);
 		if (schemas.exports.length > 0) lines.push("");
 		lines.push("export declare const TYPERT: unknown");
 		return `${lines.join("\n")}\n`;
@@ -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,7 +3204,15 @@ var SchemaEmitter = class {
 	}
 	emit() {
 		const definitions = this.declarations.map((declaration) => this.declarationDefinition(declaration));
-		for (const boundary of this.boundaries) definitions.push(`const ${this.boundaryName(boundary.key)} = ${this.typeSchema(boundary.type)}`);
+		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) => ({
@@ -3064,12 +3220,13 @@ 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) {
 		const name = this.schemaName(declaration.id);
-		if (declaration.typeParameters.length === 0) return `const ${name} = ${this.declarationSchema(declaration, /* @__PURE__ */ new Map())}`;
+		if (declaration.typeParameters.length === 0) return `let ${name}$value\nconst ${name} = () => (${name}$value ??= ${this.declarationSchema(declaration, /* @__PURE__ */ new Map())})`;
 		const parameters = declaration.typeParameters.map((parameter, index) => [`type${String(index)}$schema`, parameter.id]);
 		const substitutions = new Map(parameters.map(([schema, id]) => [id, schema]));
 		return `const ${name} = (${parameters.map(([schema]) => schema).join(", ")}) => ${this.declarationSchema(declaration, substitutions)}`;
@@ -3129,7 +3286,7 @@ var SchemaEmitter = class {
 			const declaration = this.renderer.declaration(node.target.symbol);
 			if (declaration.typeParameters.length === 0) {
 				if (node.arguments.length > 0) this.fail(node.name, `non-generic declaration received ${String(node.arguments.length)} type arguments`);
-				return `z.lazy(() => ${name})`;
+				return `z.lazy(() => ${name}())`;
 			}
 			return `z.lazy(() => ${name}(${this.declarationArguments(node, declaration, substitutions).join(", ")}))`;
 		}
@@ -3153,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`);
@@ -3197,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");
@@ -3276,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
@@ -3286,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)},`,
-		`  schema: ${schema},`,
+		`  create: ${schema},`,
+		...encoder === void 0 ? [] : [`  decode: value => ${schema}().parse(value),`, `  encode: (value, writeBytes) => ${encoder}(value, writeBytes, [], new Map()),`],
 		"}"
 	].join("\n");
 }
@@ -3313,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);
@@ -3529,13 +3719,14 @@ var CordisCatalogProjector = class {
 	runtimeTypes(services, events) {
 		const declarations = /* @__PURE__ */ new Map();
 		const ambiguous = /* @__PURE__ */ new Set();
+		const maxDeclarationChars = this.policy.runtimeDeclarationMaxChars ?? DEFAULT_MAX_DECL_CHARS;
 		for (const declaration of this.sourceDeclarations) {
-			if (declaration.face !== this.face.face || declaration.kind === "enum" || !/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file)) continue;
+			if (declaration.face !== this.face.face || !/^packages\/[^/]+\/[^/]+\/src\/.+\.tsx?$/.test(declaration.location.file) && !(declaration.kind === "enum" && /^vendor\/[^/]+\/src\/.+\.ts$/.test(declaration.location.file))) continue;
 			if (declarations.has(declaration.name)) {
 				ambiguous.add(declaration.name);
 				continue;
 			}
-			declarations.set(declaration.name, declaration.text.length > MAX_DECL_CHARS ? `${declaration.text.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */` : declaration.text);
+			declarations.set(declaration.name, declaration.text.length > maxDeclarationChars ? `${declaration.text.slice(0, maxDeclarationChars)} /* …truncated — full shape in source */` : declaration.text);
 		}
 		for (const name of ambiguous) declarations.delete(name);
 		return referencedTypes([...services.flatMap((service) => service.methods.map((method) => method.signature)), ...events.map((event) => event.signature)], declarations);
@@ -3751,7 +3942,7 @@ function signatureTypeNames(renderer, signature) {
 	return [...names].sort();
 }
 /** Declarations longer than this render as a truncated stub. */
-const MAX_DECL_CHARS = 1500;
+const DEFAULT_MAX_DECL_CHARS = 1500;
 /** Render one value as a single-quoted TypeScript literal. */
 function quote(value) {
 	return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'").replaceAll("\n", "\\n")}'`;