@deepseek-ai/dsh-client-connection 0.1.6-alpha.2 → 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/client/connection/README.md
-README.md: f72dd40db4c6414c368e039300198151cf2bd96a
-README.zh.md: 4644dfb23074338bdd5888d20e0f0115811115d8
+README.md: e50f4fb6838ae27b545bd2b3c4683224f7eb37c9
+README.zh.md: 1bf0733bd660049a5b99a7e7966d65121b0dea3f

package/README.md

@@ -27,20 +27,24 @@ The package carries browser-to-Host Remote calls, exact Fetch responses, and con
 
 A static desktop page can provide `__DSH_TRANSPORT__.streamBaseUrl` for the HTTP origin of its owned Host. The Gateway uses that origin for its WebSocket while HTTP transport remains independently selected. The desktop carrier owns authentication; setting the origin alone grants no access.
 
-The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
+Unary RPC requests use JSON. A Host handler may return byte attachments that it has already separated from the JSON-compatible result value, with each attachment naming its result-relative path. Connection writes these values as multipart parts. The JSON `metadata` part contains the RPC response envelope with `null` placeholders and an attachment table recording each path, codec, and part identifier. Paths use string keys and numeric array indices; no business field name is reserved. The Client validates the envelope, `rpcId`, attachment table, and parts, then restores each byte value as an `ArrayBuffer`-backed view. Results without attachments, including base64 strings, and failures remain JSON. Logical RPC carriers return decoded native values directly. Connection does not discover binary fields or depend on Typert; the handler that owns a result protocol performs any type-directed or runtime projection before returning. Binary parameters, events, and streamed binary results are unsupported.
+
+The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams, including a stream's uplink, through `connection.rpc.open` without opening a WebSocket. The browser plugin reads the page transport, recovery settings, and location, then delegates to `installConnection(ctx, options)`. A composition that owns its carrier may call the same installer directly; the whole-client test tier does so. Each invocation creates one Context-owned service, so several Client trees can use different carriers in one realm. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
 
 -----
 
 <a id="browser-authentication-and-request-trust"></a>
 ## Browser authentication and request trust
 
-Every Host RPC method and WebSocket stream requires one browser session; there is no method-specific loopback tier. Each process mints a random launch token. `dsh-web-app` prints and opens the ordinary root URL with `?token=...`; `frontend-static` delegates root and index requests to `ctx.connection.authorizeIndex`, which accepts that token only on `GET /`, writes an authority-bound signed cookie, and redirects to clean `/`. A missing, expired, malformed, or wrong-authority cookie returns 401 before RPC dispatch. Static assets remain public. The HTTP carrier accepts no query token outside the root exchange and no Authorization-header token.
+Every Host RPC method and WebSocket stream requires one browser session; there is no method-specific loopback tier. Each process mints a random launch token. `dsh-web-app` prints and opens its application URL with `?token=...`, preserving the caller's authority and mount; `frontend-static` delegates root and index requests to `ctx.connection.authorizeIndex`, which accepts that token only on `GET /`, writes an authority-bound signed cookie, and redirects to clean `./`, which drops the token and keeps the request's directory. A missing, expired, malformed, or wrong-authority cookie returns 401 before RPC dispatch. Static assets remain public. The HTTP carrier accepts no query token outside the root exchange and no Authorization-header token.
 
 The cookie signing secret is the owner-scoped `client-connection/browser-session` grant record in `ctx.credentials`. The local provider persists it in `$DSH_HOME/.credentials.yaml`; `BrowserAuth` loads or creates the record during Connection activation and retains the secret in memory, so request authentication is synchronous. Deleting or replacing the record takes effect on the next Connection activation. Cookies carry an absolute issue/expiry interval, defaulting to 30 days through `cookieMaxAgeDays`, and bind the normalized hostname plus port in both their deterministic name and signed payload. They are host-only, `Path=/`, `HttpOnly`, and `SameSite=Strict`; they deliberately omit `Secure` because the shipped server uses loopback HTTP.
 
 Before authentication, every request still passes `src/api-request-trust.ts`. Its `Host` must be loopback or match a `trustedHosts` entry: exact on `host:port`, any port on port-less entries, both sides WHATWG-normalized. An attached `Origin` must equal that Host and `sec-fetch-site: cross-site` is refused. Malformed configured authorities fail plugin load. These checks defend DNS rebinding and cross-site browser requests; they never establish identity. A failed Host/Origin check returns 403, while a trusted but unauthenticated request returns 401. `dsh web --host 0.0.0.0` remains unsupported. Decision records: [browser request trust](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md) and [browser token authentication](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.md).
 
-Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. WebSocket stream ownership remains with API Gateway.
+Every admitted request speaks for one Peer, the operator. `ctx.connection.operator` is that `PeerScope`: its `ctx` is a Cordis scope that owns connection-lifetime registrations and is disposed with the Connection. `ctx.connection.admit(request)` runs the trust and authentication checks and answers with the rejection status or the operator; the `/api` route and the Gateway's WebSocket upgrade admit through it, and every RPC handler receives the Peer of its call. `OperatorPeer` is exported so a composition without Connection, such as the Gateway's in-process carrier, owns an operator scope with the same contract.
+
+Authenticated shared HTTP requests pass through the `connection/request` waterfall before body transfer. A listener may refuse new requests or await `next()` through response completion; removing its owning fiber removes admission behavior. Desktop uses this hook to lock new API work during an approved installation without canceling already-admitted work. Client disconnection aborts the handler signal; the bridge stops socket writes and drains any remaining response chunks. WebSocket stream ownership remains with API Gateway.
 
 <a id="connection-generation"></a>
 ## Connection generation

package/README.zh.md

@@ -27,20 +27,24 @@ kind: "package-reference"
 
 静态桌面页面可以通过 `__DSH_TRANSPORT__.streamBaseUrl` 提供其所拥有 Host 的 HTTP origin。Gateway 将该 origin 用于 WebSocket，HTTP 传输仍独立选择。桌面载体负责认证；仅设置 origin 不会授予访问权限。
 
-浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流，不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location，再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数；整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务，因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
+一元 RPC 请求使用 JSON。Host handler 可以返回已经从 JSON 兼容结果值中分离的字节附件，每个附件标明其相对于结果的路径。Connection 将这些值写为 multipart 部分。JSON `metadata` 部分包含带 `null` 占位值的 RPC 响应信封，以及记录各路径、codec 和部分标识符的附件表。路径使用字符串键与数字数组下标，不保留任何业务字段名。Client 校验信封、`rpcId`、附件表和各部分，再将每个字节值恢复为以 `ArrayBuffer` 为底层缓冲区的视图。没有附件的结果（包括 base64 字符串）与失败仍使用 JSON。逻辑 RPC 载体直接返回解码后的原生值。Connection 不识别二进制字段，也不依赖 Typert；拥有结果协议的 handler 在返回前执行按类型或按运行时值的投影。不支持二进制参数、事件和二进制流式结果。
+
+浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流（包括流的上行），不打开 WebSocket。浏览器插件读取页面 transport、恢复设置与 location，再委托 `installConnection(ctx, options)`。持有自身载体的组合可以直接调用同一个安装函数；整机客户端测试档就是这一消费者。每次调用都会创建一个归所属 Context 的服务，因此同一 realm 中的多棵 Client 树可以使用不同载体。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
 
 -----
 
 <a id="browser-authentication-and-request-trust"></a>
 ## 浏览器认证与请求信任
 
-每个 Host RPC 方法和 WebSocket 流都要求一个浏览器会话，不存在按方法区分的 loopback 层。每个进程生成一个随机启动令牌。`dsh-web-app` 打印并打开带 `?token=...` 的普通根 URL；`frontend-static` 把根路径和 index 请求交给 `ctx.connection.authorizeIndex`，后者只在 `GET /` 接受该令牌，写入绑定 authority 的签名 cookie，再重定向到干净的 `/`。缺失、过期、畸形或 authority 不匹配的 cookie 会在 RPC 分发前得到 401。静态资源保持公开。HTTP 载体不在根路径交换之外接受 query token，也不接受 Authorization header token。
+每个 Host RPC 方法和 WebSocket 流都要求一个浏览器会话，不存在按方法区分的 loopback 层。每个进程生成一个随机启动令牌。`dsh-web-app` 打印并打开带 `?token=...` 的应用 URL，保留调用方的 authority 与挂载；`frontend-static` 把根路径和 index 请求交给 `ctx.connection.authorizeIndex`，后者只在 `GET /` 接受该令牌，写入绑定 authority 的签名 cookie，再重定向到干净的 `./`，移除令牌并保留请求目录。缺失、过期、畸形或 authority 不匹配的 cookie 会在 RPC 分发前得到 401。静态资源保持公开。HTTP 载体不在根路径交换之外接受 query token，也不接受 Authorization header token。
 
 cookie 签名密钥是 `ctx.credentials` 中由 `client-connection/browser-session` 拥有的 grant 记录。本地提供方把它持久化到 `$DSH_HOME/.credentials.yaml`；`BrowserAuth` 在 Connection 激活期间加载或创建该记录，并把密钥留在内存中，因此请求认证同步执行。删除或替换该记录会在下一次 Connection 激活时生效。cookie 携带绝对签发与过期区间，`cookieMaxAgeDays` 默认设为 30 天，并在确定性名称与签名 payload 中同时绑定规范化 hostname 和 port。它是 host-only、`Path=/`、`HttpOnly`、`SameSite=Strict`；随附服务器使用 loopback HTTP，因此刻意不设置 `Secure`。
 
 认证之前，每个请求仍经过 `src/api-request-trust.ts`。其 `Host` 必须是 loopback，或与 `trustedHosts` 条目匹配：带端口的 `host:port` 精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化。若附带 `Origin`，它必须等于该 Host；`sec-fetch-site: cross-site` 一律拒绝。畸形配置 authority 会让插件加载失败。这些检查防御 DNS rebinding 与跨站浏览器请求，绝不建立身份。Host/Origin 校验失败返回 403；Host 可信但未认证的请求返回 401。`dsh web --host 0.0.0.0` 仍不受支持。决策记录：[浏览器请求信任](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.zh.md)与[浏览器令牌认证](../../../.agents/notes/implemented/architecture/2026-08-24-browser-token-authentication.zh.md)。
 
-通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求，或等待 `next()` 直到响应完成；释放所属 fiber 会移除准入行为。Desktop 使用此扩展点，在已批准的安装期间锁住新的 API 工作，而不取消已接纳的工作。WebSocket 流仍由 API Gateway 负责。
+每个被接纳的请求都代表同一个 Peer——操作者。`ctx.connection.operator` 就是这个 `PeerScope`：其 `ctx` 是拥有连接期注册的 Cordis scope，随 Connection 一起释放。`ctx.connection.admit(request)` 执行信任与认证检查，以拒绝状态或操作者作答；`/api` 路由与 Gateway 的 WebSocket 升级都经它接纳，每个 RPC 处理器都收到本次调用的 Peer。`OperatorPeer` 对外导出，供没有 Connection 的组合（例如 Gateway 的进程内载体）以同一约定拥有一个操作者 scope。
+
+通过认证的共享 HTTP 请求在传输请求体之前经过 `connection/request` waterfall。监听器可以拒绝新请求，或等待 `next()` 直到响应完成；释放所属 fiber 会移除准入行为。Desktop 使用此扩展点，在已批准的安装期间锁住新的 API 工作，而不取消已接纳的工作。客户端断开会中止处理函数的信号；桥接器停止写入 socket，并排空剩余响应块。WebSocket 流仍由 API Gateway 负责。
 
 <a id="connection-generation"></a>
 ## Connection generation

package/lib/client.js

