@deepseek-ai/dsh-typert-protocol 0.2.1-alpha.1 → 0.2.1-alpha.3

package/README.i18n.yaml

@@ -18,8 +18,11 @@
   en: c479b5b665822198
   zh: 1ffb789c18043baf
 /deepseek-ai-dsh-typert-protocol/use-this-package/exposing-a-host-method:
-  en: fae902875c18ef33
-  zh: ed4332cabe0e3a45
+  en: 63968de5fc817d06
+  zh: fbe2804b2a2d70d3
+/deepseek-ai-dsh-typert-protocol/use-this-package/identifying-the-caller-and-admitting-non-owner-callers:
+  en: 78e08ae732a8f6f4
+  zh: be15fb7599994fb9
 /deepseek-ai-dsh-typert-protocol/use-this-package/associating-host-objects-and-contexts-with-wire-identities:
   en: 3db384ae6f215632
   zh: 56207184b09d4018
@@ -36,17 +39,17 @@
   en: 4f45bb46a1920984
   zh: 70408d3b59d2735a
 /deepseek-ai-dsh-typert-protocol/understand-the-implementation/remote-markers:
-  en: 93b83a9441a5a3c2
-  zh: c4eb143ddd167a27
+  en: 082530713c5cea83
+  zh: 592fe5d9636ef288
 /deepseek-ai-dsh-typert-protocol/understand-the-implementation/protocol-maps-and-descriptors:
-  en: 164b30b3fa543936
-  zh: 0831edd3e04a3d3a
+  en: c202904201402211
+  zh: 3db1d83683b4fd2a
 /deepseek-ai-dsh-typert-protocol/understand-the-implementation/wire-identity-grammar:
   en: aac79a7b4682371e
   zh: bc9cc513c1ced3e6
 /deepseek-ai-dsh-typert-protocol/understand-the-implementation/source-map:
-  en: 62da405f16379f39
-  zh: fcbd0f10dd198018
+  en: 74fdb78bf4e7753b
+  zh: dad439ba2a323ff9
 /deepseek-ai-dsh-typert-protocol/further-exploration:
   en: 84191d1b07fb8bb6
   zh: 9a5212732ed38ab6
@@ -57,8 +60,8 @@
   en: b1c49d5e440d9d41
   zh: 87ead78472415189
 /deepseek-ai-dsh-typert-protocol/known-limitations-and-deferred-work:
-  en: 0be59e6d97923487
-  zh: 70523fb0dc567ed6
+  en: 32a7ede4de20ad4e
+  zh: 57b86c314cd376b8
 /deepseek-ai-dsh-typert-protocol/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -46,7 +46,21 @@ Generation turns the method into a wire endpoint under the service's namespace;
 
 A unary method can return `Uint8Array` directly or within nested objects, arrays, tuples, optional fields, unions, and recursive types. Generation supplies optional result codec `encode()` and `decode()` functions: encoding visits only subtrees whose types can contain bytes, while decoding validates reconstructed values; Client declarations use `Uint8Array<ArrayBuffer>` at every byte position while retaining other field types. Pure JSON results pass through without Host byte detection or Client parsing. Parameters, events, and stream items remain JSON-only; runtime object cycles are unsupported.
 
