@x1a0f3n9/dsh-typert-protocol 0.1.2-alpha.6

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/typert/protocol/README.md
+README.md: 7f7c817073c7c5ca3bb3746fe681f8fd426a3167
+README.zh.md: 462e20b80967a8e7546a9cab71e6d1eebe4cc807

package/README.md

@@ -0,0 +1,149 @@
+---
+description: "The shared Typert Remote protocol: decorators, wire descriptors, codecs, and provider contracts used by business packages, generated artifacts, the Host Gateway, and the Client API."
+kind: "package-library"
+---
+
+# @x1a0f3n9/dsh-typert-protocol
+
+English | [中文](README.zh.md)
+
+## Summary
+
+With `dsh-typert-protocol`, business packages can expose Host methods to Remote clients: mark a method with `@Remote` (or `@RemoteScope` for scoped receivers), bind the service to a wire namespace, and associate Host objects and scoped Contexts with wire identities through the merge-extensible protocol maps. Generated artifacts, the Host Gateway, and the Client API consume the same invocation descriptors, codecs, and provider contracts, so one declaration set stays in sync across every face. The package registers no Cordis service and runs no TypeScript analysis; it declares types and decorator markers only.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [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
+
+This package is for business-package and assembly maintainers who expose Host capabilities to Remote clients. It is a declarations library: mark methods, bind services, and let the generated pipeline and the Gateway do the rest.
+
+### Exposing a Host method
+
+A business package marks a public instance method with `@Remote` (or `@RemoteScope(key)` when the receiver comes from a scoped Context), and the owning service either extends `TypertRemoteService` or declares a `typertRemote` binding through `bindTypertRemote()`:
+
+```text
+import { Remote, TypertRemoteService } from '@x1a0f3n9/dsh-typert-protocol'
+
+export class GoalService extends TypertRemoteService {
+  @Remote
+  async create(agentId: string, objective: string): Promise<GoalResult> {
+    ...
+  }
+}
+```
+
+Generation turns the method into a wire endpoint under the service's namespace; Clients call it as a typed method through `ctx.remote` (see the [API Gateway reference](../../../docs/api-gateway.md)). A method opts into cooperative cancellation by declaring `signal: AbortSignal` as its final parameter — the signal is injected, never a JSON parameter or lookup field.
+
+### Associating Host objects and Contexts with wire identities
+
+Complex Host objects cannot cross the wire directly. A business package declares the association through the merge-extensible `TypertLookupMap` and `TypertContextMap`. Host and Client Context adapters both map `Context` to a wire identity and that identity back to `Context`; the Host adapter also owns the stable wire declaration. Host composition may override its synchronous or asynchronous resolver. A resolver that refuses on policy grounds throws `RemoteError` with its own code, which reaches the caller unchanged.
+
+### Reporting and reading a Remote failure
+
+One class carries every Remote failure: `RemoteError`, holding a stable `<domain>/<reason>` code and the details typed for that code. This package declares the universal carrier codes (`gateway/bad-request`, `gateway/cancelled`, `gateway/internal`) and owns `RemoteErrorDetailsMap`, the merge-extensible table every other package extends beside its own throwing code:
+
+```text
+declare module '@x1a0f3n9/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    'goal/not-found': { readonly goalId: string }
+  }
+}
+throw new RemoteError('goal/not-found', `goal "${id}" does not exist`, { goalId: id })
+```
+
+An owner throws at the failure point; no package writes an error-class family or an exit-mapping function. A caller discriminates by `code` — never by `instanceof` — and a `code` branch narrows `details` with no cast, because `RemoteFailure` is the code-discriminated union of `RemoteError` instances. Infrastructure that must recognize a failure carried across a module or realm copy of the class calls `remoteErrorOf(value)`, which reads a structural marker instead of the prototype chain.
+
+### Receiving forwarded Host events on the Client
+
+The Host assembly extends `TypertRemoteEventSelection` with the Cordis events it forwards to consumers, which narrows the `ctx.remote.$on` key set. `TypertForwardableEvent` accepts unscoped `void` notifications and scoped async waterfalls whose final `next()` callback returns the event's result type. `TypertClientEventListener` derives the Client listener from that same `Events` member while preserving signals, optional and readonly fields, arrays, callbacks, and result types. `TypertClientRemote` exposes only `$mount()` and `$on()`; event transport remains private to Gateway.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the declarations stay compiler-independent and where each contract is enforced; the programming model is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The package keeps strict reflection in the compiler: decorator initializers retain minimal markers in a versioned descriptor on the Service prototype. The descriptor uses a stable string property name, so another installed copy of the protocol package can read the same markers. Full parameter, result, lookup, and schema reflection is the Typert build pipeline's job, delivered through `InvocationDescriptor`.
+
+### 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.
+
+### 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, cancellation, and result codecs.
+
+### Wire identity grammar
+
+Every namespace, method, lookup, and Context segment must satisfy `isTypertRemoteSegment()`, so generated names cross the shared RPC carrier unchanged. Strict codecs carry generated schemas; `src-json` codecs identify the weaker source-launch path.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Decorators, Gateway bindings, `remoteMethods`, segment validation |
+| [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` and the structural `remoteErrorOf` recognizer |
+| [`src/types.ts`](src/types.ts) | Protocol maps, `RemoteErrorDetailsMap`, `RemoteResult`, `InvocationDescriptor`, codecs, provider contracts, registry interfaces, `TypertClientRemote` |
+| — | No runtime invariant companion is published; decorators retain private immutable declarations and bindings are frozen values with no independent event stream to cross-check. |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough; they move from the declarations to the runtime and the call path.
+
+- [API Gateway reference](../../../docs/api-gateway.md) — how the declarations become running Host-to-Client calls.
+- [Typert subsystem reference](../../../docs/subsystems/typert.md) — the literal public contracts recorded from protocol and Gateway types.
+- [Typert registry](../registry/README.md) — where descriptors and providers are stored at runtime.
+- [Typert generator](../generator/README.md) — what generates the consumer-side declarations and descriptors.
+- [Remote-call Agent Note](../../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.md) — the architecture and transport decisions behind Remote calls.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as compiler-independent Remote protocol declarations register nothing model-facing.
+
+#### KV Cache effect
+
+No direct effect; the declared contracts reach a request only when an assembly places them in one.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+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.
+- **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>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,149 @@
+---
+description: "共享的 Typert Remote 协议：业务包、生成产物、Host Gateway 与 Client API 使用的装饰器、wire 描述符、编解码器与提供方约定。"
+kind: "package-library"
+---
+
+# @x1a0f3n9/dsh-typert-protocol
+
+[English](README.md) | 中文
+
+## 概述
+
+借助 `dsh-typert-protocol`，业务包可以向 Remote 客户端暴露 Host 方法：用 `@Remote`（作用域接收者用 `@RemoteScope`）标记方法，把服务绑定到 wire 命名空间，并通过可合并扩展的协议映射把 Host 对象与作用域 Context 关联到 wire identity。生成产物、Host Gateway 与 Client API 消费同一套调用描述符、编解码器与提供方约定，因此一套声明在每个 face 上保持一致。本包不注册任何 Cordis 服务，也不运行 TypeScript 分析；它只声明类型与装饰器标记。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+本包供向 Remote 客户端暴露 Host 能力的业务包与装配维护者使用。它是一个声明库：标记方法、绑定服务，其余交给生成的流水线与 Gateway。
+
+### 暴露 Host 方法
+
+业务包用 `@Remote`（当接收者来自作用域 Context 时用 `@RemoteScope(key)`）标记一个公开实例方法，所属服务要么继承 `TypertRemoteService`，要么通过 `bindTypertRemote()` 声明 `typertRemote` 绑定：
+
+```text
+import { Remote, TypertRemoteService } from '@x1a0f3n9/dsh-typert-protocol'
+
+export class GoalService extends TypertRemoteService {
+  @Remote
+  async create(agentId: string, objective: string): Promise<GoalResult> {
+    ...
+  }
+}
+```
+
+生成会把方法变为服务命名空间下的 wire 端点；Client 通过 `ctx.remote` 以类型化方法调用它（见 [API Gateway 参考](../../../docs/api-gateway.zh.md)）。方法把 `signal: AbortSignal` 声明为最后一个参数即可选择协作式取消——该信号是注入的，绝不会成为 JSON 参数或查找字段。
+
+### 把 Host 对象与 Context 关联到 wire identity
+
+复杂的 Host 对象不能直接跨 wire 传输。业务包通过可合并扩展的 `TypertLookupMap` 与 `TypertContextMap` 声明关联。Host 与 Client Context adapter 都把 `Context` 映射为 wire identity，也把该 identity 映射回 `Context`；Host adapter 还拥有稳定 wire 声明。Host 组合可以覆盖其同步或异步 resolver。因策略而拒绝的 resolver 抛出带自有码的 `RemoteError`，该码原样到达调用方。
+
+### 报告与读取 Remote 失败
+
+所有 Remote 失败都由一个类承载：`RemoteError`，携带稳定的 `<domain>/<reason>` 码，以及按该码定型的 details。本包声明通用载体码（`gateway/bad-request`、`gateway/cancelled`、`gateway/internal`），并拥有 `RemoteErrorDetailsMap`——可合并扩展的码表，其他每个包都在自己的抛出点旁扩展它：
+
+```text
+declare module '@x1a0f3n9/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    'goal/not-found': { readonly goalId: string }
+  }
+}
+throw new RemoteError('goal/not-found', `goal "${id}" does not exist`, { goalId: id })
+```
+
+拥有方在失败点直接抛出；没有任何包再写错误类家族或出口映射函数。调用方按 `code` 判别——绝不用 `instanceof`——且 `code` 分支无需 cast 即收窄 `details`，因为 `RemoteFailure` 就是 `RemoteError` 实例按码判别的 union。需要识别跨模块或跨 realm 类副本传来的失败时，基础设施调用 `remoteErrorOf(value)`，它读结构标记而不是原型链。
+
+### 在 Client 侧接收转发的 Host 事件
+
+Host 装配以转发给消费端的 Cordis 事件扩展 `TypertRemoteEventSelection`，从而收窄 `ctx.remote.$on` 的键集。`TypertForwardableEvent` 接受无作用域且返回 `void` 的通知，以及最后一个 `next()` 回调返回事件结果类型的异步作用域 waterfall。`TypertClientEventListener` 从同一条 `Events` 成员派生 Client listener，并保留 signal、可选和只读字段、数组、回调与结果类型。`TypertClientRemote` 只公开 `$mount()` 与 `$on()`；事件传输仍由 Gateway 私有持有。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释声明如何保持与编译器无关，以及每个约定在哪里执行；编程模型已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+本包把严格反射留在编译器中：装饰器初始化器把最小标记保存在 Service 原型上的带版本描述符中。描述符使用稳定的字符串属性名，因此协议包的另一个已安装副本也能读取同一组标记。完整的参数、结果、查找与 schema 反射是 Typert 构建流水线的职责，通过 `InvocationDescriptor` 交付。
+
+### Remote 标记
+
+`@Remote` 与 `@RemoteScope` 调度一个初始化器，把方法名、可选导出名与调用模式追加到原型描述符；`remoteMethods(service)` 校验其版本，并返回与已存描述符分离、按声明顺序排列的快照，供 Gateway 的源码模式回退读取。标记要求公开、非静态、具名字符串的实例方法，同一方法上的冲突标记会被拒绝。
+
+### 协议映射与描述符
+
+可合并扩展的协议映射在类型系统中保留静态关联，运行时提供方则向 `ctx.typert` 注册解析；映射的名称与形状见 [`src/types.ts`](src/types.ts)。`InvocationDescriptor` 是注册表、Gateway 与 Client Remote 共同消费的共享运行时形式，涵盖直接与 Context 接收者、JSON 与查找参数、作用域投影、取消与结果编解码器。
+
+### Wire 标识文法
+
+每个命名空间、方法、查找与 Context 段都必须满足 `isTypertRemoteSegment()`，生成的名字才能原样跨共享 RPC 载体传输。严格编解码器携带生成的 schema；`src-json` 编解码器标识约束更弱的源码启动路径。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 装饰器、Gateway 绑定、`remoteMethods`、段校验 |
+| [`src/remote-error.ts`](src/remote-error.ts) | `RemoteError` 与结构式识别函数 `remoteErrorOf` |
+| [`src/types.ts`](src/types.ts) | 协议映射、`RemoteErrorDetailsMap`、`RemoteResult`、`InvocationDescriptor`、编解码器、提供方约定、注册表接口、`TypertClientRemote` |
+| — | 不发布运行时不变量伴生入口；decorator 只保留私有不可变声明，binding 也是冻结值，没有可供交叉核对的独立事件流。 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面；它们从声明逐步进入运行时与调用路径。
+
+- [API Gateway 参考](../../../docs/api-gateway.zh.md)——声明如何成为实际的 Host 到 Client 调用。
+- [Typert 子系统参考](../../../docs/subsystems/typert.zh.md)——从协议与 Gateway 类型记录的字面公共约定。
+- [Typert 注册表](../registry/README.zh.md)——描述符与提供方在运行时存放的位置。
+- [Typert 生成器](../generator/README.zh.md)——生成消费方声明与描述符的包。
+- [Remote 调用 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-02-typert-remote-method-calls.zh.md)——Remote 调用背后的架构与传输决策。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为与编译器无关的 Remote 协议声明不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无直接影响；声明的约定只有在装配将其放入请求时才会触及请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明声明能表示什么；它们是当前包约束，不是任务积压。
+
+- **装饰器标记是最小化的**——标记只包含方法名与直接调用或 Context 调用模式；参数、结果、查找与 schema 反射需要 Typert 构建流水线。
+- **Remote 签名受限**——装饰器只接受具有字符串名称的公开、非静态实例方法，源码模式执行无法表示重载、解构、默认参数或剩余参数签名。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,184 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/remote-error.js
+/** The one Remote failure class shared by owners, the Gateway, and consumers. */
+/**
+* One Remote call failure: a real Error carrying its stable code and typed
+* details. Owners throw it at the failure point; the Host Gateway encodes it
+* onto the wire unchanged; the Client face rebuilds an instance for the
+* `RemoteResult` error branch, so `throw result.error` keeps throw semantics.
+* Discrimination is always by `code`, never by instanceof.
+*/
+var RemoteError = class extends Error {
+	code;
+	details;
+	/** Structural marker: cross-realm/bundle identification never uses instanceof. */
+	isDSHRemoteError = true;
+	/**
+	* @param code - stable failure code declared in {@link RemoteErrorDetailsMap}.
+	* @param message - human diagnostic carried across the wire.
+	* @param details - structured payload typed by the code.
+	* @param options - standard Error options (`cause` survives in-process only).
+	*/
+	constructor(code, message, details, options) {
+		super(message, options);
+		this.code = code;
+		this.details = details;
+		this.name = "RemoteError";
+	}
+};
+/**
+* Structurally identify a RemoteError thrown across module or realm copies of
+* this class. Mechanism-internal: the Gateway and test assertions use it;
+* business code receives typed failures and never needs it.
+* @param value - a caught value.
+* @returns the failure when the marker matches, otherwise undefined.
+*/
+function remoteErrorOf(value) {
+	if (typeof value === "object" && value !== null && value.isDSHRemoteError === true && typeof value.code === "string") return value;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Remote decorators and explicit Gateway bindings backed by versioned
+* descriptors carried on decorated class prototypes. Strict reflection
+* remains a Typert compiler responsibility.
+* @module @x1a0f3n9/dsh-typert-protocol
+*/
+const TYPERT_REMOTE_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
+/**
+* Test one generated Remote name against the Connection endpoint grammar.
+* @param value - namespace, method, lookup, or Context segment.
+* @returns whether the value can cross the shared RPC carrier unchanged.
+*/
+function isTypertRemoteSegment(value) {
+	return value !== "." && value !== ".." && TYPERT_REMOTE_SEGMENT_PATTERN.test(value);
+}
+const REMOTE_METHOD_DESCRIPTOR = "@x1a0f3n9/dsh-typert-protocol/remote-methods";
+/**
+* Bind one visible Service field to a Cordis key and Remote namespace.
+* @param service - owning Service instance, normally `this`.
+* @param serviceKey - exact Cordis service key.
+* @param options - optional distinct wire namespace.
+* @returns a frozen, inspectable binding with no compiler-injected metadata.
+*/
+function bindTypertRemote(service, serviceKey, options = {}) {
+	validateName("service key", serviceKey);
+	const namespace = options.namespace ?? serviceKey;
+	validateName("namespace", namespace);
+	return Object.freeze({
+		service,
+		serviceKey,
+		namespace
+	});
+}
+/** Cordis Service base that exposes its registered name through Typert Gateway. */
+var TypertRemoteService = class extends Service {
+	/** Visible binding consumed by the Gateway's source-mode discovery. */
+	typertRemote;
+	/**
+	* 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.
+	*/
+	constructor(ctx, serviceKey, options = {}) {
+		super(ctx, serviceKey);
+		this.typertRemote = bindTypertRemote(this, this.name, options);
+	}
+};
+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");
+	}
+	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");
+}
+function remoteDecorator(invocation, mode, exportName) {
+	return function(_method, context) {
+		addMarkerInitializer(context, invocation, mode, exportName);
+	};
+}
+/**
+* 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) {
+	validateName("Scope key", key);
+	if (exportName !== void 0) validateName("Remote export name", exportName);
+	return remoteDecorator({
+		kind: "context",
+		context: key
+	}, void 0, exportName);
+}
+/**
+* Read Remote markers attached to a live Service's class prototype.
+* The returned snapshot cannot mutate the stored descriptor.
+* @param service - live Service instance.
+* @returns markers in class declaration order.
+*/
+function remoteMethods(service) {
+	const prototype = Object.getPrototypeOf(service);
+	if (prototype === null) return [];
+	return (readRemoteMethodDescriptor(prototype)?.methods ?? []).map((marker) => ({ ...marker }));
+}
+function readRemoteMethodDescriptor(prototype) {
+	const property = Object.getOwnPropertyDescriptor(prototype, REMOTE_METHOD_DESCRIPTOR);
+	if (property === void 0) return void 0;
+	const descriptor = property.value;
+	if (descriptor === null || typeof descriptor !== "object") throw new TypeError("typert-protocol: Remote method descriptor must be an object");
+	const version = Reflect.get(descriptor, "version");
+	if (version !== 1) throw new TypeError(`typert-protocol: unsupported Remote method descriptor version ${String(version)}`);
+	const methods = Reflect.get(descriptor, "methods");
+	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) {
+	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);
+	});
+}
+function mark(prototype, method, invocation, mode, exportName) {
+	const descriptor = readRemoteMethodDescriptor(prototype);
+	const marker = Object.freeze({
+		method,
+		...exportName === void 0 || exportName === method ? {} : { exportName },
+		...mode === void 0 ? {} : { mode },
+		invocation: Object.freeze(invocation)
+	});
+	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;
+		throw new Error(`typert-protocol: Remote method "${method}" has conflicting invocation markers`);
+	}
+	Object.defineProperty(prototype, REMOTE_METHOD_DESCRIPTOR, {
+		configurable: true,
+		value: Object.freeze({
+			version: 1,
+			methods: Object.freeze([...descriptor?.methods ?? [], marker])
+		})
+	});
+}
+function sameInvocation(left, right) {
+	if (left.kind === "direct") return right.kind === "direct";
+	if (right.kind === "direct") return false;
+	return left.context === right.context;
+}
+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, TypertRemoteService, bindTypertRemote, isTypertRemoteSegment, remoteErrorOf, remoteMethods };

package/lib/types/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Remote decorators and explicit Gateway bindings backed by versioned
+ * descriptors carried on decorated class prototypes. Strict reflection
+ * remains a Typert compiler responsibility.
+ * @module @x1a0f3n9/dsh-typert-protocol
+ */
+import { Service, type Context } from '@deepseek-ai/cordis';
+import type { TypertContextMap } from './types.ts';
+export { RemoteError, remoteErrorOf } from './remote-error.ts';
+/**
+ * Test one generated Remote name against the Connection endpoint grammar.
+ * @param value - namespace, method, lookup, or Context segment.
+ * @returns whether the value can cross the shared RPC carrier unchanged.
+ */
+export declare function isTypertRemoteSegment(value: string): boolean;
+export type { InvocationDescriptor, InvocationParameterDescriptor, InvocationSourceLocation, RemoteErrorCode, RemoteErrorDetailsMap, RemoteFailure, RemoteResult, TypertClientEventListener, TypertClientRemote, TypertClientContextAdapter, TypertCodec, TypertContext, TypertContextAdapter, TypertContextMap, TypertContextRegistry, TypertContextWire, TypertDisposer, TypertForwardableEvent, TypertForwardableEventEntry, TypertHostContextAdapter, TypertHostContextIdentity, TypertHostContextResolver, TypertLocalRegistry, TypertLookup, TypertLookupDefinition, TypertLookupHost, TypertLookupMap, TypertLookupProvider, TypertLookupResolver, TypertLookupRegistry, TypertLookupWire, TypertRemoteScopeApi, TypertRemoteScopeMap, TypertRemoteScopeNamespace, TypertRemoteContribution, TypertRemoteEvent, TypertRemoteEventSelection, TypertRemoteMap, TypertRemoteNamespace, TypertRemoteNamespaceMap, TypertRemoteRegistry, TypertRegistryChange, TypertRegistryListener, TypertSchema, TypertRegistryContract, } from './types.ts';
+/** Options for an explicit Service-to-Gateway binding. */
+export interface TypertGatewayBindingOptions {
+    /** Wire namespace; defaults to the Cordis service key. */
+    readonly namespace?: string;
+}
+/** Visible declaration that one Service participates in Typert Gateway export. */
+export interface TypertGatewayBinding<Service extends object = object> {
+    readonly service: Service;
+    readonly serviceKey: string;
+    readonly namespace: string;
+}
+/** Invocation mode recorded by a Remote method decorator. */
+export type RemoteInvocationMarker = {
+    readonly kind: 'direct';
+} | {
+    readonly kind: 'context';
+    readonly context: string;
+};
+/** One decorator marker discovered for a live Service instance. */
+export interface RemoteMethodMarker {
+    /** Public instance method carrying the implementation. */
+    readonly method: string;
+    /** Endpoint method when it differs from the implementation member. */
+    readonly exportName?: string;
+    /** Stream methods yield many independently validated result items. */
+    readonly mode?: 'stream';
+    readonly invocation: RemoteInvocationMarker;
+}
+/** Options for a non-unary Remote method. */
+export interface RemoteMethodOptions {
+    /** Deliver each Iterable item over the shared logical-stream carrier. */
+    readonly mode: 'stream';
+}
+type RemoteMethodDecorator = <This extends object, Args extends unknown[], Result>(method: (this: This, ...args: Args) => Result, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>) => void;
+/**
+ * Bind one visible Service field to a Cordis key and Remote namespace.
+ * @param service - owning Service instance, normally `this`.
+ * @param serviceKey - exact Cordis service key.
+ * @param options - optional distinct wire namespace.
+ * @returns a frozen, inspectable binding with no compiler-injected metadata.
+ */
+export declare function bindTypertRemote<Service extends object>(service: Service, serviceKey: string, options?: TypertGatewayBindingOptions): TypertGatewayBinding<Service>;
+/** Cordis Service base that exposes its registered name through Typert Gateway. */
+export declare abstract class TypertRemoteService<out T = never> extends Service<T> {
+    /** Visible binding consumed by the Gateway's source-mode discovery. */
+    readonly typertRemote: TypertGatewayBinding<this>;
+    /**
+     * 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.
+     */
+    protected constructor(ctx: Context, serviceKey: string, options?: TypertGatewayBindingOptions);
+}
+/**
+ * Mark one public instance method as a direct Remote invocation.
+ * @param _method - decorated method; retained only by the class itself.
+ * @param context - standard decorator context used to schedule private marking.
+ */
+export declare function Remote<This extends object, Args extends unknown[], Result>(_method: (this: This, ...args: Args) => Result, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Result>): void;
+/**
+ * Mark one public instance method under an exported name or as a logical stream.
+ * @param option - endpoint method name or stream delivery mode.
+ * @returns a standard method decorator.
+ */
+export declare function Remote(option: string | RemoteMethodOptions): RemoteMethodDecorator;
+/**
+ * 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.
+ */
+export declare function RemoteScope(key: Extract<keyof TypertContextMap, string>, exportName?: string): RemoteMethodDecorator;
+/**
+ * Read Remote markers attached to a live Service's class prototype.
+ * The returned snapshot cannot mutate the stored descriptor.
+ * @param service - live Service instance.
+ * @returns markers in class declaration order.
+ */
+export declare function remoteMethods(service: object): readonly RemoteMethodMarker[];
+//# sourceMappingURL=index.d.ts.map