@deepseek-ai/dsh-remote-mock 0.1.6-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/test-support/remote-mock/README.md
+README.md: 82979e37052aecee6ec716702f634d25c969f5ad
+README.zh.md: 201ca011410dd5a4d65b6ebdfb0c47f23742b0d3

package/README.md

@@ -0,0 +1,146 @@
+---
+description: "Endpoint-named mock for Typert Remote traffic: a table of unary answers and stream scripts, live stream control, a log, and the Connection carrier face, for test authors booting a real browser client without a Host."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-remote-mock
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-remote-mock` lets tests configure Host responses through `mock.remote.<namespace>.<method>` using native Vitest mock methods. The same functions answer direct calls and real Connection traffic; reusable tables supply default responses, and explicitly declared streams support test-driven frames and cancellation. Missing responses fail the call and are reported again by `assertNoUnmatched()` at teardown. The package runs without a business Host in Node or a browser page, imports no DOM, React, or Node modules, and is consumed from `devDependencies` only.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+### When to use it
+
+Use it when a spec boots real client plugins that talk to `ctx.remote` and wants to script the Host side by endpoint name: whole-client specs bind `mock.rpc` to their Connection instance, while unit specs may call `mock.remote`, `dispatch`, or `open` directly. Endpoints are the Gateway's wire names (`session/page`, `settings/describe`); `args` is the caller's positional argument list with a trailing `AbortSignal` removed; a value is whatever the test registers and is answered unchanged. The only declaration is whether an endpoint is unary (`unary`) or a stream (`stream`).
+
+<a id="remote-proxy"></a>
+### Use the Remote proxy
+
+`mock.remote` exposes every namespace and method without a method list or a domain-specific helper. Each accessed endpoint uses a cached native Vitest mock; `@vitest/spy.fn` is the implementation behind `vi.fn` and also works in a browser page without the Vitest runner. The same mock answers direct calls and Connection traffic, so return overrides and call assertions observe the functions the client actually invokes:
+
+```text
+const mock = RemoteMock.create().load(remoteDefaultResponses)
+mock.remote.settings.describe.mockResolvedValue(ok({
+  writable: true, hasDocument: false, namespaces: [],
+}))
+mock.remote.settings.mutate.mockResolvedValueOnce(ok(updatedNamespace))
+// After the client writes:
+expect(mock.remote.settings.mutate).toHaveBeenCalledWith('locale', operations, revision)
+```
+
+Use `mockResolvedValue` for a persistent response, `mockResolvedValueOnce` or `mockReturnValueOnce` for queued responses, and `mockImplementation` for argument-dependent behavior. Native queued responses run in registration order, then the mock's current implementation answers. Its initial implementation reads the registered default. `mockClear()` preserves responses and queues; `mockReset()` clears overrides and restores that initial implementation, which reads the latest default. Missing defaults still fail after queued responses are exhausted, including direct calls, which can throw synchronously.
+
+Only explicit `stream()` or table stream declarations select stream methods; everything else uses unary mocks. Accessing a method does not fabricate a successful business result. Declare stream mode before retaining a method reference: each endpoint/mode owns its own mock. Namespace and method `then` probes and symbol reads are inert.
+
+`MockedRemote` uses Vitest's deep mock transformation over the entire generated `TypertRemoteNamespaceMap`. A non-empty map preserves its namespace and method names, parameters, results, and native spy types. An empty map makes only this test proxy `any`, allowing arbitrary namespaces and methods; it does not augment or weaken production Remote declarations. No copied method signatures, optional generated-module suppressions, or compiler-wide flags are needed. Before handing off Remote/mock changes, run `pnpm run typecheck` to generate and check the real Client types; missing, stale, or partial declarations require rebuilding first. Unbuilt test success or `any` inference is not strict type evidence.
+
+### Register default responses
+
+`load(table)` installs reusable `unary` values or handlers, `stream` scripts, and scriptless `streams` declarations. `unary(endpoint, value)` and `unary(endpoint, fn)` register individual defaults; handlers receive the caller's positional arguments and use existing request types. Each endpoint holds only its latest default, including an explicit `undefined`; updating defaults does not discard native overrides. `ok(value)` builds `{ ok: true, value }`; failures use `{ ok: false, error: { code, message, details } }`. Keep stateful handlers, promises, and native queues local to each test:
+
+```text
+const initial = { writable: true, hasDocument: false, namespaces: [] }
+const mock = RemoteMock.create().load({
+  unary: { 'settings/describe': ok(initial) },
+})
+mock.remote.settings.describe.mockResolvedValueOnce(ok({ ...initial, hasDocument: true }))
+```
+
+### Drive streams
+
+A stream script is a function of the open `args` and a `StreamHandle` (`push`, `end`, `fail(error)`, `signal`); the stream stays open after the script returns until the handle ends or fails it. `frames(items)` builds a script that yields the items and ends; `openStream(initial)` one that yields them and stays open. `mock.streams` controls streams the client currently holds open, filtered by the args they were opened with; `opened(endpoint, count)` resolves once the endpoint has been opened that many times, and `drained(endpoint)` once the consumer of every matching stream has pulled everything pushed so far, an open stream's consumer waiting for more and a settled stream's queue empty (pulled from the queue; that equals processed only for a consumer that handles items inside its read loop):
+
+```text
+mock.stream('session/follow', openStream([snapshotFrame]))
+await mock.streams.opened('session/follow', 1)
+mock.streams.push('session/follow', eventFrame, ([request]) => (request as { sessionId: string }).sessionId === SID)
+mock.streams.fail('session/follow', new Error('gone'))
+await mock.streams.drained('session/follow')
+```
+
+A failed stream rejects the consumer's next read with the given `Error`. Consumer cancellation (the opening signal or an early iterator `return()`) aborts `StreamHandle.signal`, ends the iteration without throwing, and logs the stream as `cancelled`.
+
+### Connect a client
+
+`mock.rpc` is the `ClientConnectionRpc` face. Pass it as `{ transport: { rpc: mock.rpc } }` to the Connection installer, or let `TestClient` bind it to its instance, so every Remote call reaches `dispatch` and every stream reaches `open` with no envelopes in between. Payloads carry `{ args }` as the whole-client proxies send them (an array) or as the Gateway's own endpoints send them (one object, delivered as one positional arg); a call whose signal aborts rejects with the abort reason. `RemoteMock.create()` registers one stream, `$events`, that answers the Gateway client's opening with `{ type: 'ready', clientId, host: { home } }` (host from `RemoteMockOptions.host`, default `/home/mock`) and stays open, which is what lets the assembled client reach `connected`; a spec overrides or fails it like any other stream.
+
+### Observe and assert
+
+`mock.log.calls(endpoint?)` lists unary calls through `dispatch` or `rpc.call` (`args`, `seq`, a live `state` of `pending` / `answered` / `failed`, and the answer or thrown error as `result`), `streams(endpoint?)` lists scripted opens with their live `state` and `pushed` count, `requests(endpoint?)` lists the first positional arg of calls and opens in order (without an endpoint, excluding the Gateway's own `$`-prefixed endpoints), and `unmatched()` lists requests that found no rule. Native `.mock.calls` additionally includes direct proxy calls; carrier stream mocks receive their final cancellation signal. `assertNoUnmatched()` reports misses at teardown. `modeOf(endpoint)` reports explicit registrations; `endpoints()` also includes accessed proxy methods so assembly can provide their namespaces.
+
+### What can go wrong
+
+- **A request has no rule** — `dispatch` rejects and `open` throws `remote-mock: no rule for <endpoint>; registered: …`, and the log records the miss; register the endpoint.
+- **A payload is not `{ args: unknown[] | object }`** — `rpc.call` rejects and `rpc.open` throws a `TypeError`; the whole-client proxies send the array form and the Gateway's own endpoints the object form, so a hand-written call is at fault.
+- **A second concurrent read on one stream** — the read rejects; the Gateway reads streams sequentially, so this names a test-side misuse.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+### Design
+
+`dispatch` and `open` take the endpoint and positional args; `rpc` exposes the same core through Connection's decoded carrier interface. Each mock owns its native functions and queued overrides; shared tables supply defaults without copying handlers or answer objects. Each scripted stream owns its queue, its single pending read, and its log entry; the first of `end`, `fail`, or consumer cancellation settles it.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Public face re-exports |
+| [`src/remote-mock.ts`](src/remote-mock.ts) | `RemoteMock`: default responses, native mocks, Connection dispatch, controlled streams and missing-response checks; `ok` |
+| [`src/remote-proxy.ts`](src/remote-proxy.ts) | Namespace/method lookup and generated-map mock types |
+| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` scripts and `MockStream` (handle + `AsyncIterable`) |
+| [`src/log.ts`](src/log.ts) | Log store with the shared `seq` counter |
+| — | No runtime invariant companion is published; this test-support library owns no production event stream or mutable process state, and its behavior is exercised by its package tests. |
+
+</details>
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package is browser-side test infrastructure; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **In-process carrier only** — `rpc` serves a Connection instance in the same realm; no HTTP or WebSocket carrier for browser-lane specs is provided.
+- **Values cross by reference** — answers and stream items reach the client unserialized, so a non-JSON value that the real wire would reject passes through unchanged.
+- **Values are not checked** — a unary answer must be the result the caller reads (`{ ok, value }` or `{ ok: false, error }`); the mock passes it through unchanged and does not check those fields.
+- **No payload matching** — rules match on endpoint only; discriminate on business arguments inside a handler.
+- **Native stream overrides own their iterable** — an override returning its own iterable bypasses scripted-stream logs, `requests`, `opened`, `drained`, and `push` / `end` / `fail`; the caller also owns cancellation. Native call assertions still work. Use a registered stream script when a scenario needs those controls.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,146 @@
+---
+description: "Typert Remote 流量的端点具名 mock：一元应答与流脚本的表、活流控制、日志与 Connection 载体面，供测试作者在没有 Host 的情况下启动真实浏览器客户端。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-remote-mock
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-remote-mock` 让测试通过 `mock.remote.<namespace>.<method>`，使用原生 Vitest mock 方法配置 Host 响应。同一组函数应答直接调用与真实 Connection 流量；可复用的表提供默认响应，显式声明的流支持测试驱动的推帧与取消。缺少响应时调用失败，`assertNoUnmatched()` 会在收尾时再次报告。本包无需业务 Host 即可在 Node 或浏览器页面中运行，不导入 DOM、React 或 Node 模块，只从 `devDependencies` 消费。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+### 何时使用
+
+当测试要启动与 `ctx.remote` 对话的真实客户端插件、并想按端点名脚本化 Host 侧时使用它：整体客户端测试把 `mock.rpc` 绑定到各自的 Connection 实例，单元测试也可以直接调用 `mock.remote`、`dispatch` 或 `open`。端点是 Gateway 的 wire 名（`session/page`、`settings/describe`）；`args` 是调用方的位置参数列表，末尾的 `AbortSignal` 已剥掉；值就是测试登记的东西，原样应答。唯一的声明是端点是一元（`unary`）还是流（`stream`）。
+
+<a id="remote-proxy"></a>
+### 使用 Remote Proxy
+
+`mock.remote` 无需方法清单或领域专属 Helper 即可提供每个命名空间和方法。每个访问过的端点使用缓存的原生 Vitest mock；`@vitest/spy.fn` 就是 `vi.fn` 背后的实现，也能在没有 Vitest runner 的浏览器页面中运行。同一个 mock 应答直接调用与 Connection 流量，因此返回值覆盖和调用断言观察的是客户端实际调用的函数：
+
+```text
+const mock = RemoteMock.create().load(remoteDefaultResponses)
+mock.remote.settings.describe.mockResolvedValue(ok({
+  writable: true, hasDocument: false, namespaces: [],
+}))
+mock.remote.settings.mutate.mockResolvedValueOnce(ok(updatedNamespace))
+// After the client writes:
+expect(mock.remote.settings.mutate).toHaveBeenCalledWith('locale', operations, revision)
+```
+
+使用 `mockResolvedValue` 设置持续响应，使用 `mockResolvedValueOnce` 或 `mockReturnValueOnce` 排队设置响应，使用 `mockImplementation` 按参数决定行为。原生队列按登记顺序消费响应，耗尽后由 mock 的当前实现应答；初始实现读取已登记的默认响应。`mockClear()` 保留响应与队列；`mockReset()` 清除覆盖并恢复初始实现，由它读取最新默认响应。若未配置默认响应，排队响应耗尽后仍会失败，包括可能同步抛错的直接调用。
+
+只有显式 `stream()` 或响应表中的流声明才选择流方法；其余均使用一元 mock。访问方法不会凭空构造成功的业务结果。保存方法引用前先声明流模式：每个端点/模式拥有各自的 mock。命名空间和方法的 `then` 探测及 symbol 读取均无副作用。
+
+`MockedRemote` 使用 Vitest 的深层 mock 类型转换，覆盖完整生成的 `TypertRemoteNamespaceMap`。非空映射保留命名空间与方法名、参数、返回值和原生 spy 类型。映射为空时只有这个测试 Proxy 变成 `any`，允许任意命名空间和方法；它不增补或弱化生产 Remote 声明。不需要复制方法签名、抑制可选生成模块错误或开启编译器级全局 Flag。交付 Remote/mock 改动前运行 `pnpm run typecheck`，生成并检查真实 Client 类型；声明缺失、陈旧或不完整时先重新构建。无构建测试通过或推断为 `any` 都不是严格类型证据。
+
+### 登记默认响应
+
+`load(table)` 安装可复用的 `unary` 值或 handler、`stream` 脚本以及无脚本的 `streams` 声明。`unary(endpoint, value)` 与 `unary(endpoint, fn)` 登记单个默认响应；handler 接收调用方的位置参数，并使用现有请求类型。每个端点仅保存最新默认响应，包括显式 `undefined`；更新默认响应不会清除原生覆盖。`ok(value)` 构造 `{ ok: true, value }`；失败使用 `{ ok: false, error: { code, message, details } }`。有状态 handler、promise 与原生队列均由各测试独立持有：
+
+```text
+const initial = { writable: true, hasDocument: false, namespaces: [] }
+const mock = RemoteMock.create().load({
+  unary: { 'settings/describe': ok(initial) },
+})
+mock.remote.settings.describe.mockResolvedValueOnce(ok({ ...initial, hasDocument: true }))
+```
+
+### 驾驭流
+
+流脚本是一个接收打开时的 `args` 与 `StreamHandle`（`push`、`end`、`fail(error)`、`signal`）的函数；脚本返回后流保持打开，直到句柄结束或失败。`frames(items)` 构造吐完即结束的脚本，`openStream(initial)` 构造吐完后保持打开的脚本。`mock.streams` 控制客户端当前打开着的流，可按打开时的参数过滤；`opened(endpoint, count)` 在该端点被打开达到该次数时 resolve，`drained(endpoint)` 在每条匹配流的消费方都拉完了迄今推入的全部内容时 resolve——打开的流要其消费方再次等待，已定局的流要队列已空（拉完指从队列取走；只有在读循环内处理项的消费方才等于处理完）：
+
+```text
+mock.stream('session/follow', openStream([snapshotFrame]))
+await mock.streams.opened('session/follow', 1)
+mock.streams.push('session/follow', eventFrame, ([request]) => (request as { sessionId: string }).sessionId === SID)
+mock.streams.fail('session/follow', new Error('gone'))
+await mock.streams.drained('session/follow')
+```
+
+失败的流让消费方的下一次读取以给定的 `Error` reject。消费方取消（打开时的 signal 或 iterator 提前 `return()`）会中止 `StreamHandle.signal`、结束迭代而不抛错，并把该流记为 `cancelled`。
+
+### 接上客户端
+
+`mock.rpc` 是 `ClientConnectionRpc` 面。把它作为 `{ transport: { rpc: mock.rpc } }` 传给 Connection 安装函数，或让 `TestClient` 将其绑定到自身实例，每次 Remote 调用就会直达 `dispatch`、每条流直达 `open`，中间没有信封。payload 携带 `{ args }`——整机代理发数组、Gateway 自身端点发一个对象（到达时是一个位置参数）；signal 中止的调用以中止原因 reject。`RemoteMock.create()` 登记一条流 `$events`，用 `{ type: 'ready', clientId, host: { home } }`（host 来自 `RemoteMockOptions.host`，默认 `/home/mock`）应答 Gateway 客户端的打开并保持打开——这正是整机能达到 `connected` 的原因；测试可以像任何流一样覆盖或让它失败。
+
+### 观察与断言
+
+`mock.log.calls(endpoint?)` 列出经 `dispatch` 或 `rpc.call` 的一元调用（`args`、`seq`、实时 `state` 为 `pending` / `answered` / `failed`，以及作为 `result` 的应答值或抛出的错误），`streams(endpoint?)` 列出脚本流的打开记录及其实时 `state` 与 `pushed` 计数，`requests(endpoint?)` 按顺序列出调用与打开的首个位置参数（不带端点时去掉 Gateway 自己带 `$` 前缀的端点），`unmatched()` 列出没找到规则的请求。原生 `.mock.calls` 还包含直接 Proxy 调用；载体的流 mock 会收到末尾的取消信号。`assertNoUnmatched()` 在收尾时报告漏配。`modeOf(endpoint)` 报告显式登记；`endpoints()` 还包含访问过的 Proxy 方法，使装配能够提供它们的命名空间。
+
+### 可能出什么问题
+
+- **请求没有规则**——`dispatch` reject、`open` 抛出 `remote-mock: no rule for <endpoint>; registered: …`，日志记下这次漏配；请登记该端点。
+- **payload 不是 `{ args: unknown[] | object }`**——`rpc.call` reject、`rpc.open` 抛 `TypeError`；整机代理发数组形式、Gateway 自身端点发对象形式，所以问题出在手写调用。
+- **同一条流上有第二个并发读取**——该读取 reject；Gateway 顺序读取流，因此这指向测试侧误用。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+### 设计
+
+`dispatch` 与 `open` 接收端点与位置参数；`rpc` 通过 Connection 的已解码载体接口暴露同一个核心。每个 mock 独立持有原生函数及排队覆盖；共享表提供默认响应，不复制 handler 或应答对象。每条脚本流拥有自己的队列、唯一挂起读取和日志条目；`end`、`fail`、消费方取消三者中最先发生者定局。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 公开面转出 |
+| [`src/remote-mock.ts`](src/remote-mock.ts) | `RemoteMock`：默认响应、原生 mock、Connection 分发、受控流与缺失响应检查；`ok` |
+| [`src/remote-proxy.ts`](src/remote-proxy.ts) | 命名空间／方法查找与生成映射的 mock 类型 |
+| [`src/streams.ts`](src/streams.ts) | `frames` / `openStream` 脚本与 `MockStream`（句柄 + `AsyncIterable`） |
+| [`src/log.ts`](src/log.ts) | 带共享 `seq` 计数器的日志 |
+| — | 不发布运行时不变量伴生件；本测试支持库不拥有任何生产事件流或可变进程状态，其行为由本包测试覆盖。 |
+
+</details>
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无；本包是浏览器侧测试基础设施，无一物到达模型请求。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **仅进程内载体**——`rpc` 服务同一 realm 中的 Connection 实例；不提供给浏览器车道测试用的 HTTP 或 WebSocket 载体。
+- **值按引用传递**——应答与流项都未经序列化就到达客户端，真实线路会拒绝的非 JSON 值在这里原样通过。
+- **不校验值**——一元应答必须是调用方读取的结果（`{ ok, value }` 或 `{ ok: false, error }`）；mock 原样传递它，不检查这些字段。
+- **不做 payload 匹配**——规则只按端点匹配；在 handler 内按业务参数判别。
+- **原生流覆盖自行管理 iterable**——覆盖返回自有 iterable 时，不参与脚本流日志、`requests`、`opened`、`drained` 以及 `push` / `end` / `fail`；调用方也负责取消。原生调用断言仍然有效。需要这些控制能力的场景应使用已登记的流脚本。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,557 @@
+import { fn } from "@vitest/spy";
+//#region lib/types/log.js
+/** What a `RemoteMock` saw: answered calls, opened streams, and requests without a rule. */
+/** The mock's log store. */
+var MockLogStore = class {
+	callEntries = [];
+	streamEntries = [];
+	missEntries = [];
+	seq = 0;
+	calls(endpoint) {
+		return this.callEntries.filter((entry) => endpoint === void 0 || entry.endpoint === endpoint);
+	}
+	streams(endpoint) {
+		return this.streamEntries.filter((entry) => endpoint === void 0 || entry.endpoint === endpoint);
+	}
+	requests(endpoint) {
+		return [...this.calls(endpoint), ...this.streams(endpoint)].filter((entry) => endpoint !== void 0 || !entry.endpoint.startsWith("$")).sort((a, b) => a.seq - b.seq).map((entry) => entry.args[0]);
+	}
+	unmatched() {
+		return [...this.missEntries];
+	}
+	/**
+	* Record one call whose rule was selected.
+	* @param endpoint - endpoint.
+	* @param args - positional args.
+	* @returns the mutable entry the dispatcher settles.
+	*/
+	call(endpoint, args) {
+		const record = {
+			endpoint,
+			args,
+			state: "pending",
+			result: void 0,
+			seq: ++this.seq
+		};
+		this.callEntries.push(record);
+		return record;
+	}
+	/**
+	* Record one stream open.
+	* @param endpoint - endpoint.
+	* @param args - positional args.
+	* @returns the mutable entry the stream updates.
+	*/
+	stream(endpoint, args) {
+		const record = {
+			endpoint,
+			args,
+			state: "open",
+			pushed: 0,
+			seq: ++this.seq
+		};
+		this.streamEntries.push(record);
+		return record;
+	}
+	/**
+	* Record one request without a rule.
+	* @param endpoint - endpoint.
+	* @param mode - how it was requested.
+	*/
+	miss(endpoint, mode) {
+		this.missEntries.push({
+			endpoint,
+			mode
+		});
+	}
+};
+//#endregion
+//#region lib/types/streams.js
+/** Stream scripts and the pushable, abort-aware stream a script drives. */
+/**
+* Script yielding `items`, then ending.
+* @param items - items in order.
+* @returns the script.
+*/
+function frames(items) {
+	return (_args, stream) => {
+		for (const item of items) stream.push(item);
+		stream.end();
+	};
+}
+/**
+* Script yielding `initial`, then staying open for `streams.push`.
+* @param initial - items yielded on open.
+* @returns the script.
+*/
+function openStream(initial = []) {
+	return (_args, stream) => {
+		for (const item of initial) stream.push(item);
+	};
+}
+/** One open stream: a queue the script pushes into and a single consumer reads from; the log entry tracks its state. */
+var MockStream = class {
+	record;
+	sourceSignal;
+	queue = [];
+	settled;
+	waiting;
+	drainWaiters = [];
+	cancellation = new AbortController();
+	signal = this.cancellation.signal;
+	/** Consumer cancellation listener; attached while the stream is open, removed when it settles or cancels. */
+	onAbort = () => {
+		this.cancel(this.sourceSignal.reason);
+	};
+	/** Items pushed but not yet pulled by the consumer. */
+	get queued() {
+		return this.queue.length;
+	}
+	/**
+	* @param record - log entry this stream updates.
+	* @param sourceSignal - cancellation from the caller that opened the stream.
+	*/
+	constructor(record, sourceSignal) {
+		this.record = record;
+		this.sourceSignal = sourceSignal;
+		if (sourceSignal.aborted) this.cancel(sourceSignal.reason);
+		else sourceSignal.addEventListener("abort", this.onAbort, { once: true });
+	}
+	push(item) {
+		if (this.record.state !== "open") return;
+		this.record.pushed += 1;
+		if (this.waiting !== void 0) {
+			const { resolve } = this.waiting;
+			this.waiting = void 0;
+			resolve({
+				value: item,
+				done: false
+			});
+			return;
+		}
+		this.queue.push(item);
+	}
+	end() {
+		this.settle({ kind: "end" }, "ended");
+	}
+	fail(error) {
+		this.settle({
+			kind: "fail",
+			error
+		}, "failed");
+	}
+	/**
+	* Start `script` on this stream.
+	* @param script - the registered script.
+	* @param args - open args.
+	*/
+	run(script, args) {
+		let outcome;
+		try {
+			outcome = script(args, this);
+		} catch (error) {
+			this.fail(toError(error));
+			return;
+		}
+		if (outcome instanceof Promise) outcome.catch((error) => {
+			this.fail(toError(error));
+		});
+	}
+	/**
+	* Resolve once the consumer has pulled every queued item and waits for the next one, or the stream is no longer
+	* open and holds nothing the consumer could still pull (a consumer that returns discards what it left).
+	* @returns settles when drained.
+	*/
+	drained() {
+		if (this.isDrained()) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.drainWaiters.push(resolve);
+		});
+	}
+	[Symbol.asyncIterator]() {
+		return {
+			next: () => this.next(),
+			return: () => {
+				this.cancel();
+				return Promise.resolve({
+					value: void 0,
+					done: true
+				});
+			}
+		};
+	}
+	next() {
+		const result = this.pull();
+		this.wakeDrained();
+		return result;
+	}
+	pull() {
+		if (this.queue.length > 0) return Promise.resolve({
+			value: this.queue.shift(),
+			done: false
+		});
+		if (this.settled !== void 0) return this.finish(this.settled);
+		if (this.record.state === "cancelled") return Promise.resolve({
+			value: void 0,
+			done: true
+		});
+		if (this.waiting !== void 0) return Promise.reject(/* @__PURE__ */ new Error(`remote-mock: ${this.record.endpoint} stream has one consumer`));
+		return new Promise((resolve, reject) => {
+			this.waiting = {
+				resolve,
+				reject
+			};
+		});
+	}
+	finish(settled) {
+		return settled.kind === "end" ? Promise.resolve({
+			value: void 0,
+			done: true
+		}) : Promise.reject(settled.error);
+	}
+	settle(settled, state) {
+		if (this.record.state !== "open") return;
+		this.record.state = state;
+		this.settled = settled;
+		this.sourceSignal.removeEventListener("abort", this.onAbort);
+		this.wakeDrained();
+		const waiting = this.waiting;
+		if (waiting === void 0) return;
+		this.waiting = void 0;
+		this.finish(settled).then(waiting.resolve, waiting.reject);
+	}
+	cancel(reason) {
+		if (this.record.state === "open") {
+			this.record.state = "cancelled";
+			this.sourceSignal.removeEventListener("abort", this.onAbort);
+			const waiting = this.waiting;
+			this.waiting = void 0;
+			this.queue.length = 0;
+			this.cancellation.abort(reason);
+			waiting?.resolve({
+				value: void 0,
+				done: true
+			});
+		}
+		this.queue.length = 0;
+		this.wakeDrained();
+	}
+	isDrained() {
+		return this.queue.length === 0 && (this.waiting !== void 0 || this.record.state !== "open");
+	}
+	wakeDrained() {
+		if (!this.isDrained()) return;
+		const waiters = this.drainWaiters;
+		this.drainWaiters = [];
+		for (const resolve of waiters) resolve();
+	}
+};
+/**
+* The `Error` a thrown value stands for: itself, or a new Error carrying its string form.
+* @param reason - thrown value.
+* @returns the error.
+*/
+function toError(reason) {
+	return reason instanceof Error ? reason : new Error(String(reason));
+}
+//#endregion
+//#region lib/types/remote-proxy.js
+/**
+* Cache accessed namespaces and expose the current native mock for each method.
+* @param method - selects a stable endpoint mock for its configured invocation mode.
+* @returns enumerable accessed namespaces and methods; symbols and thenable probes remain inert.
+*/
+function createRemoteProxy(method) {
+	return new Proxy(Object.create(null), { get(namespaces, namespace) {
+		if (typeof namespace !== "string" || namespace === "then") return void 0;
+		return namespaces[namespace] ??= new Proxy(Object.create(null), { get(methods, name) {
+			if (typeof name !== "string" || name === "then") return void 0;
+			return methods[name] = method(`${namespace}/${name}`);
+		} });
+	} });
+}
+//#endregion
+//#region lib/types/remote-mock.js
+/** `RemoteMock`: an endpoint table (unary answers or stream scripts), live stream control, a log, and the Connection carrier face. */
+const EVENTS_ENDPOINT = "$events";
+/**
+* The success envelope the Client's Remote callers read: `{ ok: true, value }`.
+* @param value - success value.
+* @returns the envelope.
+*/
+function ok(value) {
+	return {
+		ok: true,
+		value
+	};
+}
+/** A missing default answer is an unmatched request, not a selected rule that failed. */
+var MissingUnaryRule = class extends Error {};
+/**
+* Endpoint-named Remote mock. `dispatch` / `open` are the core; `rpc` is the
+* same core as the decoded carrier accepted by the Connection installer.
+*/
+var RemoteMock = class RemoteMock {
+	/**
+	* Create a mock whose `$events` stream answers the Gateway client's opening
+	* with one ready frame and then stays open, so the assembled client connects.
+	* @param options - host facts for the ready frame.
+	* @returns the mock.
+	*/
+	static create(options = {}) {
+		const mock = new RemoteMock();
+		const host = options.host ?? { home: "/home/mock" };
+		let generation = 0;
+		return mock.stream(EVENTS_ENDPOINT, (_args, stream) => {
+			generation += 1;
+			stream.push({
+				type: "ready",
+				clientId: `mock-client-${String(generation)}`,
+				host
+			});
+		});
+	}
+	unaryDefaults = /* @__PURE__ */ new Map();
+	scripts = /* @__PURE__ */ new Map();
+	live = [];
+	openWaiters = [];
+	logStore = new MockLogStore();
+	unaryMocks = /* @__PURE__ */ new Map();
+	streamMocks = /* @__PURE__ */ new Map();
+	proxy = createRemoteProxy((endpoint) => this.modeOf(endpoint) === "stream" ? this.streamMock(endpoint) : this.unaryMock(endpoint));
+	/**
+	* Native mock functions for every namespace: configure answers and inspect calls without declaring method names.
+	* Explicit stream registrations select stream mocks; all other methods use unary mocks.
+	* Native overrides belong to this instance; `mockReset()` restores the implementation reading current defaults.
+	* Generated declarations provide exact signatures; absent declarations weaken only this test-owned proxy.
+	*/
+	remote = this.proxy;
+	/** Everything observed so far. */
+	log = this.logStore;
+	/** Control over streams opened by registered scripts. */
+	streams = {
+		push: (endpoint, item, where) => this.forEachOpen(endpoint, where, (stream) => {
+			stream.push(item);
+		}),
+		end: (endpoint, where) => this.forEachOpen(endpoint, where, (stream) => {
+			stream.end();
+		}),
+		fail: (endpoint, error, where) => this.forEachOpen(endpoint, where, (stream) => {
+			stream.fail(error);
+		}),
+		opened: (endpoint, count) => {
+			if (this.logStore.streams(endpoint).length >= count) return Promise.resolve();
+			return new Promise((resolve) => {
+				this.openWaiters.push({
+					endpoint,
+					count,
+					resolve
+				});
+			});
+		},
+		drained: (endpoint, where) => Promise.all(this.matching(endpoint, where).map((stream) => stream.drained())).then(() => void 0)
+	};
+	/**
+	* The Connection carrier face: `call` dispatches, `open` opens; payloads carry
+	* `{ args }` as the whole-client proxies (an array) or the Gateway's own
+	* endpoints (one object) send them, and a call aborted by its signal rejects.
+	*/
+	rpc = {
+		call: async (_channel, endpoint, payload, signal) => {
+			const pending = this.dispatch(endpoint, argsOf(endpoint, payload));
+			return await (signal === void 0 ? pending : settleOrAbort(pending, signal));
+		},
+		open: (_channel, endpoint, payload, signal) => this.open(endpoint, argsOf(endpoint, payload), signal)
+	};
+	constructor() {}
+	unary(endpoint, rule) {
+		this.unaryDefaults.set(endpoint, rule);
+		return this;
+	}
+	/**
+	* Declare `endpoint` as a stream and replace its default script when supplied. A declaration without a script
+	* preserves any existing script; an endpoint declared without one fails an open as a stream miss.
+	* @param endpoint - `<namespace>/<method>`.
+	* @param script - script (`frames` / `openStream` build the common ones).
+	* @returns this.
+	*/
+	stream(endpoint, script) {
+		if (script !== void 0 || !this.scripts.has(endpoint)) this.scripts.set(endpoint, script);
+		return this;
+	}
+	/**
+	* Register endpoint defaults without changing native mock overrides.
+	* @param table - unary answers and stream scripts.
+	* @returns this.
+	*/
+	load(table) {
+		for (const [endpoint, rule] of Object.entries(table.unary ?? {})) this.unary(endpoint, rule);
+		for (const endpoint of table.streams ?? []) this.stream(endpoint);
+		for (const [endpoint, script] of Object.entries(table.stream ?? {})) this.stream(endpoint, script);
+		return this;
+	}
+	/**
+	* Whether `endpoint` is declared a stream (with or without a script) or has a unary rule — the one declaration
+	* the whole-client proxies need; an endpoint neither declared nor ruled is dispatched as a unary call.
+	* @param endpoint - endpoint.
+	* @returns the mode, or undefined when nothing is registered.
+	*/
+	modeOf(endpoint) {
+		if (this.scripts.has(endpoint)) return "stream";
+		if (this.unaryDefaults.has(endpoint)) return "unary";
+	}
+	/**
+	* Registered endpoints and accessed proxy methods, sorted.
+	* @returns endpoint names.
+	*/
+	endpoints() {
+		const names = new Set(this.scripts.keys());
+		for (const endpoint of this.unaryDefaults.keys()) names.add(endpoint);
+		for (const [namespace, methods] of Object.entries(this.proxy)) for (const method of Object.keys(methods)) names.add(`${namespace}/${method}`);
+		return [...names].sort();
+	}
+	/**
+	* Answer one unary call with the registered rule's value, verbatim. The call
+	* is logged as soon as its rule is selected and settles with the rule: a
+	* rule that throws or rejects fails the call with that error.
+	* @param endpoint - endpoint.
+	* @param args - positional args.
+	* @returns the answer.
+	* @throws {Error} when no rule is registered (logged as unmatched).
+	*/
+	async dispatch(endpoint, args) {
+		let answer;
+		try {
+			answer = this.unaryMock(endpoint)(...args);
+		} catch (error) {
+			if (error instanceof MissingUnaryRule) throw error;
+			answer = Promise.reject(toError(error));
+		}
+		const record = this.logStore.call(endpoint, args);
+		try {
+			record.result = await answer;
+		} catch (error) {
+			record.state = "failed";
+			record.result = error;
+			throw error;
+		}
+		record.state = "answered";
+		return record.result;
+	}
+	unaryMock(endpoint) {
+		let mock = this.unaryMocks.get(endpoint);
+		if (mock === void 0) {
+			mock = fn((...args) => Promise.resolve(this.unaryAnswer(endpoint, args)));
+			this.unaryMocks.set(endpoint, mock);
+		}
+		return mock;
+	}
+	unaryAnswer(endpoint, args) {
+		if (!this.unaryDefaults.has(endpoint)) {
+			this.logStore.miss(endpoint, "unary");
+			throw new MissingUnaryRule(this.noRuleMessage(endpoint));
+		}
+		const rule = this.unaryDefaults.get(endpoint);
+		return isRuleFn(rule) ? answerOf(rule, args) : rule;
+	}
+	/**
+	* Open through the endpoint's native mock; its default runs the registered script as a controlled stream.
+	* A native override returns its own iterable: the caller owns consumption and cancellation, outside `OpenStreams`.
+	* @param endpoint - endpoint.
+	* @param args - positional args.
+	* @param signal - consumer cancellation.
+	* @returns the controlled script stream or the native override's caller-owned iterable.
+	* @throws {Error} when the default runs without a registered script (logged as unmatched).
+	*/
+	open(endpoint, args, signal) {
+		return this.streamMock(endpoint)(...args, signal);
+	}
+	streamMock(endpoint) {
+		let mock = this.streamMocks.get(endpoint);
+		if (mock === void 0) {
+			mock = fn((...values) => {
+				const args = [...values];
+				const signal = args.at(-1) instanceof AbortSignal ? args.pop() : new AbortController().signal;
+				return this.openScript(endpoint, args, signal);
+			});
+			this.streamMocks.set(endpoint, mock);
+		}
+		return mock;
+	}
+	openScript(endpoint, args, signal) {
+		const script = this.scripts.get(endpoint);
+		if (script === void 0) {
+			this.logStore.miss(endpoint, "stream");
+			throw new Error(this.noRuleMessage(endpoint));
+		}
+		const stream = new MockStream(this.logStore.stream(endpoint, args), signal);
+		this.live.push(stream);
+		this.wakeOpened(endpoint);
+		stream.run(script, args);
+		return stream;
+	}
+	/** Throw when any request found no rule, naming the endpoints and the registered ones. */
+	assertNoUnmatched() {
+		const unmatched = this.logStore.unmatched();
+		if (unmatched.length === 0) return;
+		const lines = unmatched.map((entry) => `  ${entry.endpoint} (${entry.mode})`);
+		throw new Error(`remote-mock: ${String(unmatched.length)} unmatched request(s):\n${lines.join("\n")}\nregistered: ${this.endpoints().join(", ")}`);
+	}
+	noRuleMessage(endpoint) {
+		return `remote-mock: no rule for ${endpoint}; registered: ${this.endpoints().join(", ")}`;
+	}
+	/** Streams on `endpoint` still open or still holding items their consumer has not pulled; the rest are forgotten. */
+	matching(endpoint, where) {
+		this.live = this.live.filter((stream) => stream.record.state === "open" || stream.queued > 0);
+		return this.live.filter((stream) => stream.record.endpoint === endpoint && (where === void 0 || where(stream.record.args)));
+	}
+	forEachOpen(endpoint, where, action) {
+		const targets = this.matching(endpoint, where).filter((stream) => stream.record.state === "open");
+		for (const stream of targets) action(stream);
+		return targets.length;
+	}
+	wakeOpened(endpoint) {
+		const opened = this.logStore.streams(endpoint).length;
+		const ready = this.openWaiters.filter((waiter) => waiter.endpoint === endpoint && opened >= waiter.count);
+		this.openWaiters = this.openWaiters.filter((waiter) => !ready.includes(waiter));
+		for (const waiter of ready) waiter.resolve();
+	}
+};
+function isRuleFn(rule) {
+	return typeof rule === "function";
+}
+/** A rule's synchronous throw becomes a rejection so the call settles through one path. */
+function answerOf(rule, args) {
+	try {
+		return rule(...args);
+	} catch (error) {
+		return Promise.reject(toError(error));
+	}
+}
+/** Positional args from a carrier payload: the array the whole-client proxies send, or the one object the Gateway's own endpoints send. */
+function argsOf(endpoint, payload) {
+	if (typeof payload === "object" && payload !== null && "args" in payload) {
+		const { args } = payload;
+		if (Array.isArray(args)) return args;
+		if (typeof args === "object" && args !== null) return [args];
+	}
+	throw new TypeError(`remote-mock: payload of ${endpoint} must be { args: unknown[] | object }`);
+}
+/**
+* Settle with the call, or reject with the abort reason first; the call itself
+* always keeps a handler so its own outcome is never an unhandled rejection.
+*/
+function settleOrAbort(pending, signal) {
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			reject(signal.reason instanceof Error ? signal.reason : new Error("remote-mock: call aborted", { cause: signal.reason }));
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		pending.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", abort);
+		});
+		if (signal.aborted) abort();
+	});
+}
+//#endregion
+export { RemoteMock, frames, ok, openStream };

package/lib/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Endpoint-named mock for Typert Remote traffic: a table of unary answers and
+ * stream scripts keyed by `<namespace>/<method>`, scripted-stream control, a
+ * carrier log, and the Connection carrier face the `connection` plugin
+ * accepts through explicit installation or a page transport. Values are whatever the test
+ * registers; the only declaration is whether an endpoint is unary or a
+ * stream. Browser-safe: no DOM, React, or Node imports, no runtime import
+ * from another harness package.
+ * @module @deepseek-ai/dsh-remote-mock
+ */
+export { RemoteMock, ok } from './remote-mock.ts';
+export type { OpenStreams, RemoteMockOptions, RemoteTable, StreamFilter, UnaryRuleFn } from './remote-mock.ts';
+export { frames, openStream } from './streams.ts';
+export type { StreamHandle, StreamScript } from './streams.ts';
+export type { LoggedCall, LoggedMiss, LoggedStream, MockLog } from './log.ts';
+export type { MockedRemote } from './remote-proxy.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/log.d.ts

@@ -0,0 +1,96 @@
+/** What a `RemoteMock` saw: answered calls, opened streams, and requests without a rule. */
+/** One unary call, logged when its rule is selected and settled when the rule does. */
+export interface LoggedCall {
+    readonly endpoint: string;
+    /** Positional args as the caller passed them. */
+    readonly args: readonly unknown[];
+    /** `pending` until the rule settles, then `answered` or `failed`. */
+    readonly state: 'pending' | 'answered' | 'failed';
+    /** The answer once `answered`, the thrown error once `failed`. */
+    readonly result: unknown;
+    /** Global order across calls and stream opens. */
+    readonly seq: number;
+}
+/** One stream open and its current state. */
+export interface LoggedStream {
+    readonly endpoint: string;
+    /** Positional args the stream was opened with. */
+    readonly args: readonly unknown[];
+    readonly state: 'open' | 'ended' | 'failed' | 'cancelled';
+    /** Items delivered to the consumer so far. */
+    readonly pushed: number;
+    /** Global order across calls and stream opens. */
+    readonly seq: number;
+}
+/** One request that found no rule. */
+export interface LoggedMiss {
+    readonly endpoint: string;
+    readonly mode: 'unary' | 'stream';
+}
+/** Read side of the log. */
+export interface MockLog {
+    /**
+     * Unary calls, oldest first, with their live state.
+     * @param endpoint - restrict to one endpoint.
+     * @returns matching entries.
+     */
+    calls(endpoint?: string): readonly LoggedCall[];
+    /**
+     * Stream opens, oldest first, with their live state.
+     * @param endpoint - restrict to one endpoint.
+     * @returns matching entries.
+     */
+    streams(endpoint?: string): readonly LoggedStream[];
+    /**
+     * The first positional arg of every unary call and stream open, oldest first: the request object of the Gateway's
+     * one-parameter endpoints. Without `endpoint`, every endpoint the client asked the Host for, except the Gateway's
+     * own `$`-prefixed ones (`$events`).
+     * @param endpoint - restrict to one endpoint.
+     * @returns the requests.
+     */
+    requests(endpoint?: string): readonly unknown[];
+    /** Requests that found no rule, oldest first. */
+    unmatched(): readonly LoggedMiss[];
+}
+/** Mutable call entry the dispatcher settles. */
+export interface CallRecord extends LoggedCall {
+    state: LoggedCall['state'];
+    result: unknown;
+}
+/** Mutable stream entry shared with the live stream. */
+export interface StreamRecord extends LoggedStream {
+    state: LoggedStream['state'];
+    pushed: number;
+}
+/** The mock's log store. */
+export declare class MockLogStore implements MockLog {
+    private readonly callEntries;
+    private readonly streamEntries;
+    private readonly missEntries;
+    private seq;
+    calls(endpoint?: string): readonly LoggedCall[];
+    streams(endpoint?: string): readonly LoggedStream[];
+    requests(endpoint?: string): readonly unknown[];
+    unmatched(): readonly LoggedMiss[];
+    /**
+     * Record one call whose rule was selected.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the mutable entry the dispatcher settles.
+     */
+    call(endpoint: string, args: readonly unknown[]): CallRecord;
+    /**
+     * Record one stream open.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the mutable entry the stream updates.
+     */
+    stream(endpoint: string, args: readonly unknown[]): StreamRecord;
+    /**
+     * Record one request without a rule.
+     * @param endpoint - endpoint.
+     * @param mode - how it was requested.
+     */
+    miss(endpoint: string, mode: 'unary' | 'stream'): void;
+}
+//# sourceMappingURL=log.d.ts.map

package/lib/types/remote-mock.d.ts

@@ -0,0 +1,184 @@
+/** `RemoteMock`: an endpoint table (unary answers or stream scripts), live stream control, a log, and the Connection carrier face. */
+import type { ClientConnectionRpc } from '@deepseek-ai/dsh-client-connection/client';
+import { type MockLog } from './log.ts';
+import { type StreamScript } from './streams.ts';
+import { type MockedRemote } from './remote-proxy.ts';
+/** A unary handler receives the caller's positional arguments, without its trailing `AbortSignal`. */
+export type UnaryRuleFn<Args extends readonly unknown[] = readonly unknown[], Result = unknown> = (...args: Args) => Result;
+/** Endpoint defaults: unary values or positional handlers, stream scripts, and stream declarations. */
+export interface RemoteTable {
+    readonly unary?: Readonly<Record<string, unknown>>;
+    readonly stream?: Readonly<Record<string, StreamScript>>;
+    /** Endpoints declared as streams without a script, so an open finds a stream miss rather than a unary one. */
+    readonly streams?: readonly string[];
+}
+/** Construction options. */
+export interface RemoteMockOptions {
+    /** Host facts the built-in `$events` ready frame carries; default `{ home: '/home/mock' }`. */
+    readonly host?: {
+        readonly home: string;
+    };
+}
+/** Filter over the args a stream was opened with. */
+export type StreamFilter = (args: readonly unknown[]) => boolean;
+/** Control and synchronization for streams opened by registered scripts; native overrides are excluded. */
+export interface OpenStreams {
+    /**
+     * Push one item into every open stream on `endpoint`, optionally filtered by its open args.
+     * @param endpoint - endpoint.
+     * @param item - item to deliver.
+     * @param where - filter over open args.
+     * @returns how many streams received it.
+     */
+    push(endpoint: string, item: unknown, where?: StreamFilter): number;
+    /**
+     * End every matching open stream.
+     * @param endpoint - endpoint.
+     * @param where - filter over open args.
+     * @returns how many streams ended.
+     */
+    end(endpoint: string, where?: StreamFilter): number;
+    /**
+     * Fail every matching open stream with `error`.
+     * @param endpoint - endpoint.
+     * @param error - error the consumer's read rejects with.
+     * @param where - filter over open args.
+     * @returns how many streams failed.
+     */
+    fail(endpoint: string, error: Error, where?: StreamFilter): number;
+    /**
+     * Resolve once registered scripts have opened `endpoint` at least `count` times in total.
+     * @param endpoint - endpoint.
+     * @param count - opens to wait for.
+     */
+    opened(endpoint: string, count: number): Promise<void>;
+    /**
+     * Resolve once the consumer of every matching stream has pulled everything pushed so far and, for a stream still
+     * open, waits for more; a settled stream counts once its queue is empty, and a stream nobody reads never drains.
+     * Pulled means taken from the queue: a consumer that processes items asynchronously after pulling them may still
+     * be working on the last one.
+     * @param endpoint - endpoint.
+     * @param where - filter over open args.
+     */
+    drained(endpoint: string, where?: StreamFilter): Promise<void>;
+}
+/**
+ * The success envelope the Client's Remote callers read: `{ ok: true, value }`.
+ * @param value - success value.
+ * @returns the envelope.
+ */
+export declare function ok<T>(value: T): {
+    readonly ok: true;
+    readonly value: T;
+};
+/**
+ * Endpoint-named Remote mock. `dispatch` / `open` are the core; `rpc` is the
+ * same core as the decoded carrier accepted by the Connection installer.
+ */
+export declare class RemoteMock {
+    /**
+     * Create a mock whose `$events` stream answers the Gateway client's opening
+     * with one ready frame and then stays open, so the assembled client connects.
+     * @param options - host facts for the ready frame.
+     * @returns the mock.
+     */
+    static create(options?: RemoteMockOptions): RemoteMock;
+    private readonly unaryDefaults;
+    private readonly scripts;
+    private live;
+    private openWaiters;
+    private readonly logStore;
+    private readonly unaryMocks;
+    private readonly streamMocks;
+    private readonly proxy;
+    /**
+     * Native mock functions for every namespace: configure answers and inspect calls without declaring method names.
+     * Explicit stream registrations select stream mocks; all other methods use unary mocks.
+     * Native overrides belong to this instance; `mockReset()` restores the implementation reading current defaults.
+     * Generated declarations provide exact signatures; absent declarations weaken only this test-owned proxy.
+     */
+    readonly remote: MockedRemote;
+    /** Everything observed so far. */
+    readonly log: MockLog;
+    /** Control over streams opened by registered scripts. */
+    readonly streams: OpenStreams;
+    /**
+     * The Connection carrier face: `call` dispatches, `open` opens; payloads carry
+     * `{ args }` as the whole-client proxies (an array) or the Gateway's own
+     * endpoints (one object) send them, and a call aborted by its signal rejects.
+     */
+    readonly rpc: ClientConnectionRpc;
+    private constructor();
+    /**
+     * Set the endpoint's default positional-argument handler without changing its native mock overrides.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param rule - handler computing the answer.
+     * @returns this.
+     */
+    unary<Args extends readonly unknown[]>(endpoint: string, rule: UnaryRuleFn<Args>): this;
+    /**
+     * Set the endpoint's default answer, including explicit `undefined`, without changing its native mock overrides.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param rule - default answer.
+     * @returns this.
+     */
+    unary(endpoint: string, rule: unknown): this;
+    /**
+     * Declare `endpoint` as a stream and replace its default script when supplied. A declaration without a script
+     * preserves any existing script; an endpoint declared without one fails an open as a stream miss.
+     * @param endpoint - `<namespace>/<method>`.
+     * @param script - script (`frames` / `openStream` build the common ones).
+     * @returns this.
+     */
+    stream(endpoint: string, script?: StreamScript): this;
+    /**
+     * Register endpoint defaults without changing native mock overrides.
+     * @param table - unary answers and stream scripts.
+     * @returns this.
+     */
+    load(table: RemoteTable): this;
+    /**
+     * Whether `endpoint` is declared a stream (with or without a script) or has a unary rule — the one declaration
+     * the whole-client proxies need; an endpoint neither declared nor ruled is dispatched as a unary call.
+     * @param endpoint - endpoint.
+     * @returns the mode, or undefined when nothing is registered.
+     */
+    modeOf(endpoint: string): 'unary' | 'stream' | undefined;
+    /**
+     * Registered endpoints and accessed proxy methods, sorted.
+     * @returns endpoint names.
+     */
+    endpoints(): readonly string[];
+    /**
+     * Answer one unary call with the registered rule's value, verbatim. The call
+     * is logged as soon as its rule is selected and settles with the rule: a
+     * rule that throws or rejects fails the call with that error.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @returns the answer.
+     * @throws {Error} when no rule is registered (logged as unmatched).
+     */
+    dispatch(endpoint: string, args: readonly unknown[]): Promise<unknown>;
+    private unaryMock;
+    private unaryAnswer;
+    /**
+     * Open through the endpoint's native mock; its default runs the registered script as a controlled stream.
+     * A native override returns its own iterable: the caller owns consumption and cancellation, outside `OpenStreams`.
+     * @param endpoint - endpoint.
+     * @param args - positional args.
+     * @param signal - consumer cancellation.
+     * @returns the controlled script stream or the native override's caller-owned iterable.
+     * @throws {Error} when the default runs without a registered script (logged as unmatched).
+     */
+    open(endpoint: string, args: readonly unknown[], signal: AbortSignal): AsyncIterable<unknown>;
+    private streamMock;
+    private openScript;
+    /** Throw when any request found no rule, naming the endpoints and the registered ones. */
+    assertNoUnmatched(): void;
+    private noRuleMessage;
+    /** Streams on `endpoint` still open or still holding items their consumer has not pulled; the rest are forgotten. */
+    private matching;
+    private forEachOpen;
+    private wakeOpened;
+}
+//# sourceMappingURL=remote-mock.d.ts.map

package/lib/types/remote-proxy.d.ts

@@ -0,0 +1,15 @@
+/** Lazy namespace access for native Remote mocks; production Remote declarations stay unchanged. */
+import type { MaybeMockedDeep } from '@vitest/spy';
+import type { TypertRemoteNamespaceMap } from '@deepseek-ai/dsh-typert-protocol';
+/**
+ * Native mocks for every generated Remote namespace, or an unrestricted local proxy without generated types.
+ * @template Api - generated namespace map available in the caller's TypeScript program.
+ */
+export type MockedRemote<Api = TypertRemoteNamespaceMap> = keyof Api extends never ? any : MaybeMockedDeep<Api>;
+/**
+ * Cache accessed namespaces and expose the current native mock for each method.
+ * @param method - selects a stable endpoint mock for its configured invocation mode.
+ * @returns enumerable accessed namespaces and methods; symbols and thenable probes remain inert.
+ */
+export declare function createRemoteProxy(method: (endpoint: string) => unknown): Record<string, object>;
+//# sourceMappingURL=remote-proxy.d.ts.map

package/lib/types/streams.d.ts

@@ -0,0 +1,81 @@
+/** Stream scripts and the pushable, abort-aware stream a script drives. */
+import type { StreamRecord } from './log.ts';
+/** Test-side controls over one open stream. */
+export interface StreamHandle {
+    /** Queue one item for the consumer. */
+    push(item: unknown): void;
+    /** End the stream after the queued items drain. */
+    end(): void;
+    /** Fail the consumer's next read with `error` after the queued items drain. */
+    fail(error: Error): void;
+    /** Aborts when the opening signal aborts or the consumer returns early. */
+    readonly signal: AbortSignal;
+}
+/**
+ * How a stream endpoint answers an open: receives the open args and the
+ * handle; the stream stays open after the script returns until `end()` or
+ * `fail()`. A script that throws or rejects fails the stream with that error.
+ */
+export type StreamScript = (args: readonly unknown[], stream: StreamHandle) => void | Promise<void>;
+/**
+ * Script yielding `items`, then ending.
+ * @param items - items in order.
+ * @returns the script.
+ */
+export declare function frames(items: readonly unknown[]): StreamScript;
+/**
+ * Script yielding `initial`, then staying open for `streams.push`.
+ * @param initial - items yielded on open.
+ * @returns the script.
+ */
+export declare function openStream(initial?: readonly unknown[]): StreamScript;
+/** One open stream: a queue the script pushes into and a single consumer reads from; the log entry tracks its state. */
+export declare class MockStream implements StreamHandle, AsyncIterable<unknown> {
+    readonly record: StreamRecord;
+    private readonly sourceSignal;
+    private readonly queue;
+    private settled;
+    private waiting;
+    private drainWaiters;
+    private readonly cancellation;
+    readonly signal: AbortSignal;
+    /** Consumer cancellation listener; attached while the stream is open, removed when it settles or cancels. */
+    private readonly onAbort;
+    /** Items pushed but not yet pulled by the consumer. */
+    get queued(): number;
+    /**
+     * @param record - log entry this stream updates.
+     * @param sourceSignal - cancellation from the caller that opened the stream.
+     */
+    constructor(record: StreamRecord, sourceSignal: AbortSignal);
+    push(item: unknown): void;
+    end(): void;
+    fail(error: Error): void;
+    /**
+     * Start `script` on this stream.
+     * @param script - the registered script.
+     * @param args - open args.
+     */
+    run(script: StreamScript, args: readonly unknown[]): void;
+    /**
+     * Resolve once the consumer has pulled every queued item and waits for the next one, or the stream is no longer
+     * open and holds nothing the consumer could still pull (a consumer that returns discards what it left).
+     * @returns settles when drained.
+     */
+    drained(): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+    private next;
+    private pull;
+    private finish;
+    private settle;
+    private cancel;
+    private isDrained;
+    private wakeDrained;
+}
+/**
+ * The `Error` a thrown value stands for: itself, or a new Error carrying its string form.
+ * @param reason - thrown value.
+ * @returns the error.
+ */
+export declare function toError(reason: unknown): Error;
+//# sourceMappingURL=streams.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepseek-ai/dsh-remote-mock",
+  "description": "Endpoint-named mock for Typert Remote traffic: unary answers and stream scripts per <namespace>/<method>, live stream control, a log, and the Connection carrier face whole-client specs install",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/test-support/remote-mock"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@vitest/spy": "^4.1.8"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "@deepseek-ai/dsh-client-connection": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-api-settings-controller": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ]
+}