@@ -28,6 +28,43 @@ window.__ModuleLoader__.load({
 			for (const key of keys) if (forced || source[key] !== void 0) result[key] = source[key];
 			return result;
 		}
+		/** Shared config references used by schema validators and plugin runtimes. */
+		const write = Symbol.for("cosmokit.volatile.write");
+		function snapshot(value, ancestors = /* @__PURE__ */ new Set()) {
+			if (typeof value === "function") throw new TypeError("volatile config cannot contain functions");
+			if (value === null || typeof value !== "object") return value;
+			if (ancestors.has(value)) throw new TypeError("volatile config cannot contain cycles");
+			ancestors.add(value);
+			try {
+				if (Array.isArray(value)) return Object.freeze(value.map((item) => snapshot(item, ancestors)));
+				if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new TypeError("volatile config objects must be plain objects or arrays");
+				return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item, ancestors)])));
+			} finally {
+				ancestors.delete(value);
+			}
+		}
+		/**
+		* Create a detached reference containing an immutable copy of the supplied data.
+		* @param value - validated config data; class instances and functions are unsupported.
+		* @returns a reference whose value is updated only by its owning runtime.
+		*/
+		function createVolatile(value) {
+			let current = snapshot(value);
+			return Object.freeze({
+				get: () => current,
+				[write]: (value) => {
+					current = value;
+				}
+			});
+		}
+		/**
+		* Identify references across ESM/CJS copies of the shared library.
+		* @param value - a parsed config value.
+		* @returns whether the value implements the shared reference protocol.
+		*/
+		function isVolatile(value) {
+			return typeof value === "object" && value !== null && write in value;
+		}
 		/** Test values using `instanceof` with a `toStringTag` fallback. */
 		function is(type, value) {
 			if (arguments.length === 1) return (value) => is(type, value);
@@ -108,26 +145,47 @@ window.__ModuleLoader__.load({
 			}
 			return result;
 		}
-		/** Deeply compare arrays, dates, regexps, buffers, and plain object fields. */
+		/**
+		* Compare values recursively, treating two volatile references as equal regardless of value.
+		* Strict comparison distinguishes null/undefined, treats opaque objects by identity,
+		* compares URLs by normalized href, treats array holes as undefined, and considers distinct cyclic structures unequal.
+		* @param a - first value.
+		* @param b - second value.
+		* @param strict - whether to require strict data equality outside volatile references.
+		* @returns whether the values compare equal.
+		*/
 		function deepEqual(a, b, strict) {
-			if (a === b) return true;
-			if (!strict && isNullable(a) && isNullable(b)) return true;
-			if (typeof a !== typeof b) return false;
-			if (typeof a !== "object") return false;
-			if (!a || !b) return false;
-			function check(test, then) {
-				return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : void 0;
+			const ancestors = /* @__PURE__ */ new Set();
+			function compare(a, b) {
+				if (a === b) return true;
+				if (isVolatile(a) || isVolatile(b)) return isVolatile(a) && isVolatile(b);
+				if (!strict && isNullable(a) && isNullable(b)) return true;
+				if (typeof a !== typeof b || typeof a !== "object" || !a || !b) return false;
+				if (ancestors.has(a)) return false;
+				function check(test, then) {
+					return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : void 0;
+				}
+				ancestors.add(a);
+				try {
+					return check(Array.isArray, (a, b) => {
+						if (a.length !== b.length) return false;
+						for (let index = 0; index < a.length; index++) if (!compare(a[index], b[index])) return false;
+						return true;
+					}) ?? check(is("Date"), (a, b) => a.valueOf() === b.valueOf()) ?? check(is("URL"), (a, b) => a.href === b.href) ?? check(is("RegExp"), (a, b) => a.source === b.source && a.flags === b.flags) ?? check(isArrayBufferLike, (a, b) => {
+						if (a.byteLength !== b.byteLength) return false;
+						const viewA = new Uint8Array(a);
+						const viewB = new Uint8Array(b);
+						for (let i = 0; i < viewA.length; i++) if (viewA[i] !== viewB[i]) return false;
+						return true;
+					}) ?? ((!strict || [a, b].every((value) => Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) && Object.keys({
+						...a,
+						...b
+					}).every((key) => compare(a[key], b[key])));
+				} finally {
+					ancestors.delete(a);
+				}
 			}
-			return check(Array.isArray, (a, b) => a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))) ?? check(is("Date"), (a, b) => a.valueOf() === b.valueOf()) ?? check(is("RegExp"), (a, b) => a.source === b.source && a.flags === b.flags) ?? check(isArrayBufferLike, (a, b) => {
-				if (a.byteLength !== b.byteLength) return false;
-				const viewA = new Uint8Array(a);
-				const viewB = new Uint8Array(b);
-				for (let i = 0; i < viewA.length; i++) if (viewA[i] !== viewB[i]) return false;
-				return true;
-			}) ?? Object.keys({
-				...a,
-				...b
-			}).every((key) => deepEqual(a[key], b[key], strict));
+			return compare(a, b);
 		}
 		/** Time constants plus parsing and formatting helpers. */
 		var Time;
@@ -376,6 +434,7 @@ window.__ModuleLoader__.load({
 			return schema;
 		};
 		Schema.prototype.simplify = function simplify(value) {
+			if (isVolatile(value)) value = value.get();
 			if (deepEqual(value, this.meta.default, this.type === "dict")) return null;
 			if (isNullable(value)) return value;
 			if (this.type === "object" || this.type === "dict") {
@@ -432,12 +491,49 @@ window.__ModuleLoader__.load({
 			};
 			return schema;
 		} });
+		Schema.prototype.volatile = function volatile() {
+			if (this.meta.volatile) throw new TypeError("volatile schema is already wrapped");
+			return this.extra("volatile", true);
+		};
 		const resolvers = {};
+		const checkedVolatile = Symbol("checked-volatile-schema");
+		function validateVolatileSchema(schema, path = [], blocked = false, seen = /* @__PURE__ */ new Map()) {
+			const states = seen.get(schema) ?? /* @__PURE__ */ new Set();
+			if (states.has(blocked)) return;
+			states.add(blocked);
+			seen.set(schema, states);
+			if (schema.meta?.volatile && blocked) throw new ValidationError("volatile fields require a fixed object path without an enclosing volatile field", { path });
+			const nested = blocked || !!schema.meta?.volatile;
+			if (schema.dict) for (const [key, child] of Object.entries(schema.dict)) validateVolatileSchema(child, [...path, key], nested, seen);
+			if (schema.sKey) validateVolatileSchema(schema.sKey, [...path, "<key>"], true, seen);
+			if (schema.inner && (schema.type !== "lazy" || schema.inner[kSchema])) validateVolatileSchema(schema.inner, [...path, "*"], true, seen);
+			if (schema.list) for (let index = 0; index < schema.list.length; index++) validateVolatileSchema(schema.list[index], [...path, String(index)], true, seen);
+		}
 		Schema.extend = function extend(type, resolve) {
 			resolvers[type] = resolve;
 		};
 		Schema.resolve = function resolve(data, schema, options = {}, strict = false) {
 			if (!schema) return [data];
+			if (!options[checkedVolatile]) {
+				validateVolatileSchema(schema, options.path);
+				options = {
+					...options,
+					[checkedVolatile]: true
+				};
+			}
+			if (schema.meta?.volatile) {
+				const inner = Schema(schema);
+				inner.meta = {
+					...schema.meta,
+					volatile: false
+				};
+				const [value, adapted] = Schema.resolve(data, inner, options, strict);
+				try {
+					return [createVolatile(value), adapted];
+				} catch (error) {
+					throw new ValidationError(error instanceof Error ? error.message : String(error), options);
+				}
+			}
 			if (options.ignore?.(data, schema)) return [data];
 			if (isNullable(data) && schema.type !== "lazy") {
 				if (schema.meta.required) throw new ValidationError(`missing required value`, options);
@@ -540,6 +636,7 @@ window.__ModuleLoader__.load({
 					...schema.meta,
 					...schema.inner.meta
 				};
+				validateVolatileSchema(schema.inner, options.path, true);
 			}
 			return Schema.resolve(data, schema.inner, options, strict);
 		});
@@ -639,7 +736,7 @@ window.__ModuleLoader__.load({
 			} catch (e) {
 				if (!options?.autofix) throw e;
 				delete data[key];
-				return schema.meta.default;
+				return schema.meta.volatile ? createVolatile(schema.meta.default) : schema.meta.default;
 			}
 		}
 		Schema.extend("array", (data, { inner, meta }, options) => {
@@ -1101,7 +1198,6 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region lib/types/client/rpc.js
 		/** Browser caller for generic Connection unary RPC channels. */
-		const INTERNAL_BASE = "http://dsh.internal";
 		const CHANNEL_PATTERN = /^\/[A-Za-z0-9._~-]+$/;
 		const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 		/**
@@ -1122,24 +1218,73 @@ window.__ModuleLoader__.load({
 						method: endpoint,
 						payload
 					};
-					const response = await send(new URL(`${channel}/${endpoint}`, resolveBase()), {
+					const response = await send(`${channel}/${endpoint}`.slice(1), {
 						method: "POST",
 						headers: { "content-type": "application/json" },
 						body: JSON.stringify(message),
 						...signal === void 0 ? {} : { signal }
 					});
 					if (!response.ok) throw new Error(`transport failure for ${channel}/${endpoint}: HTTP ${response.status}`);
-					const full = parseConnectionResponse(await response.json());
+					const full = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() === "multipart/form-data" ? await parseBinaryResponse(response) : parseConnectionResponse(await response.json());
+					signal?.throwIfAborted();
 					if (full.rpcId !== rpcId) throw new Error(`rpcId mismatch for ${endpoint}: sent ${rpcId}, got ${full.rpcId}`);
 					return full.result;
 				},
-				...openStream === void 0 ? {} : { open(channel, endpoint, payload, signal) {
+				...openStream === void 0 ? {} : { open(channel, endpoint, payload, signal, uplink) {
 					assertTarget(channel, endpoint);
 					if (channel !== "/api") throw new Error(`connection: worker-local streams require the /api channel, got ${JSON.stringify(channel)}`);
-					return openStream(endpoint, payload, signal);
+					return openStream(endpoint, payload, signal, uplink);
 				} }
 			};
 		}
+		async function parseBinaryResponse(response) {
+			const body = await response.formData();
+			const fields = /* @__PURE__ */ new Map();
+			for (const [name, value] of body) {
+				if (fields.has(name)) throw new TypeError("connection: invalid binary response fields");
+				fields.set(name, value);
+			}
+			const metadata = fields.get("metadata");
+			fields.delete("metadata");
+			if (typeof metadata !== "string") throw new TypeError("connection: invalid binary response fields");
+			const envelope = JSON.parse(metadata);
+			const full = parseConnectionResponse(envelope);
+			if (!full.result.ok || !isRecord(envelope) || !Array.isArray(envelope.attachments) || envelope.attachments.length === 0) throw new TypeError("connection: invalid binary response result");
+			const root = { value: full.result.value };
+			for (const attachment of envelope.attachments) {
+				if (!isRecord(attachment) || attachment.codec !== "bytes" || typeof attachment.part !== "string" || !Array.isArray(attachment.path)) throw new TypeError("connection: invalid binary response attachment");
+				const data = fields.get(attachment.part);
+				fields.delete(attachment.part);
+				if (!(data instanceof Blob)) throw new TypeError("connection: invalid binary response fields");
+				let parent = root;
+				let key = "value";
+				for (const segment of attachment.path) {
+					const value = Reflect.get(parent, key);
+					if (typeof value !== "object" || value === null) throw new TypeError("connection: invalid binary response path");
+					if (Array.isArray(value)) {
+						if (typeof segment !== "number" || !Number.isSafeInteger(segment) || segment < 0 || segment >= value.length) throw new TypeError("connection: invalid binary response path");
+					} else if (typeof segment !== "string") throw new TypeError("connection: invalid binary response path");
+					if (!Object.hasOwn(value, segment)) throw new TypeError("connection: invalid binary response path");
+					parent = value;
+					key = segment;
+				}
+				if (Reflect.get(parent, key) !== null) throw new TypeError("connection: invalid binary response placeholder");
+				Object.defineProperty(parent, key, {
+					value: new Uint8Array(await data.arrayBuffer()),
+					enumerable: true,
+					writable: true,
+					configurable: true
+				});
+			}
+			if (fields.size !== 0) throw new TypeError("connection: invalid binary response fields");
+			return {
+				rpcId: full.rpcId,
+				result: {
+					ok: true,
+					value: root.value
+				}
+			};
+		}
 		function parseConnectionResponse(value) {
 			if (!isRecord(value) || value.type !== "server-response" || typeof value.rpcId !== "string") throw new TypeError("connection: invalid server-response envelope");
 			const result = value.result;
@@ -1169,10 +1314,6 @@ window.__ModuleLoader__.load({
 		function isRecord(value) {
 			return typeof value === "object" && value !== null && !Array.isArray(value);
 		}
-		function resolveBase() {
-			const location = globalThis.location;
-			return location?.origin !== void 0 && location.origin !== "null" ? location.origin : INTERNAL_BASE;
-		}
 		function assertTarget(channel, endpoint) {
 			const segments = endpoint.split("/");
 			if (!CHANNEL_PATTERN.test(channel) || segments.some((segment) => segment === "" || segment === "." || segment === ".." || !ENDPOINT_SEGMENT_PATTERN.test(segment))) throw new Error(`connection: invalid RPC target ${JSON.stringify(`${channel}/${endpoint}`)}`);

package/lib/index.js

@@ -1,9 +1,10 @@
 import z from "@deepseek-ai/schemastery";
 import { Readable } from "node:stream";
-import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { credentialKey } from "@deepseek-ai/dsh-credentials";
 import { Service } from "@deepseek-ai/cordis";
 import { z as z$1 } from "zod";
+import { createScope } from "@deepseek-ai/dsh-scope";
 //#region lib/types/api-path.js
 /**
 * The /api URL prefix — single source for both halves of the web transport.
@@ -24,7 +25,7 @@ const API_PATH = "/api";
 const DEFAULT_MAX_REQUEST_BODY_BYTES = 300 * 1024 * 1024;
 /**
 * Bridge one node:http request to the fetch-shaped handler (client close
-* aborts; response bodies stream out chunk by chunk).
+* aborts; response writes respect backpressure and stop on disconnect).
 * @param req - incoming node:http request.
 * @param res - node:http response the bridge writes and owns to completion.
 * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
@@ -90,15 +91,18 @@ async function bridge(req, res, apiHandler, maxRequestBodyBytes = DEFAULT_MAX_RE
 		if (requestUnread) req.destroy();
 		return;
 	}
-	for await (const chunk of response.body) if (!res.write(chunk)) await new Promise((resolve) => {
-		const done = () => {
-			res.off("drain", done);
-			res.off("close", done);
-			resolve();
-		};
-		res.once("drain", done);
-		res.once("close", done);
-	});
+	for await (const chunk of response.body) {
+		if (abort.signal.aborted) continue;
+		if (!res.write(chunk) && !res.destroyed) await new Promise((resolve) => {
+			const done = () => {
+				res.off("drain", done);
+				res.off("close", done);
+				resolve();
+			};
+			res.once("drain", done);
+			res.once("close", done);
+		});
+	}
 	res.end();
 	if (requestUnread) req.destroy();
 }
@@ -363,22 +367,20 @@ var BrowserAuth = class BrowserAuth {
 		return new BrowserAuth(processOwner, await initializeSecret(credentials), maxAgeDays);
 	}
 	/**
-	* Add this process's launch token to the ordinary application root URL.
-	* @param baseUrl - canonical browser origin without credentials.
-	* @returns root URL carrying the process token as its sole authentication input.
+	* Add this process's launch token to the caller's application URL.
+	* @param baseUrl - clean browser URL whose authority and mount are preserved.
+	* @returns the same URL carrying the process token as its sole authentication input.
 	*/
 	authenticatedUrl(baseUrl) {
 		const url = new URL(baseUrl);
-		url.pathname = "/";
-		url.search = "";
-		url.hash = "";
 		url.searchParams.set(TOKEN_QUERY, this.launchToken);
 		return url.href;
 	}
 	/**
 	* Authenticate an index request. A valid root query token mints the cookie
-	* and redirects to clean `/`; a valid cookie lets the caller serve the
-	* index; every other request receives the same minimal 401 response.
+	* and redirects to the directory-relative clean `./`; a valid cookie lets
+	* the caller serve the index; every other request receives the same minimal
+	* 401 response.
 	* @param req - incoming root or configured-index request.
 	* @param res - response owned when this method returns false.
 	* @returns true only when the caller may serve index.html.
@@ -400,7 +402,7 @@ var BrowserAuth = class BrowserAuth {
 				}, this.secret);
 				res.writeHead(303, {
 					"cache-control": "no-store",
-					"location": "/",
+					"location": "./",
 					"referrer-policy": "no-referrer",
 					"set-cookie": sessionCookie(cookieName(authority), value, expiresAt, Math.floor(this.maxAgeMilliseconds / 1e3))
 				});
@@ -410,7 +412,7 @@ var BrowserAuth = class BrowserAuth {
 			if (req.method === "GET" && url.pathname === "/" && this.isAuthenticated(req)) {
 				res.writeHead(303, {
 					"cache-control": "no-store",
-					"location": "/",
+					"location": "./",
 					"referrer-policy": "no-referrer"
 				});
 				res.end();
@@ -514,6 +516,33 @@ const serverResponseSchema = z$1.object({
 /** Either Connection RPC envelope direction. */
 const rpcMessageSchema = z$1.discriminatedUnion("type", [clientRequestSchema, serverResponseSchema]);
 //#endregion
+//#region lib/types/operator-peer.js
+/**
+* The operator Peer: the one party this Host answers to. Connection owns it
+* for its own lifetime, admits every request as it, and hands it to each
+* Remote call as `invocation.peer`.
+* @module @deepseek-ai/dsh-client-connection/src/operator-peer
+*/
+/**
+* The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+* returns it and events dispatched with `scopeTarget(subject, peer)` reach
+* listeners registered through `peer.ctx` and nobody else.
+*/
+var OperatorPeer = class {
+	id = randomUUID();
+	ctx;
+	scope;
+	/** @param owner - Connection plugin context the scope fiber hangs under. */
+	constructor(owner) {
+		this.scope = createScope(owner, this);
+		this.ctx = this.scope.ctx;
+	}
+	/** Tear down every connection-lifetime registration; racing calls share one completion. */
+	dispose() {
+		return this.scope.dispose();
+	}
+};
+//#endregion
 //#region lib/types/rpc-host.js
 /** Host registry and HTTP adapter for generic Connection RPC channels. */
 const INVALID_REQUEST_RPC_ID = RpcId("invalid-request");
@@ -523,6 +552,8 @@ const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
 var HostConnectionService = class extends Service {
 	trustedHosts;
 	browserAuth;
+	/** The operator Peer every admitted request speaks for. */
+	operator;
 	interceptors = /* @__PURE__ */ new Map();
 	fetchRoutes = /* @__PURE__ */ new Map();
 	/**
@@ -535,6 +566,8 @@ var HostConnectionService = class extends Service {
 		super(ctx, "connection");
 		this.trustedHosts = trustedHosts;
 		this.browserAuth = browserAuth;
+		this.operator = new OperatorPeer(ctx);
+		ctx.effect(() => () => this.operator.dispose(), "client-connection: operator Peer");
 	}
 	/** Generic channel registry scoped to the Context reading this service. */
 	get rpc() {
@@ -554,6 +587,11 @@ var HostConnectionService = class extends Service {
 		if (!isTrustedApiRequest(request, this.trustedHosts)) return 403;
 		return this.browserAuth.isAuthenticated(request) ? void 0 : 401;
 	}
+	/** A request that passes the fence and authentication speaks for the operator. */
+	admit(request) {
+		const rejection = this.requestRejection(request);
+		return rejection === void 0 ? { peer: this.operator } : { rejection };
+	}
 	/** Authenticate an index request through the process-token exchange or cookie. */
 	authorizeIndex(request, response) {
 		return this.browserAuth.authorizeIndex(request, response);
@@ -601,15 +639,15 @@ var HostConnectionService = class extends Service {
 	}
 	register(owner, channel, handler) {
 		assertChannel(channel);
-		const fetchHandler = rpcFetchHandler(channel, handler);
+		const fetchHandler = rpcFetchHandler(channel, handler, this.operator);
 		const route = {
 			kind: "prefix",
 			path: channel,
 			handler: async (req, res) => {
-				const rejection = this.requestRejection(req);
-				if (rejection !== void 0) {
-					res.writeHead(rejection);
-					res.end(rejection === 401 ? "unauthorized" : "forbidden");
+				const admission = this.admit(req);
+				if ("rejection" in admission) {
+					res.writeHead(admission.rejection);
+					res.end(admission.rejection === 401 ? "unauthorized" : "forbidden");
 					return;
 				}
 				await bridge(req, res, fetchHandler);
@@ -621,7 +659,7 @@ var HostConnectionService = class extends Service {
 		if (channel !== "/api") throw new Error(`connection: invalid shared RPC channel ${JSON.stringify(channel)}`);
 		const interceptor = {
 			matches,
-			fetchHandler: rpcFetchHandler(channel, handler)
+			fetchHandler: rpcFetchHandler(channel, handler, this.operator)
 		};
 		return owner.effect(() => {
 			if (this.interceptors.has(channel)) throw new Error(`connection: shared RPC channel ${JSON.stringify(channel)} already has an interceptor`);
@@ -632,7 +670,7 @@ var HostConnectionService = class extends Service {
 		}, `client-connection: ${channel} rpc interceptor`);
 	}
 };
-function rpcFetchHandler(channel, handler) {
+function rpcFetchHandler(channel, handler, peer) {
 	return {
 		requestBodyMode: () => "buffered",
 		async fetch(request) {
@@ -654,7 +692,7 @@ function rpcFetchHandler(channel, handler) {
 				details: { issues: [] }
 			});
 			try {
-				const result = await handler(endpoint, message.payload, request.signal);
+				const result = await handler(endpoint, message.payload, request.signal, peer);
 				return fullResponse(message.rpcId, result);
 			} catch (error) {
 				return new Response(`handler failure: ${String(error)}`, { status: 500 });
@@ -683,12 +721,36 @@ function errorResponse(rpcId, error) {
 	});
 }
 function fullResponse(rpcId, result) {
+	if (!result.ok) {
+		const body = {
+			type: "server-response",
+			rpcId,
+			result
+		};
+		return Response.json(body);
+	}
+	const { attachments, ...success } = result;
 	const body = {
 		type: "server-response",
 		rpcId,
-		result
+		result: success
 	};
-	return Response.json(body);
+	if (attachments === void 0 || attachments.length === 0) return Response.json(body);
+	const parts = new FormData();
+	const attachmentMetadata = attachments.map((attachment, index) => {
+		const part = `bytes-${index}`;
+		parts.set(part, new Blob([new Uint8Array(attachment.bytes)]));
+		return {
+			path: [...attachment.path],
+			codec: "bytes",
+			part
+		};
+	});
+	parts.set("metadata", JSON.stringify({
+		...body,
+		attachments: attachmentMetadata
+	}));
+	return new Response(parts);
 }
 function assertChannel(channel) {
 	if (!CHANNEL_PATTERN.test(channel) || channel === "/api") throw new Error(`connection: invalid or reserved RPC channel ${JSON.stringify(channel)}`);
@@ -769,10 +831,10 @@ async function apply(ctx, config) {
 			kind: "prefix",
 			path: API_PATH,
 			handler: async (req, res) => {
-				const rejection = connection.requestRejection(req);
-				if (rejection !== void 0) {
-					res.writeHead(rejection);
-					res.end(rejection === 401 ? "unauthorized" : "forbidden");
+				const admission = connection.admit(req);
+				if ("rejection" in admission) {
+					res.writeHead(admission.rejection);
+					res.end(admission.rejection === 401 ? "unauthorized" : "forbidden");
 					return;
 				}
 				await webCtx.waterfall("connection/request", req, res, () => bridge(req, res, fetchHandler, maxRequestBodyBytes));
@@ -785,4 +847,4 @@ async function apply(ctx, config) {
 	});
 }
 //#endregion
-export { API_PATH, Config, HostConnectionService, RpcId, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };
+export { API_PATH, Config, HostConnectionService, OperatorPeer, RpcId, apply, clientRequestSchema, inject, name, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, transportError };

package/lib/types/browser-auth.d.ts

@@ -21,15 +21,16 @@ export declare class BrowserAuth {
      */
     static create(processOwner: object, credentials: CredentialProvider, maxAgeDays: number): Promise<BrowserAuth>;
     /**
-     * Add this process's launch token to the ordinary application root URL.
-     * @param baseUrl - canonical browser origin without credentials.
-     * @returns root URL carrying the process token as its sole authentication input.
+     * Add this process's launch token to the caller's application URL.
+     * @param baseUrl - clean browser URL whose authority and mount are preserved.
+     * @returns the same URL carrying the process token as its sole authentication input.
      */
     authenticatedUrl(baseUrl: string): string;
     /**
      * Authenticate an index request. A valid root query token mints the cookie
-     * and redirects to clean `/`; a valid cookie lets the caller serve the
-     * index; every other request receives the same minimal 401 response.
+     * and redirects to the directory-relative clean `./`; a valid cookie lets
+     * the caller serve the index; every other request receives the same minimal
+     * 401 response.
      * @param req - incoming root or configured-index request.
      * @param res - response owned when this method returns false.
      * @returns true only when the caller may serve index.html.

package/lib/types/client/rpc.d.ts

@@ -1,9 +1,12 @@
 /** Browser caller for generic Connection unary RPC channels. */
 import type { ClientConnectionRpc } from '../rpc.ts';
-/** Transport this caller posts through; same signature as the global `fetch`. */
-export type RpcFetch = (input: URL, init: RequestInit) => Promise<Response>;
-/** Worker-local opener for decoded Gateway Remote streams. */
-export type RpcStreamOpen = (endpoint: string, payload: unknown, signal: AbortSignal) => AsyncIterable<unknown>;
+/**
+ * Transport this caller posts through; same signature as the global `fetch`.
+ * Receives the document-relative route so a carrier resolves it against its own base.
+ */
+export type RpcFetch = (input: string | URL, init: RequestInit) => Promise<Response>;
+/** Worker-local opener for decoded Gateway Remote streams; `uplink` carries the Client's items for the stream. */
+export type RpcStreamOpen = (endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>) => AsyncIterable<unknown>;
 /**
  * Create the browser-backed generic RPC caller.
  * @param doFetch - transport override; defaults to the page's global fetch.

package/lib/types/http-bridge.d.ts

@@ -2,20 +2,31 @@
  * node:http ↔ WHATWG fetch bridge for the /api transport (host side of the
  * web carrier; the fetch-shaped handler itself is transport-agnostic).
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { IncomingMessage } from 'node:http';
 import type { ConnectionFetchHandler } from './rpc.ts';
 /** Default carrier cap for all HTTP RPC bodies: sized for the default
  * aggregate image limit (200 MiB) after base64 expansion plus envelope
  * headroom (~267.7 MiB required), rounded up for slack. The bridge buffers
  * each body in memory, so this cap is also the per-request resident bound. */
 export declare const DEFAULT_MAX_REQUEST_BODY_BYTES: number;
+interface BridgeServerResponse {
+    readonly destroyed: boolean;
+    readonly writableEnded: boolean;
+    on(event: 'close', listener: () => void): this;
+    off(event: 'close' | 'drain', listener: () => void): this;
+    once(event: 'close' | 'drain', listener: () => void): this;
+    writeHead(statusCode: number, headers?: Record<string, string>): unknown;
+    write(chunk: Uint8Array): boolean;
+    end(): unknown;
+}
 /**
  * Bridge one node:http request to the fetch-shaped handler (client close
- * aborts; response bodies stream out chunk by chunk).
+ * aborts; response writes respect backpressure and stop on disconnect).
  * @param req - incoming node:http request.
  * @param res - node:http response the bridge writes and owns to completion.
  * @param apiHandler - fetch-shaped API carrier the request is dispatched to.
  * @param maxRequestBodyBytes - maximum bytes buffered for a buffered route.
  */
-export declare function bridge(req: IncomingMessage, res: ServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+export declare function bridge(req: IncomingMessage, res: BridgeServerResponse, apiHandler: ConnectionFetchHandler, maxRequestBodyBytes?: number): Promise<void>;
+export {};
 //# sourceMappingURL=http-bridge.d.ts.map

package/lib/types/index.d.ts

@@ -3,8 +3,10 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import z from '@deepseek-ai/schemastery';
 import { type ConnectionRecoveryConfig } from './recovery-config.ts';
-export type { ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionRpcEndpointMatcher, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
+export type { PeerAdmission, ConnectionFetchMethod, ConnectionFetchHandler, ConnectionFetchRoute, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionRpcEndpointMatcher, ConnectionRpcAttachment, ConnectionRpcFailure, ConnectionRpcHandler, ConnectionRpcHandlerResult, ConnectionRequestRejection, ConnectionRpcResult, ConnectionRequestBodyMode, ConnectionTrustRequest, ClientRequest, HostConnectionHandle, HostConnectionFetch, HostConnectionRpc, RpcMessage, ServerResponse, } from './rpc.ts';
+export type { PeerId, PeerScope, RemoteInvocation } from '@deepseek-ai/dsh-typert-protocol';
 export { RpcId, transportError } from './rpc.ts';
+export { OperatorPeer } from './operator-peer.ts';
 export { clientRequestSchema, rpcErrorSchema, rpcIdSchema, rpcMessageSchema, rpcResultSchema, serverResponseSchema, } from './rpc-schema.ts';
 export { HostConnectionService } from './rpc-host.ts';
 export { API_PATH } from './api-path.ts';

package/lib/types/operator-peer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The operator Peer: the one party this Host answers to. Connection owns it
+ * for its own lifetime, admits every request as it, and hands it to each
+ * Remote call as `invocation.peer`.
+ * @module @deepseek-ai/dsh-client-connection/src/operator-peer
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PeerId, PeerScope } from '@deepseek-ai/dsh-typert-protocol';
+/**
+ * The operator's scope. The instance is its own scope key, so `scopeOf(peer.ctx)`
+ * returns it and events dispatched with `scopeTarget(subject, peer)` reach
+ * listeners registered through `peer.ctx` and nobody else.
+ */
+export declare class OperatorPeer implements PeerScope {
+    readonly id: PeerId;
+    readonly ctx: Context;
+    private readonly scope;
+    /** @param owner - Connection plugin context the scope fiber hangs under. */
+    constructor(owner: Context);
+    /** Tear down every connection-lifetime registration; racing calls share one completion. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=operator-peer.d.ts.map

package/lib/types/rpc-host.d.ts

@@ -1,7 +1,8 @@
 /** Host registry and HTTP adapter for generic Connection RPC channels. */
 import { Context, Service } from '@deepseek-ai/cordis';
+import type { PeerScope } from '@deepseek-ai/dsh-typert-protocol';
 import type { BrowserAuth } from './browser-auth.ts';
-import type { ConnectionIndexRequest, ConnectionIndexResponse, ConnectionFetchHandler, HostConnectionFetch, ConnectionRequestRejection, ConnectionTrustRequest, HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
+import type { PeerAdmission, ConnectionIndexRequest, ConnectionIndexResponse, ConnectionFetchHandler, HostConnectionFetch, ConnectionRequestRejection, ConnectionTrustRequest, HostConnectionHandle, HostConnectionRpc } from './rpc.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** Host Connection transport and RPC registrations. */
@@ -12,6 +13,8 @@ declare module '@deepseek-ai/cordis' {
 export declare class HostConnectionService extends Service implements HostConnectionHandle {
     private readonly trustedHosts;
     private readonly browserAuth;
+    /** The operator Peer every admitted request speaks for. */
+    readonly operator: PeerScope;
     private readonly interceptors;
     private readonly fetchRoutes;
     /**
@@ -27,6 +30,8 @@ export declare class HostConnectionService extends Service implements HostConnec
     get fetch(): HostConnectionFetch;
     /** Apply the configured Host/Origin fence, then browser authentication. */
     requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
+    /** A request that passes the fence and authentication speaks for the operator. */
+    admit(request: ConnectionTrustRequest): PeerAdmission;
     /** Authenticate an index request through the process-token exchange or cookie. */
     authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
     /** Add this process's launch token to the clean application URL. */

package/lib/types/rpc.d.ts

@@ -1,5 +1,6 @@
 /** Generic unary RPC contracts shared by the Host and Client Connection halves. */
 import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { PeerScope } from '@deepseek-ai/dsh-typert-protocol';
 /** Correlation id minted by a caller and echoed by the Connection response. */
 export type RpcId = Branded<'rpc-id'>;
 /**
@@ -22,6 +23,23 @@ export type ConnectionRpcResult<T> = {
     readonly ok: false;
     readonly error: ConnectionRpcFailure;
 };
+/** One binary value separated from a successful RPC result before transport framing. */
+export interface ConnectionRpcAttachment {
+    /** Result-relative path occupied by the attachment's `null` placeholder. */
+    readonly path: readonly (string | number)[];
+    /** Byte view carried outside the JSON response metadata. */
+    readonly bytes: Uint8Array;
+}
+/** Successful or failed handler result ready for Connection transport framing. */
+export type ConnectionRpcHandlerResult = {
+    readonly ok: true;
+    readonly value: unknown;
+    /** Binary fields already projected by the handler that owns the result protocol. */
+    readonly attachments?: readonly ConnectionRpcAttachment[];
+} | {
+    readonly ok: false;
+    readonly error: ConnectionRpcFailure;
+};
 /** Historical short name for a generic Connection result. */
 export type RpcResult<T> = ConnectionRpcResult<T>;
 /**
@@ -72,8 +90,17 @@ export interface ConnectionIndexResponse {
     writeHead(status: number, headers?: Readonly<Record<string, string>>): unknown;
     end(body?: string): unknown;
 }
-/** Handler invoked after Connection has decoded the transport envelope. */
-export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcResult<unknown>>;
+/** Outcome of admitting one request: the operator Peer it speaks for, or the status refusing it. */
+export type PeerAdmission = {
+    readonly peer: PeerScope;
+} | {
+    readonly rejection: 401 | 403;
+};
+/**
+ * Handler invoked after Connection has decoded the transport envelope.
+ * `peer` is the Peer the request was admitted as: the operator.
+ */
+export type ConnectionRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal, peer: PeerScope) => Promise<ConnectionRpcHandlerResult>;
 /** Synchronous ownership test for one endpoint on a shared RPC channel. */
 export type ConnectionRpcEndpointMatcher = (endpoint: string) => boolean;
 /** HTTP methods supported by exact Fetch routes on the shared API channel. */
@@ -118,12 +145,14 @@ export interface HostConnectionRpc {
      */
     intercept(channel: '/api', matches: ConnectionRpcEndpointMatcher, handler: ConnectionRpcHandler): () => Promise<void>;
 }
-/** Host `ctx.connection` shape consumed by transport-independent adapters. */
+/** Host `ctx.connection` members consumed by transport-independent adapters. */
 export interface HostConnectionHandle {
     /** Generic RPC channel registry. */
     readonly rpc: HostConnectionRpc;
     /** Exact Fetch routes for streaming or browser-native responses. */
     readonly fetch: HostConnectionFetch;
+    /** The operator Peer every admitted request speaks for; its scope lives as long as Connection. */
+    readonly operator: PeerScope;
     /**
      * Compose exact Fetch routes and the shared-channel RPC interceptor.
      * @param channel - shared channel mounted by Connection.
@@ -137,6 +166,13 @@ export interface HostConnectionHandle {
      * @returns rejection status, or undefined when the route may accept the request.
      */
     requestRejection(request: ConnectionTrustRequest): ConnectionRequestRejection;
+    /**
+     * Admit one request: it passes {@link requestRejection} and speaks for the
+     * operator, or it is refused with that status.
+     * @param request - request headers from the HTTP or upgrade request.
+     * @returns the operator Peer, or the rejection status.
+     */
+    admit(request: ConnectionTrustRequest): PeerAdmission;
     /**
      * Authenticate one frontend index request, owning a token redirect or 401.
      * @param request - root or configured-index HTTP request.
@@ -146,8 +182,8 @@ export interface HostConnectionHandle {
     authorizeIndex(request: ConnectionIndexRequest, response: ConnectionIndexResponse): boolean;
     /**
      * Add the fresh process token to an ordinary Web application URL.
-     * @param baseUrl - clean canonical browser origin.
-     * @returns root URL accepted by {@link authorizeIndex} for initial login.
+     * @param baseUrl - clean application URL whose authority and mount are preserved.
+     * @returns tokenized URL for initial login; a mount proxy strips its prefix before {@link authorizeIndex}.
      */
     authenticatedUrl(baseUrl: string): string;
 }
@@ -187,8 +223,9 @@ export interface ClientConnectionRpc {
      * @param endpoint - channel-relative endpoint such as `session/follow`.
      * @param payload - channel-owned request payload.
      * @param signal - caller cancellation for this logical stream.
+     * @param uplink - Client uplink items the Host method reads through `invocation.uplink()`.
      * @returns decoded stream values from the in-process carrier.
      */
-    readonly open?: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal) => AsyncIterable<unknown>;
+    readonly open?: (channel: string, endpoint: string, payload: unknown, signal: AbortSignal, uplink?: AsyncIterable<unknown>) => AsyncIterable<unknown>;
 }
 //# sourceMappingURL=rpc.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-connection",
   "description": "Authenticated RPC transport and generation lifecycle",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -35,8 +35,8 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-credentials": "^0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.3",
+    "@deepseek-ai/dsh-credentials": "^0.1.7-alpha.1"
   },
   "files": [
     "lib/index.js",
@@ -44,14 +44,17 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-scope": "^0.1.7-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-attachment": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-brand": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-llm": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-scope": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.7-alpha.1"
   }
 }