-A stream method (`@Remote({ mode: 'stream' })`) returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`. `In` declares the items the Client may send back on the same logical stream; the method reads them through `this.ctx.invocation.uplink<In>()`, and the descriptor carries their codec. `RemoteInvocation` also names the receiving `service`, the calling `peer` (a `PeerScope` the connection layer admitted), and the carrier `signal`; `ctx.invocation` is `undefined` on a Context no Remote call derived: the first `bindTypertRemote()` binding in a tree, which every `TypertRemoteService` constructor makes, registers that accessor on the root. A generated Client stream method returns `RemoteStreamHandle<Out, In>`: the handle with `send`, `end`, and `dispose` beside the downlink iteration. Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through.
+A stream method (`@Remote({ mode: 'stream' })`) returns `Iterable`, `AsyncIterable`, or `RemoteStream<Out, In>`. `In` declares the items the Client may send back on the same logical stream; the method reads them through `this.ctx.invocation.uplink<In>()`, and the descriptor carries their codec. `RemoteInvocation` also names the receiving `service`, the calling `peer` (the `PeerScope` its carrier names), and the carrier `signal`; `ctx.invocation` is `undefined` on a Context no Remote call derived: the first `bindTypertRemote()` binding in a tree, which every `TypertRemoteService` constructor makes, registers that accessor on the root. Cordis's cross-copy `Context.is()` recognizes a source Context passed to a built Service, so mixed source/built compositions retain this accessor and invocation-local principals. A generated Client stream method returns `RemoteStreamHandle<Out, In>`: the handle with `send`, `end`, and `dispose` beside the downlink iteration. Uplink items are validated one by one at the Host because they arrive from the browser; downlink items are values the Host method produced and pass through.
+
+`@Remote` options contain only `name`, `mode`, and the `resources` readers described below; input policy belongs to the consumer, not a method annotation. `method.input(options?: TypertRemoteInputOptions)` returns a cached `TypertRemoteValue<Input>`, with `strict?: boolean` as its only option. `method.input()` and `{ strict: false }` retain ordinary Remote handling: declared objects accept and strip unknown fields. `{ strict: true }` rejects undeclared fields recursively, while explicit JSON values and dictionary keys stay open and dictionary values retain their declared validation. Both named-argument envelopes reject extra arguments. Select one view (`const input = method.input({ strict: true })`) for matching `input.create().parse(raw)` and `input.jsonSchema`; this does not change Host dispatch. The [generator](<../generator/README.md#ordinary-remote-metadata>) owns publication and the paired codecs.
+
+Ordinary `./remote` artifacts export `TYPERT_REMOTE` as a `TypertRemoteInfo`, extending the mountable `TypertRemoteContribution`. Its typed `methods[endpoint]` entries are the same direct descriptor objects found in `descriptors`, with derived `input(options?)` and `invoke(remote, input, signal?)`. Parameter documentation lives in `parameters[].description`; `result` is the single result codec, parser, and optional projection. Unary descriptors omit `mode`; streams use `'stream'`. Context-only receivers remain in `descriptors` and scoped declarations, not `methods`.
+
+`createTypertRemoteInfo(spec, z)` from the published pure `@deepseek-ai/dsh-typert-protocol/remote-info` entry returns a class instance, not a constructor. Construction retains only the static spec and the caller-supplied Zod runtime; the first `descriptors` or `methods` read builds and caches their shared index. Each input-policy view, its parser, and its optional JSON Schema projection are independently lazy and cached; `method.input().create()` requests the ordinary parser. The raw spec requires Zod factories, while consumer-facing `TypertSchema<T>` promises only `parse(value: unknown): T`. JSON Schema comes from generator projections, not runtime `z.toJSONSchema()`. The leaf has no runtime imports; generated artifacts supply Zod. Metadata and schema access never invokes the network; the root also re-exports the factory but imports Cordis.
+
+The invoker takes a caller-owned, mounted, unscoped Client Remote and resolves its namespace method at call time. It preserves the namespace receiver, optional positional holes, and signal, forwarding the same `Promise<RemoteResult<DecodedOutput>>` or complete `RemoteStreamHandle<Output, Uplink>` without an async wrapper. `DecodedOutput` defaults to the authored output; generation supplies `RemoteDecoded<Output>` only for byte-bearing unary methods, avoiding recursive remapping of ordinary JSON results; `result.create().parse()` retains the authored output type and does not normalize shared byte buffers. Documentation and parsing remain available when either input variant or the result lacks JSON Schema support; each variant's `jsonSchemaError` explains its absent projection. Registry readers use `isTypertRemoteMethod(descriptor)` from the same pure entry to narrow a base descriptor to these direct capabilities.
+
+### Identifying the caller and admitting non-owner callers
+
+`PeerScope.principal` is the caller identity that in-process Host code fixes when it creates the Peer; no wire field can set it, and `PeerScope.signal` aborts when the Peer scope ends. `PrincipalMap` is merge-extensible: each driver declares one JSON entry with a unique literal `kind` and no credential, because a principal can be persisted in a Session log; the built-in entry is `owner: { kind: 'owner' }`. A Remote method that records its caller on durable output calls `principalOf(this.ctx.invocation)`, which returns the principal of a non-owner caller and `undefined` for the owner and outside a Remote call, and writes the field only when it is defined.
+
+Every Remote method is under access control: [`dsh-api-remote-access`](../../api/remote-access/README.md) decides whether a non-owner caller may reach it on the resources the call touches. `TypertResourceMap` is merge-extensible beside `TypertLookupMap`: the package that owns an identity type declares its resource kind as `TypertResource<Id>` (`dsh-session` declares `session: TypertResource<SessionId>`, `dsh-workspace` declares `workspace: TypertResource<WorkspaceId>`). A `RemoteAccessResource` is either the built-in identity-less `{ kind: 'global' }` or one declared kind with its identity; resources are independent, so access to `global` implies nothing about any session. At runtime the domain that owns a kind registers its default wire field through `typert.resources.register(kind, { field })`, which rejects `global`; a lookup provider and a Host Context adapter name the kind their wire identity carries through `resource`, so a method with an Agent lookup parameter or an Agent-scoped receiver carries a `session` resource without options. The `resources` option of `@Remote` and `@RemoteScope` maps a kind to a reader that receives the method's wire arguments as its own parameters; their types are inferred from the decorated method, with lookup parameters mapped to their wire types, so `@Remote({ name: 'page', resources: { session: request => request.address.sessionId } })` reads a field the defaults cannot. A call whose readers and defaults name no resource touches `global`; they must name every resource the method accesses, because access control never checks one they omit. A forwarded `emit` entry of `TypertForwardableEventEntry` declares `resources` readers typed by its own event's parameters, and an entry without them touches `global`. Resource resolution belongs to the [API Gateway](../../api/gateway/README.md); decisions and refusal reasons belong to [`dsh-api-remote-access`](../../api/remote-access/README.md).
 
 ### Associating Host objects and Contexts with wire identities
 
@@ -89,11 +103,15 @@ The package keeps strict reflection in the compiler: decorator initializers reta
 
 ### Remote markers
 
-`@Remote` and `@RemoteScope` schedule an initializer that appends the method name, an optional export name, and the invocation mode to the prototype descriptor; `remoteMethods(service)` validates its version and returns a detached declaration-order snapshot that the Gateway's source-mode fallback reads. Markers require public, non-static instance methods with string names, and conflicting markers on one method are rejected.
+`@Remote` and `@RemoteScope` schedule an initializer that appends the method name, an optional export name, the invocation mode, and the frozen `resources` readers to the prototype descriptor; `remoteMethods(service)` validates its version and returns a detached declaration-order snapshot that the Gateway's source-mode fallback reads. Markers require public, non-static instance methods with string names, and conflicting markers on one method are rejected.
+
+Readers are validated when the decorator is created and frozen into one record per decorator application; the Gateway reads them from `remoteMethods(service)` by implementation member name, so another installed copy of the protocol package reads the same record.
 
 ### Protocol maps and descriptors
 
-The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, the uplink codec, cancellation, and result codecs.
+The merge-extensible protocol maps keep static associations in the type system, while runtime providers register resolution with `ctx.typert`; the map names and shapes live in [`src/types.ts`](src/types.ts). `InvocationDescriptor` is the shared runtime form consumed by the registry, the Gateway, and the Client Remote, covering direct and Context receivers, JSON and lookup parameters, scope projections, the uplink codec, cancellation, result codecs, and documentation. Generated `TypertRemoteMethod` objects extend this descriptor directly.
+
+`RemoteInvocation.uplinkWindow` optionally describes the carrier's complete-frame inbox capacity and the UTF-8 envelope cost added to compact JSON items. Its absence means the carrier has no encoded-frame inbox limit; consumers still own their local buffering and acknowledgement policy.
 
 ### Wire identity grammar
 
@@ -104,9 +122,12 @@ Every namespace, method, lookup, and Context segment must satisfy `isTypertRemot
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | Decorators, Gateway bindings, `remoteMethods`, segment validation |
+| [`src/principal.ts`](src/principal.ts) | `principalOf`, the caller principal a Remote-call producer records |
+| [`src/remote-access.ts`](src/remote-access.ts) | `RemoteAccessResource`, `RemoteAccessResourceKind`, and `RemoteAccessResourceOf` over `TypertResourceMap` |
 | [`src/json-value.ts`](src/json-value.ts) | `isRemoteJsonValue` and `isRemoteUplinkItem`, the lossless JSON checks every carrier shares |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` and the structural `remoteErrorOf` recognizer |
-| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `RemoteStream`, `RemoteStreamHandle`, `PeerScope`, `RemoteInvocation`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
+| [`src/remote-info.ts`](src/remote-info.ts) | Pure lazy info factory and direct-method type guard |
+| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `RemoteStream`, `RemoteStreamHandle`, `PrincipalMap`, `Principal`, `PeerScope`, `RemoteInvocation`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
 
 </details>
 
@@ -141,7 +162,7 @@ No direct effect; the declared contracts reach a request only when an assembly p
 
 These limits define what the declarations can represent; they are current package constraints, not a task backlog.
 
-- **Decorator markers are minimal** — markers contain only the method name and the direct or Context invocation mode; parameter, result, lookup, and schema reflection require the Typert build pipeline.
+- **Decorator markers are minimal** — markers contain the method name, optional export alias, stream mode, resource readers, and direct or Context receiver selection; parameter, result, lookup, schema, and documentation metadata require the Typert build pipeline.
 - **Remote signatures are restricted** — decorators accept only public, non-static instance methods with string names, and source-mode execution cannot represent overloaded, destructured, defaulted, or rest-parameter signatures.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -46,7 +46,21 @@ export class GoalService extends TypertRemoteService {
 
 一元方法可以直接返回 `Uint8Array`，也可以将其放在嵌套对象、数组、元组、可选字段、联合类型和递归类型中。生成器提供可选的结果 codec `encode()` 和 `decode()`：编码仅访问类型可能包含字节的子树，解码则校验还原后的值；Client 声明在每个字节位置使用 `Uint8Array<ArrayBuffer>`，同时保留其他字段类型。纯 JSON 结果不经 Host 字节识别或 Client 解析直接传递。参数、事件与流条目仍仅支持 JSON；不支持运行时对象循环。
 
-流方法（`@Remote({ mode: 'stream' })`）返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out, In>`。`In` 声明 Client 可以在同一条逻辑流上回送的项；方法通过 `this.ctx.invocation.uplink<In>()` 读取它们，描述符携带其 codec。`RemoteInvocation` 还给出接收服务 `service`、发起调用的 `peer`（连接层接纳的一个 `PeerScope`）与载体 `signal`；非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`：树中第一个 `bindTypertRemote()` 绑定（每个 `TypertRemoteService` 构造函数都会建立一个）在根上注册该 accessor。生成的 Client 流方法返回 `RemoteStreamHandle<Out, In>`：在下行迭代之外提供 `send`、`end` 与 `dispose` 的句柄。上行项在 Host 逐项校验，因为它们来自浏览器；下行项是 Host 方法产出的值，原样透传。
+流方法（`@Remote({ mode: 'stream' })`）返回 `Iterable`、`AsyncIterable` 或 `RemoteStream<Out, In>`。`In` 声明 Client 可以在同一条逻辑流上回送的项；方法通过 `this.ctx.invocation.uplink<In>()` 读取它们，描述符携带其 codec。`RemoteInvocation` 还给出接收服务 `service`、发起调用的 `peer`（其载体指明的 `PeerScope`）与载体 `signal`；非 Remote 调用派生的 Context 上 `ctx.invocation` 为 `undefined`：树中第一个 `bindTypertRemote()` 绑定（每个 `TypertRemoteService` 构造函数都会建立一个）在根上注册该 accessor。Cordis 的跨副本 `Context.is()` 可识别传给构建产物 Service 的源码 Context，因此混合源码／构建组合仍保留此 accessor 和调用局部的 principal。生成的 Client 流方法返回 `RemoteStreamHandle<Out, In>`：在下行迭代之外提供 `send`、`end` 与 `dispose` 的句柄。上行项在 Host 逐项校验，因为它们来自浏览器；下行项是 Host 方法产出的值，原样透传。
+
+`@Remote` 选项仅包含 `name`、`mode` 与下文所述的 `resources` 读取函数；输入策略由消费方选择，而非方法注解。`method.input(options?: TypertRemoteInputOptions)` 返回缓存的 `TypertRemoteValue<Input>`，唯一选项是 `strict?: boolean`。`method.input()` 与 `{ strict: false }` 保留普通 Remote 处理方式：已声明对象接受并剥离未知字段。`{ strict: true }` 递归拒绝未声明字段，而显式 JSON 值和字典键保持开放，字典值仍按声明校验。两种具名参数封装都拒绝额外参数。选择一个视图（`const input = method.input({ strict: true })`），即可通过 `input.create().parse(raw)` 与 `input.jsonSchema` 取得匹配的解析和投影；这不会改变 Host 分发。[生成器](<../generator/README.zh.md#ordinary-remote-metadata>)负责发布及配套 codec。
+
+普通 `./remote` 产物将 `TYPERT_REMOTE` 导出为 `TypertRemoteInfo`，它扩展可挂载的 `TypertRemoteContribution`。类型化的 `methods[endpoint]` 条目就是 `descriptors` 中同一个直接方法描述符对象，并带有派生的 `input(options?)` 和 `invoke(remote, input, signal?)`。参数文档位于 `parameters[].description`；`result` 是唯一的结果 codec、解析器和可选投影。一元描述符省略 `mode`；流使用 `'stream'`。仅使用 Context 接收器的方法保留在 `descriptors` 和作用域声明中，不进入 `methods`。
+
+已发布的纯入口 `@deepseek-ai/dsh-typert-protocol/remote-info` 提供 `createTypertRemoteInfo(spec, z)`，返回类实例而非构造函数。构造时只保留静态 spec 和调用方传入的 Zod 运行时；首次读取 `descriptors` 或 `methods` 时才构建并缓存两者共享的索引。每种输入策略的视图、解析器及可选 JSON Schema 投影都独立惰性求值并缓存；`method.input().create()` 请求普通解析器。原始 spec 要求 Zod factory，而面向消费方的 `TypertSchema<T>` 仅保证 `parse(value: unknown): T`。JSON Schema 来自生成器投影，而非运行时 `z.toJSONSchema()`。纯叶入口没有运行时导入；Zod 由生成产物提供。读取元数据和 schema 绝不发起网络调用；根入口也重新导出该 factory，但会导入 Cordis。
+
+调用器接收调用方拥有、已挂载且无作用域的 Client Remote，并在调用时解析其命名空间方法。它保留命名空间接收者、可选位置参数空位和 signal，不使用 async 包装，直接转发同一个 `Promise<RemoteResult<DecodedOutput>>` 或完整 `RemoteStreamHandle<Output, Uplink>`。`DecodedOutput` 默认采用原始输出类型；生成器仅为含字节的一元方法指定 `RemoteDecoded<Output>`，避免递归重映射普通 JSON 结果；`result.create().parse()` 保留原始输出类型，不会规范化共享字节缓冲区。任一输入变体或结果不支持 JSON Schema 时，文档与解析能力仍然保留；各变体的 `jsonSchemaError` 说明其投影缺失的原因。Registry 读取方使用同一纯入口提供的 `isTypertRemoteMethod(descriptor)`，将基础描述符收窄为这些直接调用能力。
+
+### 识别调用方并放行非 owner 调用方
+
+`PeerScope.principal` 是进程内 Host 代码创建 Peer 时固定的调用方身份；任何 wire 字段都无法设置它，`PeerScope.signal` 则在 Peer scope 结束时中止。`PrincipalMap` 可合并扩展：每个驱动方声明一个 JSON 条目，带唯一的字面量 `kind` 且不含凭据，因为 principal 可能持久化到会话日志中；内置条目是 `owner: { kind: 'owner' }`。在持久输出上记录调用方的 Remote 方法调用 `principalOf(this.ctx.invocation)`：调用方不是 owner 时它返回该 principal，对 owner 以及在 Remote 调用之外返回 `undefined`；方法只在其有定义时写入该字段。
+
+每个 Remote 方法都受访问控制：由 [`dsh-api-remote-access`](../../api/remote-access/README.zh.md) 判定非 owner 调用方能否在该调用触及的资源上调用它。`TypertResourceMap` 与 `TypertLookupMap` 并列、可合并扩展：拥有身份类型的包以 `TypertResource<Id>` 声明自己的资源种类（`dsh-session` 声明 `session: TypertResource<SessionId>`，`dsh-workspace` 声明 `workspace: TypertResource<WorkspaceId>`）。`RemoteAccessResource` 要么是内置、无身份的 `{ kind: 'global' }`，要么是某个已声明种类加其身份；资源之间相互独立，`global` 上的访问不蕴含任何会话上的访问。运行时由拥有该种类的领域经 `typert.resources.register(kind, { field })` 登记默认 wire 字段，该登记拒绝 `global`；lookup provider 与 Host Context adapter 经 `resource` 声明其 wire 身份所属的种类，因此带 Agent 查找参数或 Agent 作用域接收器的方法无需选项即携带 `session` 资源。`@Remote` 与 `@RemoteScope` 的 `resources` 选项把种类映射到一个以方法 wire 参数为自身位置参数的读取函数；这些参数的类型从被装饰的方法推断，查找参数映射为其 wire 类型，因此 `@Remote({ name: 'page', resources: { session: request => request.address.sessionId } })` 可以读取默认规则读不到的字段。读取函数与默认规则都未给出资源的调用触及 `global`；它们必须给出方法访问的全部资源，因为访问控制从不检查被遗漏的资源。`TypertForwardableEventEntry` 中的转发 `emit` 条目可以声明 `resources` 读取函数，其类型由该事件自身的参数决定；未声明的条目触及 `global`。资源解析归 [API Gateway](../../api/gateway/README.zh.md)；判定与拒绝原因归 [`dsh-api-remote-access`](../../api/remote-access/README.zh.md)。
 
 ### 把 Host 对象与 Context 关联到 wire identity
 
@@ -89,11 +103,15 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 ### Remote 标记
 
-`@Remote` 与 `@RemoteScope` 调度一个初始化器，把方法名、可选导出名与调用模式追加到原型描述符；`remoteMethods(service)` 校验其版本，并返回与已存描述符分离、按声明顺序排列的快照，供 Gateway 的源码模式回退读取。标记要求名称为字符串的公开、非静态实例方法，同一方法上的冲突标记会被拒绝。
+`@Remote` 与 `@RemoteScope` 调度一个初始化器，把方法名、可选导出名、调用模式与冻结的 `resources` 读取函数追加到原型描述符；`remoteMethods(service)` 校验其版本，并返回与已存描述符分离、按声明顺序排列的快照，供 Gateway 的源码模式回退读取。标记要求名称为字符串的公开、非静态实例方法，同一方法上的冲突标记会被拒绝。
+
+读取函数在创建装饰器时校验，并按每次装饰器应用冻结为一条记录；Gateway 按实现成员名从 `remoteMethods(service)` 读取它们，因此协议包的另一个已安装副本也能读取同一记录。
 
 ### 协议映射与描述符
 
-可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、上行编解码器、取消与结果编解码器。
+可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、上行编解码器、取消、结果编解码器与文档。生成的 `TypertRemoteMethod` 对象直接扩展该描述符。
+
+`RemoteInvocation.uplinkWindow` 可选地描述载体完整帧 inbox 的容量，以及紧凑 JSON 项之外的 UTF-8 封装开销。字段缺省表示载体没有编码帧 inbox 限额；消费者仍负责本地缓存与确认策略。
 
 ### Wire 标识文法
 
@@ -104,9 +122,12 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 装饰器、Gateway 绑定、`remoteMethods`、段校验 |
+| [`src/principal.ts`](src/principal.ts) | `principalOf`：Remote 调用生产者记录的调用方 principal |
+| [`src/remote-access.ts`](src/remote-access.ts) | 基于 `TypertResourceMap` 的 `RemoteAccessResource`、`RemoteAccessResourceKind` 与 `RemoteAccessResourceOf` |
 | [`src/json-value.ts`](src/json-value.ts) | 各载体共享的无损 JSON 校验 `isRemoteJsonValue` 与 `isRemoteUplinkItem` |
 | [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` 与结构式识别函数 `remoteErrorOf` |
-| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`RemoteStream`、`RemoteStreamHandle`、`PeerScope`、`RemoteInvocation`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
+| [`src/remote-info.ts`](src/remote-info.ts) | 纯惰性 info factory 与直接方法类型守卫 |
+| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`RemoteStream`、`RemoteStreamHandle`、`PrincipalMap`、`Principal`、`PeerScope`、`RemoteInvocation`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
 
 </details>
 
@@ -141,7 +162,7 @@ Host 装配以转发给消费方的 Cordis 事件扩展 `TypertRemoteEventSelect
 
 这些限制说明声明能表示什么；它们是当前包约束，不是任务积压。
 
-- **装饰器标记是最小化的**——标记只包含方法名与直接调用或 Context 调用模式；参数、结果、查找与 schema 反射需要 Typert 构建流水线。
+- **装饰器标记是最小化的**——标记包含方法名、可选的导出别名、流模式、资源读取函数，以及直接或 Context 接收器选择；参数、结果、查找、schema 与文档元数据需要 Typert 构建流水线。
 - **Remote 签名受限**——装饰器只接受具有字符串名称的公开、非静态实例方法，源码模式执行无法表示重载、解构、默认参数或剩余参数签名。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -116,6 +116,186 @@ function visitJsonValue(value, ancestors) {
 	}
 }
 //#endregion
+//#region lib/types/remote-info.js
+/** Lazy assembly of generated Remote definitions using caller-supplied Zod; no runtime imports. */
+/**
+* Retain one generated definition per endpoint without constructing parsers or projections.
+* The class instance builds its shared descriptor/method index on first access;
+* input schemas and JSON Schema projections are cached only when requested.
+* @param spec - compiler-produced method facts and Zod factories.
+* @param zod - the generated artifact's Zod runtime for named-input parsers.
+* @returns a lazy, mountable info instance with no registration or transport effects.
+*/
+function createTypertRemoteInfo(spec, zod) {
+	return new RemoteInfo(spec, zod);
+}
+var RemoteInfo = class {
+	spec;
+	zod;
+	index;
+	constructor(spec, zod) {
+		this.spec = spec;
+		this.zod = zod;
+	}
+	get package() {
+		return this.spec.package;
+	}
+	get descriptors() {
+		return this.resolve().descriptors;
+	}
+	get methods() {
+		return this.resolve().methods;
+	}
+	resolve() {
+		if (this.index !== void 0) return this.index;
+		const zod = this.zod;
+		const descriptors = [];
+		const methods = Object.create(null);
+		for (const [endpoint, definition] of Object.entries(this.spec.methods)) {
+			const separator = endpoint.indexOf("/");
+			const namespace = endpoint.slice(0, separator);
+			const method = endpoint.slice(separator + 1);
+			const parameters = definition.parameters.map((parameter) => ({
+				...parameter,
+				wire: parameter.wire ?? parameter.name
+			}));
+			const descriptor = {
+				...definition,
+				id: `${this.spec.package}#${endpoint}`,
+				namespace,
+				method,
+				parameters,
+				result: definition.result.description === void 0 ? definition.result : new ResultValue(definition.result)
+			};
+			if (definition.invocation.kind === "direct") {
+				const inputs = [];
+				methods[endpoint] = Object.assign(descriptor, {
+					input(options) {
+						const strict = options?.strict === true;
+						return inputs[strict ? 1 : 0] ??= new NamedInput(parameters, strict, zod);
+					},
+					invoke(remote, input, signal) {
+						const named = input;
+						const values = parameters.map((parameter) => named[parameter.wire]);
+						if (definition.cancellation !== void 0) values.push(signal);
+						const receiver = Reflect.get(remote, namespace);
+						return Reflect.get(receiver, method).apply(receiver, values);
+					}
+				});
+			}
+			descriptors.push(descriptor);
+		}
+		return this.index = {
+			descriptors,
+			methods
+		};
+	}
+};
+/**
+* Narrow a Registry descriptor to its generated direct-method capabilities.
+* @param descriptor - a live descriptor, including possible source fallback or Context-only receivers.
+* @returns whether generated named input and direct invocation are available.
+*/
+function isTypertRemoteMethod(descriptor) {
+	return descriptor.invocation.kind === "direct" && descriptor.result.mode === "strict" && "input" in descriptor && typeof descriptor.input === "function" && "invoke" in descriptor && typeof descriptor.invoke === "function";
+}
+function optional(parameter) {
+	return parameter.source === "json" && parameter.acceptsUndefined === true;
+}
+var NamedInput = class {
+	parameters;
+	strict;
+	zod;
+	schema;
+	projection;
+	constructor(parameters, strict, zod) {
+		this.parameters = parameters;
+		this.strict = strict;
+		this.zod = zod;
+	}
+	codec(parameter) {
+		return this.strict ? parameter.strictCodec : parameter.codec;
+	}
+	create = () => this.schema ??= this.zod.strictObject(Object.fromEntries(this.parameters.map((parameter) => {
+		const value = this.codec(parameter).create();
+		return [parameter.wire, optional(parameter) ? value.optional() : value.nonoptional()];
+	})));
+	get jsonSchema() {
+		return this.project().jsonSchema;
+	}
+	get jsonSchemaError() {
+		return this.project().jsonSchemaError;
+	}
+	project() {
+		if (this.projection !== void 0) return this.projection;
+		const unavailable = this.parameters.find((parameter) => this.codec(parameter).jsonSchema === void 0);
+		if (unavailable !== void 0) return this.projection = { jsonSchemaError: this.codec(unavailable).jsonSchemaError ?? `No JSON Schema for parameter ${unavailable.wire}` };
+		return this.projection = { jsonSchema: {
+			type: "object",
+			properties: Object.fromEntries(this.parameters.map((parameter) => [parameter.wire, {
+				...this.codec(parameter).jsonSchema,
+				...parameter.description === void 0 ? {} : { description: parameter.description }
+			}])),
+			required: this.parameters.filter((parameter) => !optional(parameter)).map((parameter) => parameter.wire),
+			additionalProperties: false
+		} };
+	}
+};
+var ResultValue = class {
+	spec;
+	projection;
+	constructor(spec) {
+		this.spec = spec;
+	}
+	get mode() {
+		return this.spec.mode;
+	}
+	get typeSymbol() {
+		return this.spec.typeSymbol;
+	}
+	get create() {
+		return this.spec.create;
+	}
+	get decode() {
+		return this.spec.decode;
+	}
+	get encode() {
+		return this.spec.encode;
+	}
+	get description() {
+		return this.spec.description;
+	}
+	get jsonSchemaError() {
+		return this.spec.jsonSchemaError;
+	}
+	get jsonSchema() {
+		if (this.projection === void 0) {
+			const schema = this.spec.jsonSchema;
+			this.projection = { value: schema === void 0 ? void 0 : {
+				...schema,
+				description: this.spec.description
+			} };
+		}
+		return this.projection.value;
+	}
+};
+//#endregion
+//#region lib/types/principal.js
+/**
+* Reads the non-owner caller of the current Remote call.
+* @module @deepseek-ai/dsh-typert-protocol/principal
+*/
+/**
+* The identity a Remote-call producer records on durable output.
+* @param invocation - `ctx.invocation`; `undefined` outside a Remote call.
+* @returns the caller's principal when it is not the owner; `undefined` for the
+*   owner and for trusted in-process code outside a Remote call.
+*/
+function principalOf(invocation) {
+	const principal = invocation?.peer.principal;
+	return principal?.kind === "owner" ? void 0 : principal;
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Remote decorators and explicit Gateway bindings backed by versioned
@@ -140,7 +320,7 @@ const REMOTE_METHOD_DESCRIPTOR = "@deepseek-ai/dsh-typert-protocol/remote-method
 * a Host composition to read it.
 * @param service - owning Service instance, normally `this`.
 * @param serviceKey - exact Cordis service key.
-* @param options - optional distinct wire namespace.
+* @param options - optional wire namespace.
 * @returns a frozen, inspectable binding with no compiler-injected metadata.
 */
 function bindTypertRemote(service, serviceKey, options = {}) {
@@ -148,7 +328,7 @@ function bindTypertRemote(service, serviceKey, options = {}) {
 	const namespace = options.namespace ?? serviceKey;
 	validateName("namespace", namespace);
 	const ctx = Reflect.get(service, "ctx");
-	if (ctx instanceof Context) provideInvocationAccessor(ctx);
+	if (Context.is(ctx)) provideInvocationAccessor(ctx);
 	return Object.freeze({
 		service,
 		serviceKey,
@@ -163,7 +343,7 @@ var TypertRemoteService = class extends Service {
 	* Register the Service and bind the same key to Typert Gateway.
 	* @param ctx - owning Cordis Context.
 	* @param serviceKey - exact Cordis service key and default wire namespace.
-	* @param options - optional distinct wire namespace.
+	* @param options - optional wire namespace.
 	*/
 	constructor(ctx, serviceKey, options = {}) {
 		super(ctx, serviceKey);
@@ -183,36 +363,57 @@ function provideInvocationAccessor(ctx) {
 function Remote(methodExportOrOptions, context) {
 	if (typeof methodExportOrOptions === "string") {
 		validateName("Remote export name", methodExportOrOptions);
-		return remoteDecorator({ kind: "direct" }, void 0, methodExportOrOptions);
-	}
-	if (typeof methodExportOrOptions === "object") {
-		if (remoteOptionMode(methodExportOrOptions) !== "stream" || Reflect.ownKeys(methodExportOrOptions).length !== 1) throw new TypeError("typert-protocol: Remote options must contain exactly mode: \"stream\"");
-		return remoteDecorator({ kind: "direct" }, "stream");
+		return remoteDecorator({ kind: "direct" }, { exportName: methodExportOrOptions });
 	}
+	if (typeof methodExportOrOptions === "object") return remoteDecorator({ kind: "direct" }, markerOptions(methodExportOrOptions, REMOTE_OPTION_KEYS, "Remote options require name, mode: \"stream\", or resources"));
 	if (context === void 0) throw new TypeError("typert-protocol: Remote decorator context is missing");
 	addMarkerInitializer(context, { kind: "direct" });
 }
-function remoteOptionMode(options) {
-	return Reflect.get(options, "mode");
+const REMOTE_OPTION_KEYS = new Set([
+	"name",
+	"mode",
+	"resources"
+]);
+const REMOTE_SCOPE_OPTION_KEYS = new Set(["name", "resources"]);
+/** Validate one decorator options object against its accepted keys and select the marker fields. */
+function markerOptions(options, accepted, requirement) {
+	const keys = Reflect.ownKeys(options);
+	if (keys.length === 0 || keys.some((key) => typeof key !== "string" || !accepted.has(key)) || Object.hasOwn(options, "mode") && options.mode !== "stream") throw new TypeError(`typert-protocol: ${requirement}`);
+	const { mode, name, resources } = options;
+	if (name !== void 0) validateName("Remote export name", name);
+	return {
+		...mode === void 0 ? {} : { mode },
+		...name === void 0 ? {} : { exportName: name },
+		...resources === void 0 ? {} : { resources: resourceReaders(resources) }
+	};
+}
+/** Freeze declared readers into the marker record; a misdeclared reader fails at decoration. */
+function resourceReaders(resources) {
+	const readers = {};
+	for (const [kind, reader] of Object.entries(resources)) {
+		if (typeof reader !== "function") throw new TypeError(`typert-protocol: Remote resource reader "${kind}" must be a function`);
+		readers[kind] = reader;
+	}
+	if (Object.keys(readers).length === 0) throw new TypeError("typert-protocol: Remote resources require at least one reader");
+	return Object.freeze(readers);
 }
-function remoteDecorator(invocation, mode, exportName) {
+function remoteDecorator(invocation, options = {}) {
 	return function(_method, context) {
-		addMarkerInitializer(context, invocation, mode, exportName);
+		addMarkerInitializer(context, invocation, options);
 	};
 }
-/**
-* Create a decorator for a method resolved from one Remote Scope.
-* @param key - scope key declared through the Context map.
-* @param exportName - optional Remote export name; defaults to the method name.
-* @returns a standard method decorator that records a versioned prototype descriptor.
-*/
-function RemoteScope(key, exportName) {
+function RemoteScope(key, option) {
 	validateName("Scope key", key);
-	if (exportName !== void 0) validateName("Remote export name", exportName);
-	return remoteDecorator({
+	const invocation = {
 		kind: "context",
 		context: key
-	}, void 0, exportName);
+	};
+	if (option === void 0) return remoteDecorator(invocation);
+	if (typeof option === "string") {
+		validateName("Remote export name", option);
+		return remoteDecorator(invocation, { exportName: option });
+	}
+	return remoteDecorator(invocation, markerOptions(option, REMOTE_SCOPE_OPTION_KEYS, "RemoteScope options require name or resources"));
 }
 /**
 * Read Remote markers attached to a live Service's class prototype.
@@ -236,26 +437,27 @@ function readRemoteMethodDescriptor(prototype) {
 	if (!Array.isArray(methods)) throw new TypeError("typert-protocol: Remote method descriptor methods must be an array");
 	return descriptor;
 }
-function addMarkerInitializer(context, invocation, mode, exportName) {
+function addMarkerInitializer(context, invocation, options = {}) {
 	if (context.private || context.static || typeof context.name !== "string") throw new TypeError("typert-protocol: Remote decorators require a public instance method with a string name");
 	const method = context.name;
 	context.addInitializer(function() {
 		const prototype = Object.getPrototypeOf(this);
 		if (prototype === null) throw new TypeError(`typert-protocol: cannot mark Remote method "${method}" on an object without a prototype`);
-		mark(prototype, method, invocation, mode, exportName);
+		mark(prototype, method, invocation, options);
 	});
 }
-function mark(prototype, method, invocation, mode, exportName) {
+function mark(prototype, method, invocation, { mode, exportName, resources }) {
 	const descriptor = readRemoteMethodDescriptor(prototype);
 	const marker = Object.freeze({
 		method,
 		...exportName === void 0 || exportName === method ? {} : { exportName },
 		...mode === void 0 ? {} : { mode },
-		invocation: Object.freeze(invocation)
+		invocation: Object.freeze(invocation),
+		...resources === void 0 ? {} : { resources }
 	});
 	const current = descriptor?.methods.find((candidate) => candidate.method === method);
 	if (current !== void 0) {
-		if (current.exportName === marker.exportName && current.mode === marker.mode && sameInvocation(current.invocation, invocation)) return;
+		if (current.exportName === marker.exportName && current.mode === marker.mode && current.resources === marker.resources && sameInvocation(current.invocation, invocation)) return;
 		throw new Error(`typert-protocol: Remote method "${method}" has conflicting invocation markers`);
 	}
 	Object.defineProperty(prototype, REMOTE_METHOD_DESCRIPTOR, {
@@ -275,4 +477,4 @@ function validateName(subject, value) {
 	if (!isTypertRemoteSegment(value)) throw new TypeError(`typert-protocol: ${subject} must contain only RPC endpoint segment characters`);
 }
 //#endregion
-export { Remote, RemoteError, RemoteScope, TYPERT_OWNED_VALUE, TypertRemoteService, bindTypertRemote, isRemoteJsonValue, isRemoteUplinkItem, isTypertOwnedValue, isTypertRemoteSegment, remoteErrorOf, remoteMethods, typertOwnedValue };
+export { Remote, RemoteError, RemoteScope, TYPERT_OWNED_VALUE, TypertRemoteService, bindTypertRemote, createTypertRemoteInfo, isRemoteJsonValue, isRemoteUplinkItem, isTypertOwnedValue, isTypertRemoteMethod, isTypertRemoteSegment, principalOf, remoteErrorOf, remoteMethods, typertOwnedValue };