feat: add TypeRT remote gateway infrastructure

packages/host/api-gateway/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/host/api-gateway/README.md
+README.md: 3ef926ace2ee4d6008b1d6c18b1e070fa39bc176
+README.zh.md: 77b8b8a87d5f511000aac5cf9f75ebca5fcdfbca

packages/host/api-gateway/README.md

@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-host-api-gateway
+
+English | [中文](README.zh.md)
+
+Two-sided Remote control for Host and Client Cordis environments. The Host entry provides `ctx.typertGateway`, while `@deepseek-ai/dsh-host-api-gateway/client` provides `ctx.api`; both consume the same generated `InvocationDescriptor` contract and leave transport, request correlation, trust, and response envelopes to Connection.
+
+## Host service: `TypertGatewayService` (ctx key: `typertGateway`)
+
+`ctx.typertGateway.invoke()` resolves the current descriptor and Cordis Service for each call, validates exact named arguments, resolves registered object or Context identities, invokes the public business method, and validates its result. Business Services declare participation with `bindTypeRTGateway()` and `@Remote` or `@RemoteContext` from [`dsh-type-meta`](../../typert/type-meta/README.md).
+
+Strict mode reads generated invocation descriptors from `ctx.typert.local`. Lookup parameters use registered `ctx.typert.lookups` providers, while `@RemoteContext` resolves its receiver through a registered Host Context provider. SRC mode is a development fallback for endpoints that have never had a strict definition; it parses simple parameter names and accepts only JSON-safe values for non-lookup parameters. Withdrawing an observed strict definition fails instead of weakening validation.
+
+The Host entry registers the trusted-host `/api2` unary RPC channel when Connection is available. Direct `invoke()` calls preserve business errors; `TypertGatewayError` distinguishes failures owned by dispatch, binding, providers, lookup, Context, arguments, and codecs.
+
+## Client service: `ClientApi` (ctx key: `api`)
+
+`ctx.api.mount()` validates and registers a generated Host-for-Client contribution, then installs concrete direct and scoped methods for the calling Cordis fiber. Duplicate endpoints, namespace collisions, and descriptors without strict generated codecs fail before methods become callable.
+
+Each call validates positional inputs, constructs the descriptor's exact named `args`, and sends it through `ctx.connection.rpc.call('/api2', endpoint, ...)`. The returned value is validated before reaching application code. Withdrawing a contribution removes its descriptors and methods together, aborts in-flight calls, and makes retained method handles reject.
+
+Generated declaration merges provide the TypeScript API. The Client entry contains no Host Service or Host Cordis interface merge, and method lookup and invocation use ordinary objects and functions rather than a JavaScript Proxy.
+
+## Model Experience
+
+None, as the package dispatches application calls and registers no prompt, tool, or session event.
+
+#### KV Cache effect
+
+No direct effect; invoked business Services own any model-visible result.
+
+## Known Limitations and Deferred Work
+
+- The Connection adapter currently maps dispatch and business failures to the RPC `internal` code with empty details. Structured `TypertGatewayError` categories remain available only to same-process callers.
+- SRC mode supports unique identifier parameters without destructuring, defaults, or rest parameters. It validates JSON safety rather than generated business types and never infers optional fields.
+- Only strict generated contributions can mount on the Client face. SRC markers have no Client codec or type projection.
+- The package dispatches unary methods only. Incremental Session data uses a separate named-stream protocol over the same Connection.

packages/host/api-gateway/README.zh.md

@@ -0,0 +1,36 @@
+# @deepseek-ai/dsh-host-api-gateway
+
+[English](README.md) | 中文
+
+为 Host 与 Client 两侧的 Cordis 环境提供 Remote 控制。Host 入口提供 `ctx.typertGateway`，`@deepseek-ai/dsh-host-api-gateway/client` 则提供 `ctx.api`；两者使用同一份生成的 `InvocationDescriptor` 契约，并将传输、请求关联、信任和响应封装交由 Connection 处理。
+
+## Host 服务：`TypertGatewayService`（ctx key：`typertGateway`）
+
+每次调用时，`ctx.typertGateway.invoke()` 都会解析当前的描述符和 Cordis 服务，校验具名参数是否完全匹配，解析已注册的对象或 Context 身份标识，调用公开的业务方法，并校验其结果。业务服务调用 `bindTypeRTGateway()` 并使用 [`dsh-type-meta`](../../typert/type-meta/README.md) 提供的 `@Remote` 或 `@RemoteContext` 装饰器，以显式声明接入。
+
+严格模式从 `ctx.typert.local` 读取生成的调用描述符。查找参数使用已向 `ctx.typert.lookups` 注册的提供方，`@RemoteContext` 则通过已注册的 Host Context 提供方解析其接收者。SRC 模式是开发阶段的回退路径，适用于从未具备严格定义的端点；它解析简单参数名，并且只允许非查找参数使用可安全表示为 JSON 的值。已观测到的严格定义一旦撤回，系统会直接报错，而不会降低校验强度。
+
+Connection 可用时，Host 入口会注册 trusted-host 的 `/api2` 一元 RPC 通道。直接调用 `invoke()` 会保留业务错误；`TypertGatewayError` 可区分分发、绑定、提供方、查找、Context、参数和编解码器各自负责的故障。
+
+## Client 服务：`ClientApi`（ctx key：`api`）
+
+`ctx.api.mount()` 会校验并注册生成的 Host-for-Client 贡献项，然后为发起调用的 Cordis fiber 安装具体的直接方法和作用域方法。重复端点、命名空间冲突，以及缺少生成的严格编解码器的描述符，都会在方法可调用前报错。
+
+每次调用都会校验位置参数，构造与描述符完全匹配的具名 `args`，再通过 `ctx.connection.rpc.call('/api2', endpoint, ...)` 发送。返回值经过校验后才会交给应用代码。撤回贡献项会同时移除其描述符和方法、中止正在进行的调用，并使外部仍持有的方法句柄在调用时返回拒绝。
+
+生成的声明合并提供 TypeScript API。Client 入口不包含 Host 服务或 Host Cordis 接口合并；方法查找和调用使用普通对象与函数，而不使用 JavaScript Proxy。
+
+## 模型体验
+
+无，因为该包分发应用调用，不注册任何提示词、工具或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；被调用的业务服务负责产生任何模型可见结果。
+
+## 已知限制与延期工作
+
+- Connection 适配器目前将分发故障和业务故障映射为 RPC 的 `internal` 代码，且不附带详细信息。结构化的 `TypertGatewayError` 类别仅供同进程调用方使用。
+- SRC 模式仅支持名称唯一的标识符参数，不支持解构、默认值或剩余参数。它只校验值能否安全表示为 JSON，不校验生成的业务类型，也绝不会推断可选字段。
+- Client 侧只能挂载严格模式生成的贡献项。SRC 标记不具备 Client 编解码器或类型投影。
+- 该包只分发一元方法。增量会话数据通过同一个 Connection 上独立的具名流协议传输。

packages/host/api-gateway/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@deepseek-ai/dsh-host-api-gateway",
+  "description": "Host dispatcher and Client API for TypeRT Remote invocations",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dshClient": {
+    "inject": [
+      "@deepseek-ai/dsh-typert-registry",
+      "@deepseek-ai/dsh-client-connection"
+    ],
+    "platform": "web",
+    "immediately": true
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@deepseek-ai/dsh-type-meta": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-connection": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "zod": "^4.4.3"
+  }
+}

packages/host/api-gateway/src/client/index.ts

@@ -0,0 +1,370 @@
+/**
+ * Client projection of generated TypeRT Remote descriptors. Contributions
+ * install concrete namespace methods; no JavaScript Proxy participates in
+ * lookup, invocation, or type exposure.
+ */
+
+import { Service } from 'cordis'
+import type { Context } from 'cordis'
+import type { ConnectionHandle, RpcError } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTCodec,
+  TypeRTDisposer,
+  TypeRTRemoteContribution,
+  TypeRTRemoteNamespaceMap,
+} from '@deepseek-ai/dsh-type-meta'
+
+type RemoteMethod = (...args: unknown[]) => Promise<unknown>
+
+interface MountToken {
+  active: boolean
+  readonly abort: AbortController
+}
+
+interface DirectNamespaceRecord {
+  readonly value: Record<string, RemoteMethod>
+  readonly tokens: Map<string, MountToken>
+}
+
+interface ScopedNamespaceRecord {
+  readonly service: ScopedRemoteNamespace
+  readonly tokens: Map<string, MountToken>
+}
+
+interface ScopedProjection {
+  readonly context: string
+  readonly wire: string
+  readonly codec: TypeRTCodec
+  readonly parameterIndex?: number
+}
+
+/** Typed API service augmented by generated direct Remote namespaces. */
+export interface ClientApi extends TypeRTRemoteNamespaceMap {
+  /**
+   * Mount one generated Host-for-Client contribution in the caller's fiber.
+   * @param contribution - explicitly selected Remote package artifact.
+   * @returns disposer withdrawing descriptors and concrete methods together.
+   */
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Generated direct Remote namespaces selected by the Client assembly. */
+    api: ClientApi
+  }
+}
+
+/** Required Client services: the TypeRT registry and the existing Connection carrier. */
+export const inject = ['typert', 'connection']
+
+/**
+ * Install the typed Client API service.
+ * @param ctx - Client Cordis root.
+ */
+export function apply(ctx: Context): void {
+  new ClientApiService(ctx)
+}
+
+class ClientApiService extends Service implements ClientApi {
+  private readonly ownerCtx: Context
+  private readonly direct = new Map<string, DirectNamespaceRecord>()
+  private readonly scoped = new Map<string, ScopedNamespaceRecord>()
+
+  constructor(ctx: Context) {
+    super(ctx, 'api')
+    this.ownerCtx = ctx
+  }
+
+  mount(contribution: TypeRTRemoteContribution): TypeRTDisposer {
+    this.validateContribution(contribution)
+    const callerCtx = this.ctx
+    const disposeRemote = callerCtx.typert.remotes.register(contribution)
+    let disposeMethods: () => void | Promise<void>
+    try {
+      disposeMethods = callerCtx.effect(() => {
+        const installed = contribution.descriptors.map(descriptor => this.install(descriptor))
+        return () => {
+          for (const dispose of installed.reverse()) dispose()
+        }
+      }, `api-gateway.client.mount(${JSON.stringify(contribution.package)})`)
+    } catch (error) {
+      disposeRemote().catch(() => {})
+      throw error
+    }
+    return async () => {
+      await Promise.all([disposeMethods(), disposeRemote()])
+    }
+  }
+
+  private validateContribution(contribution: TypeRTRemoteContribution): void {
+    const direct = new Map<string, Set<string>>()
+    const scoped = new Map<string, Set<string>>()
+    const add = (
+      table: Map<string, Set<string>>,
+      descriptor: InvocationDescriptor,
+      kind: 'direct' | 'scoped',
+    ): void => {
+      const methods = table.get(descriptor.namespace) ?? new Set<string>()
+      if (methods.has(descriptor.method)) {
+        throw new Error(`client api: contribution repeats ${kind} method ${endpointOf(descriptor)}`)
+      }
+      methods.add(descriptor.method)
+      table.set(descriptor.namespace, methods)
+      const live = kind === 'direct'
+        ? this.direct.get(descriptor.namespace)?.tokens
+        : this.scoped.get(descriptor.namespace)?.tokens
+      if (live?.has(descriptor.method) === true) {
+        throw new Error(`client api: ${kind} method ${endpointOf(descriptor)} is already mounted`)
+      }
+    }
+    for (const descriptor of contribution.descriptors) {
+      requireStrictDescriptor(descriptor)
+      if (descriptor.invocation.kind === 'direct') add(direct, descriptor, 'direct')
+      if (scopedProjection(descriptor) !== undefined) add(scoped, descriptor, 'scoped')
+    }
+    for (const namespace of direct.keys()) {
+      if (!this.direct.has(namespace) && namespace in this) {
+        throw new Error(`client api: namespace ${JSON.stringify(namespace)} conflicts with the API service`)
+      }
+    }
+    for (const [namespace, methods] of scoped) {
+      const record = this.scoped.get(namespace)
+      if (record !== undefined) {
+        for (const method of methods) record.service.assertMethodAvailable(method)
+      } else if (this.ownerCtx.reflect.props[namespace] !== undefined) {
+        throw new Error(`client api: scoped namespace ${JSON.stringify(namespace)} conflicts with an existing Context property`)
+      }
+    }
+  }
+
+  private install(descriptor: InvocationDescriptor): () => void {
+    const token: MountToken = { active: true, abort: new AbortController() }
+    const installed: (() => void)[] = []
+    if (descriptor.invocation.kind === 'direct') {
+      installed.push(this.installDirect(descriptor, token))
+    }
+    const projection = scopedProjection(descriptor)
+    if (projection !== undefined) installed.push(this.installScoped(descriptor, projection, token))
+    return () => {
+      if (!token.active) return
+      token.active = false
+      for (const dispose of installed.reverse()) dispose()
+      token.abort.abort()
+    }
+  }
+
+  private installDirect(descriptor: InvocationDescriptor, token: MountToken): () => void {
+    let namespace = this.direct.get(descriptor.namespace)
+    if (namespace === undefined) {
+      namespace = { value: Object.create(null) as Record<string, RemoteMethod>, tokens: new Map() }
+      this.direct.set(descriptor.namespace, namespace)
+      Object.defineProperty(this, descriptor.namespace, {
+        configurable: true,
+        enumerable: true,
+        value: namespace.value,
+      })
+    }
+    namespace.tokens.set(descriptor.method, token)
+    Object.defineProperty(namespace.value, descriptor.method, {
+      configurable: true,
+      enumerable: true,
+      value: (...args: unknown[]) => this.invoke(descriptor, undefined, token, this.ownerCtx, args),
+    })
+    return () => {
+      if (namespace.tokens.get(descriptor.method) !== token) return
+      Reflect.deleteProperty(namespace.value, descriptor.method)
+      namespace.tokens.delete(descriptor.method)
+      if (namespace.tokens.size !== 0) return
+      this.direct.delete(descriptor.namespace)
+      Reflect.deleteProperty(this, descriptor.namespace)
+    }
+  }
+
+  private installScoped(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection,
+    token: MountToken,
+  ): () => void {
+    let namespace = this.scoped.get(descriptor.namespace)
+    if (namespace === undefined) {
+      namespace = {
+        service: new ScopedRemoteNamespace(
+          this.ownerCtx,
+          descriptor.namespace,
+          (current, currentProjection, currentToken, caller, args) =>
+            this.invoke(current, currentProjection, currentToken, caller, args),
+        ),
+        tokens: new Map(),
+      }
+      this.scoped.set(descriptor.namespace, namespace)
+    }
+    namespace.tokens.set(descriptor.method, token)
+    namespace.service.install(descriptor, projection, token)
+    return () => {
+      if (namespace.tokens.get(descriptor.method) !== token) return
+      namespace.service.remove(descriptor.method)
+      namespace.tokens.delete(descriptor.method)
+    }
+  }
+
+  private async invoke(
+    descriptor: InvocationDescriptor,
+    projection: ScopedProjection | undefined,
+    token: MountToken,
+    callerCtx: Context,
+    values: readonly unknown[],
+  ): Promise<unknown> {
+    const endpoint = endpointOf(descriptor)
+    if (!token.active) throw new Error(`client api: Remote method ${endpoint} is no longer mounted`)
+    const expected = descriptor.parameters.length - (projection?.parameterIndex === undefined ? 0 : 1)
+    if (values.length !== expected) {
+      throw new Error(
+        `client api: ${endpoint} expected ${String(expected)} argument(s), got ${String(values.length)}`,
+      )
+    }
+    const args: Record<string, unknown> = {}
+    if (projection !== undefined) {
+      const binder = this.ownerCtx.typert.contexts.getClient(projection.context)
+      if (binder === undefined) {
+        throw new Error(`client api: ${endpoint} has no Client Context binder for ${JSON.stringify(projection.context)}`)
+      }
+      const identity = binder.identity(callerCtx)
+      if (identity === undefined) {
+        throw new Error(`client api: ${endpoint} requires a ${JSON.stringify(projection.context)} Context`)
+      }
+      args[projection.wire] = parse(projection.codec, identity, endpoint, projection.wire)
+    }
+    let valueIndex = 0
+    descriptor.parameters.forEach((parameter, parameterIndex) => {
+      if (parameterIndex === projection?.parameterIndex) return
+      args[parameter.wire] = parse(parameter.codec, values[valueIndex], endpoint, parameter.wire)
+      valueIndex += 1
+    })
+    const connection = this.ownerCtx.get('connection') as ConnectionHandle | undefined
+    if (connection === undefined) throw new Error(`client api: ${endpoint} has no active Connection`)
+    const result = await connection.rpc.call('/api2', endpoint, { args }, token.abort.signal)
+    if (!mountActive(token)) throw new Error(`client api: Remote method ${endpoint} was withdrawn during invocation`)
+    if (!result.ok) throw remoteFailure(endpoint, result.error)
+    return parse(descriptor.result, result.value, endpoint, 'result')
+  }
+}
+
+type InvokeRemote = (
+  descriptor: InvocationDescriptor,
+  projection: ScopedProjection,
+  token: MountToken,
+  callerCtx: Context,
+  args: readonly unknown[],
+) => Promise<unknown>
+
+class ScopedRemoteNamespace extends Service {
+  private readonly ownerCtx: Context
+  private readonly methods = new Set<string>()
+
+  constructor(
+    ctx: Context,
+    name: string,
+    private readonly invokeRemote: InvokeRemote,
+  ) {
+    super(ctx, name)
+    this.ownerCtx = ctx
+  }
+
+  assertMethodAvailable(method: string): void {
+    if (method in this) {
+      throw new Error(`client api: scoped method ${JSON.stringify(`${this.name}/${method}`)} conflicts with its namespace service`)
+    }
+  }
+
+  install(descriptor: InvocationDescriptor, projection: ScopedProjection, token: MountToken): void {
+    this.assertMethodAvailable(descriptor.method)
+    const method = descriptor.method
+    Object.defineProperty(this, method, {
+      configurable: true,
+      enumerable: true,
+      value: function (this: ScopedRemoteNamespace, ...args: unknown[]): Promise<unknown> {
+        return this.invokeRemote(descriptor, projection, token, this.ctx, args)
+      },
+    })
+    this.methods.add(method)
+    if (this.methods.size === 1 && this.ownerCtx.get(this.name, false) === undefined) {
+      this.ownerCtx.set(this.name, this)
+    }
+  }
+
+  remove(method: string): void {
+    Reflect.deleteProperty(this, method)
+    this.methods.delete(method)
+    if (this.methods.size === 0) this.ownerCtx.set(this.name, undefined)
+  }
+}
+
+function endpointOf(descriptor: Pick<InvocationDescriptor, 'namespace' | 'method'>): string {
+  return `${descriptor.namespace}/${descriptor.method}`
+}
+
+function mountActive(token: MountToken): boolean {
+  return token.active
+}
+
+function scopedProjection(descriptor: InvocationDescriptor): ScopedProjection | undefined {
+  if (descriptor.invocation.kind === 'context') {
+    return {
+      context: descriptor.invocation.context,
+      wire: descriptor.invocation.wire,
+      codec: descriptor.invocation.codec,
+    }
+  }
+  if (descriptor.scope === undefined) return undefined
+  const lookupParameters = descriptor.parameters
+    .map((parameter, index) => ({ parameter, index }))
+    .filter(candidate => candidate.parameter.source === 'lookup')
+  const selected = lookupParameters.length === 1 ? lookupParameters[0] : undefined
+  if (selected === undefined
+    || selected.parameter.wire !== descriptor.scope.wire
+    || selected.parameter.lookup !== descriptor.scope.context) {
+    throw new Error(
+      `client api: generated Remote ${endpointOf(descriptor)} scope must select its only lookup parameter`,
+    )
+  }
+  return {
+    context: descriptor.scope.context,
+    wire: descriptor.scope.wire,
+    codec: selected.parameter.codec,
+    parameterIndex: selected.index,
+  }
+}
+
+function requireStrictDescriptor(descriptor: InvocationDescriptor): void {
+  const endpoint = endpointOf(descriptor)
+  requireStrictCodec(descriptor.result, endpoint, 'result')
+  for (const parameter of descriptor.parameters) {
+    requireStrictCodec(parameter.codec, endpoint, parameter.wire)
+  }
+  if (descriptor.invocation.kind === 'context') {
+    requireStrictCodec(descriptor.invocation.codec, endpoint, descriptor.invocation.wire)
+  }
+}
+
+function requireStrictCodec(codec: TypeRTCodec, endpoint: string, field: string): void {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+}
+
+function parse(codec: TypeRTCodec, value: unknown, endpoint: string, field: string): unknown {
+  if (codec.mode !== 'strict') {
+    throw new Error(`client api: generated Remote ${endpoint} field ${JSON.stringify(field)} has no strict codec`)
+  }
+  try {
+    return codec.schema.parse(value)
+  } catch (cause) {
+    throw new Error(`client api: ${endpoint} rejected ${JSON.stringify(field)}`, { cause })
+  }
+}
+
+function remoteFailure(endpoint: string, error: RpcError): Error {
+  return new Error(`client api: ${endpoint} failed: ${error.code}: ${error.message}`, { cause: error })
+}

packages/host/api-gateway/src/index.ts

@@ -0,0 +1,604 @@
+/**
+ * Live TypeRT Remote dispatch over Cordis Services and registered providers.
+ * Transport, request correlation, and response envelopes belong to Connection.
+ * @module @deepseek-ai/dsh-host-api-gateway
+ */
+
+import { Context, Service, symbols } from 'cordis'
+import {
+  remoteMethods,
+  type InvocationDescriptor,
+  type InvocationParameterDescriptor,
+  type TypeRTCodec,
+  type TypeRTGatewayBinding,
+  type TypeRTLookupProvider,
+} from '@deepseek-ai/dsh-type-meta'
+import type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+export type {
+  InvokeRemoteRequest,
+  TypertGateway,
+  TypertGatewayErrorCode,
+} from './types.ts'
+
+interface GatewayErrorOptions {
+  readonly cause?: unknown
+  readonly field?: string
+}
+
+interface ResolvedBinding {
+  readonly binding: TypeRTGatewayBinding
+  readonly original: object
+}
+
+type ConnectionRpcResult =
+  | { readonly ok: true; readonly value: unknown }
+  | {
+    readonly ok: false
+    readonly error: {
+      readonly code: 'internal'
+      readonly message: string
+      readonly details: Record<never, never>
+    }
+  }
+
+interface HostConnectionLike {
+  readonly rpc: {
+    handle(
+      channel: string,
+      handler: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<ConnectionRpcResult>,
+      options: { readonly authority: 'trusted-host' | 'loopback' },
+    ): () => Promise<void>
+  }
+}
+
+/** Dispatch failure produced outside the invoked business method. */
+export class TypertGatewayError extends Error {
+  /** Machine-readable failure category. */
+  readonly code: TypertGatewayErrorCode
+  /** Canonical `<namespace>/<method>` endpoint. */
+  readonly endpoint: string
+  /** Affected wire field when the failure is field-specific. */
+  readonly field: string | undefined
+
+  /**
+   * Construct a Gateway failure without embedding boundary values in its message.
+   * @param code - stable failure category.
+   * @param endpoint - canonical Remote endpoint.
+   * @param message - correction-oriented diagnostic without sensitive values.
+   * @param options - optional field and contained cause.
+   */
+  constructor(
+    code: TypertGatewayErrorCode,
+    endpoint: string,
+    message: string,
+    options: GatewayErrorOptions = {},
+  ) {
+    super(`typert gateway: ${endpoint}: ${message}`, options.cause === undefined ? undefined : { cause: options.cause })
+    this.name = 'TypertGatewayError'
+    this.code = code
+    this.endpoint = endpoint
+    this.field = options.field
+  }
+}
+
+/**
+ * Resolve strict generated definitions or conservative SRC markers against
+ * current Cordis Services and TypeRT providers.
+ * @typert service typertGateway
+ */
+export class TypertGatewayService extends Service implements TypertGateway {
+  static inject = ['typert']
+
+  /**
+   * Register the Gateway against the active TypeRT registry.
+   * @param ctx - owning Host Context with TypeRT registry access.
+   */
+  constructor(ctx: Context) {
+    super(ctx, 'typertGateway')
+    ctx.inject(['connection'], (connectionCtx) => {
+      const connection = connectionCtx.get('connection') as unknown as HostConnectionLike
+      connection.rpc.handle(
+        '/api2',
+        (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),
+        { authority: 'trusted-host' },
+      )
+    })
+  }
+
+  /**
+   * Invoke one live Remote method through strict generated reflection or SRC markers.
+   * @param request - decoded endpoint and exact named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  async invoke(request: InvokeRemoteRequest): Promise<unknown> {
+    const endpoint = endpointOf(request.namespace, request.method)
+    const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)
+    assertExactArguments(request.args, descriptor, endpoint)
+    const receiverContext = this.resolveReceiverContext(descriptor, request.args, endpoint)
+    const receiver = receiverContext.get(descriptor.service) as unknown
+    if (!isObject(receiver)) {
+      throw new TypertGatewayError(
+        'service-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} is unavailable`,
+      )
+    }
+    validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)
+    const args = descriptor.parameters.map(parameter => this.resolveParameter(parameter, request.args, endpoint))
+    const implementation = descriptor.implementation ?? descriptor.method
+    const method = Reflect.get(receiver, implementation) as unknown
+    if (typeof method !== 'function') {
+      throw new TypertGatewayError(
+        'method-unavailable',
+        endpoint,
+        `active Service ${JSON.stringify(descriptor.service)} has no callable method ${JSON.stringify(implementation)}`,
+      )
+    }
+
+    const result = await Reflect.apply(method, receiver, args) as unknown
+    return decode(descriptor.result, result, 'result-invalid', endpoint, 'result')
+  }
+
+  private async dispatchRpc(
+    endpoint: string,
+    payload: unknown,
+    _signal: AbortSignal,
+  ): Promise<ConnectionRpcResult> {
+    return this.invokeRpc(endpoint, payload)
+  }
+
+  private async invokeRpc(endpoint: string, payload: unknown): Promise<ConnectionRpcResult> {
+    try {
+      const segments = endpoint.split('/')
+      const namespace = segments[0]
+      const method = segments[1]
+      if (segments.length !== 2 || namespace === undefined || namespace === '' || method === undefined || method === '') {
+        throw new Error(`invalid Remote endpoint ${JSON.stringify(endpoint)}`)
+      }
+      if (!isObject(payload)
+        || !isPlainObject(payload)
+        || Reflect.ownKeys(payload).length !== 1
+        || !Object.hasOwn(payload, 'args')
+        || !isObject(payload.args)
+        || !isPlainObject(payload.args)) {
+        throw new Error('Remote payload must contain exactly one plain-object args field')
+      }
+      const value = await this.invoke({
+        namespace,
+        method,
+        args: payload.args,
+      })
+      return { ok: true, value }
+    } catch (error) {
+      return rpcFailure(error)
+    }
+  }
+
+  private resolveDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const strict = this.ctx.typert.local.get(endpoint)
+    if (strict !== undefined) return strict
+    if (this.ctx.typert.local.hasSeen(endpoint)) {
+      throw new TypertGatewayError(
+        'definition-unavailable',
+        endpoint,
+        'its strict definition was withdrawn and SRC fallback is forbidden',
+      )
+    }
+    return this.resolveSrcDescriptor(namespace, method, endpoint)
+  }
+
+  private resolveSrcDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {
+    const candidates: InvocationDescriptor[] = []
+    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {
+      if (definition.type !== 'service') continue
+      const receiver = this.ctx.get(serviceKey) as unknown
+      if (!isObject(receiver)) continue
+      const original = originalOf(receiver)
+      const value = Reflect.get(original, 'typertGateway') as unknown
+      if (value === undefined) continue
+      const binding = readBinding(value, original, serviceKey, endpoint)
+      if (binding.namespace !== namespace) continue
+      const marker = remoteMethods(original).find(candidate => (candidate.exportName ?? candidate.method) === method)
+      if (marker === undefined) continue
+      candidates.push(this.srcDescriptor(binding, marker, method, endpoint))
+    }
+    if (candidates.length === 0) {
+      throw new TypertGatewayError('invocation-unavailable', endpoint, 'no active Remote method exports this endpoint')
+    }
+    if (candidates.length > 1) {
+      throw new TypertGatewayError(
+        'ambiguous-endpoint',
+        endpoint,
+        `multiple active Services export this endpoint: ${candidates.map(candidate => candidate.service).sort().join(', ')}`,
+      )
+    }
+    return candidates[0] as InvocationDescriptor
+  }
+
+  private srcDescriptor(
+    binding: TypeRTGatewayBinding,
+    marker: ReturnType<typeof remoteMethods>[number],
+    method: string,
+    endpoint: string,
+  ): InvocationDescriptor {
+    const names = methodParameterNames(binding.service, marker.method, endpoint)
+    const parameters: InvocationParameterDescriptor[] = []
+    const wires = new Set<string>()
+    for (const name of names) {
+      const matches = this.ctx.typert.lookups.keys()
+        .map(key => ({ key, provider: this.ctx.typert.lookups.get(key) }))
+        .filter((entry): entry is { key: string; provider: TypeRTLookupProvider } =>
+          entry.provider?.parameter === name)
+      if (matches.length > 1) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `parameter ${JSON.stringify(name)} matches multiple lookup providers`,
+          { field: name },
+        )
+      }
+      const match = matches[0]
+      const parameter: InvocationParameterDescriptor = match === undefined
+        ? { name, wire: name, source: 'json', codec: { mode: 'src-json' } }
+        : {
+          name,
+          wire: match.provider.wire,
+          source: 'lookup',
+          lookup: match.key,
+          codec: { mode: 'src-json' },
+        }
+      if (wires.has(parameter.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `multiple parameters use wire field ${JSON.stringify(parameter.wire)}`,
+          { field: parameter.wire },
+        )
+      }
+      wires.add(parameter.wire)
+      parameters.push(parameter)
+    }
+
+    let receiver: InvocationDescriptor['invocation'] = { kind: 'direct' }
+    if (marker.invocation.kind === 'context') {
+      const provider = this.ctx.typert.contexts.getHost(marker.invocation.context)
+      if (provider === undefined) {
+        throw new TypertGatewayError(
+          'context-unavailable',
+          endpoint,
+          `Context provider ${JSON.stringify(marker.invocation.context)} is unavailable`,
+        )
+      }
+      if (wires.has(provider.wire)) {
+        throw new TypertGatewayError(
+          'signature-invalid',
+          endpoint,
+          `Context identity conflicts with wire field ${JSON.stringify(provider.wire)}`,
+          { field: provider.wire },
+        )
+      }
+      receiver = {
+        kind: 'context',
+        context: marker.invocation.context,
+        wire: provider.wire,
+        codec: { mode: 'src-json' },
+      }
+    }
+
+    return {
+      id: `src:${binding.serviceKey}#${endpoint}`,
+      service: binding.serviceKey,
+      namespace: binding.namespace,
+      method,
+      ...(marker.method === method ? {} : { implementation: marker.method }),
+      invocation: receiver,
+      parameters,
+      result: { mode: 'src-json' },
+    }
+  }
+
+  private resolveReceiverContext(
+    descriptor: InvocationDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): Context {
+    if (descriptor.invocation.kind === 'direct') return this.ctx
+    const invocation = descriptor.invocation
+    const provider = this.ctx.typert.contexts.getHost(invocation.context)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'context-unavailable',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} is unavailable`,
+      )
+    }
+    if (provider.wire !== invocation.wire
+      || (invocation.codec.mode === 'strict' && provider.wireTypeSymbol !== invocation.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} does not match its strict definition`,
+        { field: invocation.wire },
+      )
+    }
+    const identity = decode(invocation.codec, args[invocation.wire], 'input-invalid', endpoint, invocation.wire)
+    let context: Context | undefined
+    try {
+      context = provider.resolve(identity)
+    } catch (cause) {
+      throw new TypertGatewayError(
+        'context-failed',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} failed`,
+        { cause, field: invocation.wire },
+      )
+    }
+    if (context === undefined) {
+      throw new TypertGatewayError(
+        'context-not-found',
+        endpoint,
+        `Context provider ${JSON.stringify(invocation.context)} did not resolve the requested identity`,
+        { field: invocation.wire },
+      )
+    }
+    return context
+  }
+
+  private resolveParameter(
+    parameter: InvocationParameterDescriptor,
+    args: Readonly<Record<string, unknown>>,
+    endpoint: string,
+  ): unknown {
+    const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)
+    if (parameter.source === 'json') return value
+    const key = parameter.lookup
+    if (key === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup parameter ${JSON.stringify(parameter.name)} has no provider key`,
+        { field: parameter.wire },
+      )
+    }
+    const provider = this.ctx.typert.lookups.get(key)
+    if (provider === undefined) {
+      throw new TypertGatewayError(
+        'lookup-unavailable',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} is unavailable`,
+        { field: parameter.wire },
+      )
+    }
+    if (provider.wire !== parameter.wire
+      || (parameter.codec.mode === 'strict' && provider.wireTypeSymbol !== parameter.codec.typeSymbol)) {
+      throw new TypertGatewayError(
+        'provider-mismatch',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} does not match its strict definition`,
+        { field: parameter.wire },
+      )
+    }
+    let resolved: unknown
+    try {
+      resolved = provider.resolve(value)
+    } catch (cause) {
+      throw new TypertGatewayError(
+        'lookup-failed',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} failed`,
+        { cause, field: parameter.wire },
+      )
+    }
+    if (resolved === undefined) {
+      throw new TypertGatewayError(
+        'lookup-not-found',
+        endpoint,
+        `lookup provider ${JSON.stringify(key)} did not resolve the requested identity`,
+        { field: parameter.wire },
+      )
+    }
+    return resolved
+  }
+}
+
+function rpcFailure(error: unknown): ConnectionRpcResult {
+  return {
+    ok: false,
+    error: {
+      code: 'internal',
+      message: error instanceof Error ? error.message : String(error),
+      details: {},
+    },
+  }
+}
+
+function endpointOf(namespace: string, method: string): string {
+  return `${namespace}/${method}`
+}
+
+function validateBinding(
+  receiver: object,
+  serviceKey: string,
+  namespace: string,
+  endpoint: string,
+): ResolvedBinding {
+  const original = originalOf(receiver)
+  const value = Reflect.get(original, 'typertGateway') as unknown
+  if (value === undefined) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has no visible typertGateway binding`,
+    )
+  }
+  return {
+    binding: readBinding(value, original, serviceKey, endpoint, namespace),
+    original,
+  }
+}
+
+function readBinding(
+  value: unknown,
+  original: object,
+  serviceKey: string,
+  endpoint: string,
+  namespace?: string,
+): TypeRTGatewayBinding {
+  if (!isObject(value)
+    || Reflect.get(value, 'service') !== original
+    || Reflect.get(value, 'serviceKey') !== serviceKey
+    || typeof Reflect.get(value, 'namespace') !== 'string'
+    || (namespace !== undefined && Reflect.get(value, 'namespace') !== namespace)) {
+    throw new TypertGatewayError(
+      'binding-invalid',
+      endpoint,
+      `Service ${JSON.stringify(serviceKey)} has an inconsistent typertGateway binding`,
+    )
+  }
+  return value as unknown as TypeRTGatewayBinding
+}
+
+function originalOf(receiver: object): object {
+  const original = Reflect.get(receiver, symbols.original) as unknown
+  return isObject(original) ? original : receiver
+}
+
+function methodParameterNames(service: object, method: string, endpoint: string): readonly string[] {
+  let prototype: object | null = Object.getPrototypeOf(service) as object | null
+  let implementation: ((this: object, ...args: never[]) => unknown) | undefined
+  while (prototype !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(prototype, method)
+    if (descriptor !== undefined) {
+      if ('value' in descriptor && typeof descriptor.value === 'function') {
+        implementation = descriptor.value as (this: object, ...args: never[]) => unknown
+      }
+      break
+    }
+    prototype = Object.getPrototypeOf(prototype) as object | null
+  }
+  if (implementation === undefined) {
+    throw new TypertGatewayError(
+      'method-unavailable',
+      endpoint,
+      `Remote marker has no prototype method ${JSON.stringify(method)}`,
+    )
+  }
+  const source = Function.prototype.toString.call(implementation)
+  const open = source.indexOf('(')
+  const close = source.indexOf(')', open + 1)
+  if (open < 0 || close < 0) return invalidSignature(endpoint, method)
+  const body = source.slice(open + 1, close).trim()
+  if (body.length === 0) return []
+  const parts = body.split(',').map(part => part.trim())
+  if (parts.at(-1) === '') parts.pop()
+  const names = new Set<string>()
+  for (const part of parts) {
+    if (!/^[$A-Z_a-z][$\w]*$/u.test(part) || names.has(part)) return invalidSignature(endpoint, method)
+    names.add(part)
+  }
+  return [...names]
+}
+
+function invalidSignature(endpoint: string, method: string): never {
+  throw new TypertGatewayError(
+    'signature-invalid',
+    endpoint,
+    `SRC method ${JSON.stringify(method)} must use unique identifier parameters without destructuring, defaults, or rest`,
+  )
+}
+
+function assertExactArguments(
+  args: Readonly<Record<string, unknown>>,
+  descriptor: InvocationDescriptor,
+  endpoint: string,
+): void {
+  if (!isPlainObject(args)) {
+    throw new TypertGatewayError('arguments-invalid', endpoint, 'args must be a plain object')
+  }
+  const expected = new Set(descriptor.parameters.map(parameter => parameter.wire))
+  if (descriptor.invocation.kind === 'context') expected.add(descriptor.invocation.wire)
+  const actual = Reflect.ownKeys(args)
+  const extra = actual.filter(key => typeof key !== 'string' || !expected.has(key))
+  const missing = [...expected].filter(key => !Object.hasOwn(args, key))
+  if (extra.length === 0 && missing.length === 0) return
+  const clauses: string[] = []
+  if (missing.length > 0) clauses.push(`missing ${missing.map(key => JSON.stringify(key)).join(', ')}`)
+  if (extra.length > 0) clauses.push(`unexpected ${extra.map(key => JSON.stringify(String(key))).join(', ')}`)
+  throw new TypertGatewayError('arguments-invalid', endpoint, `args fields do not match the descriptor: ${clauses.join('; ')}`)
+}
+
+function decode(
+  codec: TypeRTCodec,
+  value: unknown,
+  code: 'input-invalid' | 'result-invalid',
+  endpoint: string,
+  field: string,
+): unknown {
+  try {
+    if (codec.mode === 'strict') return codec.schema.parse(value)
+    assertJsonValue(value, new Set())
+    return value
+  } catch (cause) {
+    throw new TypertGatewayError(
+      code,
+      endpoint,
+      code === 'input-invalid'
+        ? `wire field ${JSON.stringify(field)} failed boundary validation`
+        : 'business result failed boundary validation',
+      { cause, field },
+    )
+  }
+}
+
+function assertJsonValue(value: unknown, ancestors: Set<object>): void {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return
+    throw new TypeError('non-finite number is not JSON-safe')
+  }
+  if (!isObject(value)) throw new TypeError(`${typeof value} is not JSON-safe`)
+  if (ancestors.has(value)) throw new TypeError('cyclic value is not JSON-safe')
+  ancestors.add(value)
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getOwnPropertySymbols(value).length > 0 || Object.keys(value).length !== value.length) {
+        throw new TypeError('sparse or decorated array is not JSON-safe')
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) throw new TypeError('sparse array is not JSON-safe')
+        assertJsonValue(value[index], ancestors)
+      }
+      return
+    }
+    if (!isPlainObject(value)) throw new TypeError('non-plain object is not JSON-safe')
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('symbol property is not JSON-safe')
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== 'string') throw new TypeError('symbol property is not JSON-safe')
+      const descriptor = Object.getOwnPropertyDescriptor(value, key)
+      if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {
+        throw new TypeError('non-data property is not JSON-safe')
+      }
+      assertJsonValue(descriptor.value, ancestors)
+    }
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+function isPlainObject(value: object): value is Record<string, unknown> {
+  if (Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value) as object | null
+  return prototype === null || prototype === Object.prototype
+}
+
+function isObject(value: unknown): value is object {
+  return (typeof value === 'object' && value !== null) || typeof value === 'function'
+}
+
+export default TypertGatewayService

packages/host/api-gateway/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-host-api-gateway`.
+ * @module @deepseek-ai/dsh-host-api-gateway/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-host-api-gateway'
+
+/** Cordis companion plugin name. */
+export const name = 'host-api-gateway-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: Host calls re-read authoritative Cordis and TypeRT
+ * state, while Client methods and descriptors mutate in one owned effect.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/host/api-gateway/src/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Carrier-independent TypeRT Gateway request, service, and error contracts.
+ * @module @deepseek-ai/dsh-host-api-gateway/types
+ */
+
+/** One Remote method request after a carrier has decoded its envelope. */
+export interface InvokeRemoteRequest {
+  /** Remote namespace selected by the generated descriptor. */
+  readonly namespace: string
+  /** Exported Service method name. */
+  readonly method: string
+  /** Named wire values; fields must exactly match the descriptor. */
+  readonly args: Readonly<Record<string, unknown>>
+}
+
+/** Stable infrastructure and boundary failures emitted before or after business execution. */
+export type TypertGatewayErrorCode =
+  | 'ambiguous-endpoint'
+  | 'arguments-invalid'
+  | 'binding-invalid'
+  | 'context-failed'
+  | 'context-not-found'
+  | 'context-unavailable'
+  | 'definition-unavailable'
+  | 'input-invalid'
+  | 'invocation-unavailable'
+  | 'lookup-failed'
+  | 'lookup-not-found'
+  | 'lookup-unavailable'
+  | 'method-unavailable'
+  | 'provider-mismatch'
+  | 'result-invalid'
+  | 'service-unavailable'
+  | 'signature-invalid'
+
+/** Host dispatcher consumed by Connection adapters. */
+export interface TypertGateway {
+  /**
+   * Invoke one live Remote method without assuming a carrier or response envelope.
+   * @param request - decoded endpoint and named wire arguments.
+   * @returns the validated business result.
+   * @throws {@link TypertGatewayError} for dispatch, provider, or boundary failures; business errors retain their identity.
+   */
+  invoke(request: InvokeRemoteRequest): Promise<unknown>
+}
+
+declare module 'cordis' {
+  interface Context {
+    /** Host dispatcher for TypeRT Remote calls. */
+    typertGateway: TypertGateway
+  }
+}

packages/host/api-gateway/tests/client.spec.ts

@@ -0,0 +1,222 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-client-connection/client'
+import type {
+  InvocationDescriptor,
+  TypeRTContext,
+  TypeRTRemoteContextApi,
+  TypeRTRemoteNamespace,
+} from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import { apply, inject } from '../src/client/index.ts'
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTContextMap {
+    fixture: TypeRTContext<string>
+  }
+
+  interface TypeRTRemoteMap {
+    'goals/create': (agentId: string, request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+  }
+
+  interface TypeRTRemoteContextMap {
+    'fixture:goals/create': (request: { readonly objective: string }) => Promise<{ readonly ref: string }>
+    'fixture:goals/rename': (request: { readonly objective: string }) => Promise<{ readonly renamed: boolean }>
+  }
+
+  interface TypeRTRemoteNamespaceMap {
+    goals: TypeRTRemoteNamespace<'goals'>
+  }
+
+}
+
+type FixtureContext = Context & TypeRTRemoteContextApi<'fixture'>
+
+const idSchema = z.string().min(1)
+const requestSchema = z.object({ objective: z.string().min(1) })
+const createResultSchema = z.object({ ref: z.string().min(1) })
+const renameResultSchema = z.object({ renamed: z.boolean() })
+
+function directDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    scope: { context: 'fixture', wire: 'agentId' },
+    parameters: [{
+      name: 'agent',
+      wire: 'agentId',
+      source: 'lookup',
+      lookup: 'fixture',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    }, {
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#CreateRequest', schema: requestSchema },
+    }],
+    result: { mode: 'strict', typeSymbol: '@fixture#CreateResult', schema: createResultSchema },
+  }
+}
+
+function contextDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/goals#goals/rename',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'rename',
+    invocation: {
+      kind: 'context',
+      context: 'fixture',
+      wire: 'agentId',
+      codec: { mode: 'strict', typeSymbol: '@fixture#AgentId', schema: idSchema },
+    },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: { mode: 'strict', typeSymbol: '@fixture#RenameRequest', schema: requestSchema },
+    }],
+    result: { mode: 'strict', typeSymbol: '@fixture#RenameResult', schema: renameResultSchema },
+  }
+}
+
+async function bench(call: ConnectionHandle['rpc']['call']): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  ctx.provide('connection', { rpc: { call } } as unknown as ConnectionHandle)
+  await ctx.plugin({ inject, apply })
+  return ctx
+}
+
+describe('Client TypeRT API', () => {
+  it('mounts concrete direct methods, validates both boundaries, and withdraws retained handles', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-1' } })
+    const ctx = await bench(call)
+    let retained: typeof ctx.api.goals.create | undefined
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+        retained = scope.api.goals.create
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).resolves.toEqual({ ref: 'goal-1' })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/create',
+      { args: { agentId: 'agent-1', request: { objective: 'ship' } } },
+      expect.any(AbortSignal),
+    )
+    await expect(ctx.api.goals.create('', { objective: 'ship' })).rejects.toThrow('rejected "agentId"')
+
+    call.mockResolvedValueOnce({ ok: true, value: { ref: 1 } })
+    await expect(ctx.api.goals.create('agent-1', { objective: 'ship' })).rejects.toThrow('rejected "result"')
+
+    await assembly.dispose()
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('goals')).toBeUndefined()
+    expect(ctx.typert.remotes.list()).toEqual([])
+    await expect(retained?.('agent-1', { objective: 'ship' })).rejects.toThrow('no longer mounted')
+  })
+
+  it('projects one direct lookup descriptor onto an Agent-scoped alias', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { ref: 'goal-2' } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.goals.create({ objective: 'ship scoped' })).resolves.toEqual({ ref: 'goal-2' })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/create',
+      { args: { agentId: 'agent-2', request: { objective: 'ship scoped' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).goals.create({ objective: 'wrong scope' }))
+      .rejects.toThrow('requires a "fixture" Context')
+
+    await assembly.dispose()
+    expect((ctx.api as unknown as Record<string, unknown>).goals).toBeUndefined()
+    expect(ctx.get('goals')).toBeUndefined()
+  })
+
+  it('uses the caller Context identity for scoped namespace methods', async () => {
+    const call = vi.fn<ConnectionHandle['rpc']['call']>()
+      .mockResolvedValue({ ok: true, value: { renamed: true } })
+    const ctx = await bench(call)
+    const agentCtx = ctx.extend({ fixtureId: 'agent-2' }) as FixtureContext
+    ctx.typert.contexts.registerClient('fixture', {
+      identity: candidate => (candidate as Context & { fixtureId?: string }).fixtureId,
+    })
+    const assembly = ctx.plugin(Object.assign(
+      (scope: Context) => {
+        scope.api.mount({ package: '@fixture/goals', descriptors: [contextDescriptor()] })
+      },
+      { inject: ['api'] },
+    ))
+    await assembly
+
+    await expect(agentCtx.goals.rename({ objective: 'land' })).resolves.toEqual({ renamed: true })
+    expect(call).toHaveBeenCalledWith(
+      '/api2',
+      'goals/rename',
+      { args: { agentId: 'agent-2', request: { objective: 'land' } } },
+      expect.any(AbortSignal),
+    )
+    await expect((ctx as FixtureContext).goals.rename({ objective: 'land' }))
+      .rejects.toThrow('requires a "fixture" Context')
+
+    await assembly.dispose()
+    expect(ctx.get('goals')).toBeUndefined()
+  })
+
+  it('rejects weak descriptors and namespace collisions before registration', async () => {
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>())
+    const weak: InvocationDescriptor = {
+      ...directDescriptor(),
+      result: { mode: 'src-json' },
+    }
+
+    expect(() => ctx.api.mount({ package: '@fixture/weak', descriptors: [weak] }))
+      .toThrow('has no strict codec')
+    expect(() => ctx.api.mount({
+      package: '@fixture/conflict',
+      descriptors: [{ ...directDescriptor(), namespace: 'mount' }],
+    })).toThrow('conflicts with the API service')
+    expect(ctx.typert.remotes.list()).toEqual([])
+  })
+
+  it('throws RPC failures with the structured error as its cause', async () => {
+    const rpcError = { code: 'internal' as const, message: 'host failed', details: {} }
+    const ctx = await bench(vi.fn<ConnectionHandle['rpc']['call']>().mockResolvedValue({ ok: false, error: rpcError }))
+    ctx.api.mount({ package: '@fixture/goals', descriptors: [directDescriptor()] })
+
+    let failure: unknown
+    try {
+      await ctx.api.goals.create('agent-1', { objective: 'ship' })
+    } catch (error) {
+      failure = error
+    }
+    expect(failure).toBeInstanceOf(Error)
+    if (!(failure instanceof Error)) throw new Error('expected Client API invocation to fail')
+    expect(failure.message).toContain('internal: host failed')
+    expect(failure.cause).toBe(rpcError)
+  })
+})

packages/host/api-gateway/tests/gateway.spec.ts

@@ -0,0 +1,795 @@
+import { createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { describe, expect, it } from 'vitest'
+import { Context, Service, symbols } from 'cordis'
+import { z } from 'zod'
+import { apply as applyConnection, inject as connectionInject } from '@deepseek-ai/dsh-client-connection'
+import type { HttpServerService, WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import {
+  bindTypeRTGateway,
+  Remote,
+  RemoteContext,
+  type InvocationDescriptor,
+  type TypeRTContext,
+  type TypeRTLookup,
+  type TypeRTLookupProvider,
+} from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry, { type TypertContribution } from '@deepseek-ai/dsh-typert-registry'
+import TypertGatewayService, { TypertGatewayError } from '@deepseek-ai/dsh-host-api-gateway'
+
+interface FixtureAgent {
+  readonly id: string
+}
+
+interface MarkedContext extends Context {
+  readonly fixtureScope?: string
+}
+
+declare module '@deepseek-ai/dsh-type-meta' {
+  interface TypeRTLookupMap {
+    gatewayFixture: TypeRTLookup<FixtureAgent, string>
+    gatewayFixtureAlias: TypeRTLookup<FixtureAgent, string>
+  }
+
+  interface TypeRTContextMap {
+    gatewayFixture: TypeRTContext<string>
+  }
+}
+
+const emptyModel: TypertContribution['model'] = {
+  services: [],
+  events: [],
+  objects: [],
+}
+
+class GoalService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'goals')
+  readonly calls: string[] = []
+  nextResult: unknown = undefined
+  businessError: Error | undefined
+
+  constructor(ctx: Context) {
+    super(ctx, 'goals')
+  }
+
+  @Remote
+  create(agent: FixtureAgent, request: { readonly title: string }): unknown {
+    this.calls.push('create')
+    return {
+      agentId: agent.id,
+      title: request.title,
+      scope: (this.ctx as MarkedContext).fixtureScope ?? 'root',
+    }
+  }
+
+  @RemoteContext('gatewayFixture')
+  rename(request: { readonly title: string }): unknown {
+    this.calls.push('rename')
+    return { title: request.title, scope: (this.ctx as MarkedContext).fixtureScope ?? 'root' }
+  }
+
+  @Remote
+  passthrough(value: unknown): unknown {
+    this.calls.push('passthrough')
+    return this.nextResult === undefined ? value : this.nextResult
+  }
+
+  @Remote
+  fail(request: unknown): never {
+    void request
+    this.calls.push('fail')
+    throw this.businessError ?? new Error('fixture business failure')
+  }
+
+  strictOnly(request: { readonly title: string }): unknown {
+    this.calls.push('strictOnly')
+    return this.nextResult === undefined ? request : this.nextResult
+  }
+}
+
+type FakeRpcResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: { readonly code: 'internal'; readonly message: string; readonly details: object } }
+
+type FakeRpcHandler = (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<FakeRpcResult>
+
+class FakeConnectionService extends Service {
+  channel: string | undefined
+  authority: string | undefined
+  handler: FakeRpcHandler | undefined
+
+  constructor(ctx: Context) {
+    super(ctx, 'connection')
+  }
+
+  get rpc() {
+    const owner = this.ctx
+    return {
+      handle: (channel: string, handler: FakeRpcHandler, options: { readonly authority: string }) =>
+        owner.effect(() => {
+          this.channel = channel
+          this.authority = options.authority
+          this.handler = handler
+          return () => {
+            this.channel = undefined
+            this.authority = undefined
+            this.handler = undefined
+          }
+        }),
+    }
+  }
+}
+
+function fakeHttpServer(routes: WebRoute[]): Pick<HttpServerService, 'register' | 'tapIndex' | 'port'> {
+  return {
+    register(route) {
+      if (routes.some(candidate => candidate.kind === route.kind && candidate.path === route.path)) {
+        throw new Error(`duplicate route ${route.path}`)
+      }
+      routes.push(route)
+      return () => { routes.splice(routes.indexOf(route), 1) }
+    },
+    tapIndex: () => () => {},
+    port: 0,
+  }
+}
+
+async function serveRoute(route: WebRoute): Promise<{ readonly origin: string; close(): Promise<void> }> {
+  const server = createServer((request, response) => {
+    void route.handler(request, response)
+  })
+  await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve))
+  const address = server.address() as AddressInfo
+  return {
+    origin: `http://127.0.0.1:${String(address.port)}`,
+    close: () => new Promise<void>((resolve, reject) => {
+      server.close((error) => {
+        if (error === undefined || error === null) resolve()
+        else reject(error)
+      })
+    }),
+  }
+}
+
+class FirstSharedService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'firstShared', { namespace: 'shared' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'firstShared')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class SecondSharedService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'secondShared', { namespace: 'shared' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'secondShared')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+class DefaultParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'defaultParameter', { namespace: 'invalid-default' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'defaultParameter')
+  }
+
+  @Remote
+  run(value = 'fallback'): string {
+    return value
+  }
+}
+
+class DestructuredParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'destructuredParameter', { namespace: 'invalid-destructure' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'destructuredParameter')
+  }
+
+  @Remote
+  run({ value }: { readonly value: string }): string {
+    return value
+  }
+}
+
+class RestParameterService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'restParameter', { namespace: 'invalid-rest' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'restParameter')
+  }
+
+  @Remote
+  run(...values: readonly unknown[]): string {
+    return values.map(String).join(',')
+  }
+}
+
+class WrongBindingService extends Service {
+  readonly typertGateway = bindTypeRTGateway(this, 'notWrongBinding', { namespace: 'wrong-binding' })
+
+  constructor(ctx: Context) {
+    super(ctx, 'wrongBinding')
+  }
+
+  @Remote
+  run(value: string): string {
+    return value
+  }
+}
+
+describe('TypertGatewayService', () => {
+  it('invokes a strict direct method with schema decoding and a live lookup', async () => {
+    const { ctx, service } = await setup()
+    const agent = { id: 'agent-1' }
+    registerAgentLookup(ctx, agent)
+    registerStrict(ctx, [createDescriptor()])
+    const caller = ctx.extend({ fixtureScope: 'direct-caller' })
+
+    await expect(caller.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: '  ship  ' } },
+    })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-caller' })
+    expect(service.calls).toEqual(['create'])
+  })
+
+  it('resolves strict Remote Context identity without adding a business argument', async () => {
+    const { ctx, service } = await setup()
+    const scoped = ctx.extend({ fixtureScope: 'agent-scope' })
+    ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+    registerStrict(ctx, [renameDescriptor()])
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    })).resolves.toEqual({ title: 'land', scope: 'agent-scope' })
+    expect(service.calls).toEqual(['rename'])
+  })
+
+  it('derives SRC direct lookup and JSON parameters from marker and parameter names', async () => {
+    const { ctx } = await setup()
+    const agent = { id: 'agent-1' }
+    registerAgentLookup(ctx, agent)
+    const caller = ctx.extend({ fixtureScope: 'direct-src' })
+
+    await expect(caller.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    })).resolves.toEqual({ agentId: 'agent-1', title: 'ship', scope: 'direct-src' })
+  })
+
+  it('derives SRC Remote Context identity and preserves the scoped Proxy receiver', async () => {
+    const { ctx } = await setup()
+    const scoped = ctx.extend({ fixtureScope: 'agent-src' })
+    ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    })).resolves.toEqual({ title: 'land', scope: 'agent-src' })
+  })
+
+  it('re-reads Service and providers on every strict invocation', async () => {
+    const { ctx, serviceFiber } = await setup()
+    const agent = { id: 'agent-1' }
+    const disposeLookup = registerAgentLookup(ctx, agent)
+    registerStrict(ctx, [createDescriptor()])
+
+    await disposeLookup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'lookup-unavailable')
+
+    registerAgentLookup(ctx, agent)
+    await serviceFiber.dispose()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'service-unavailable')
+  })
+
+  it('re-reads and contains Context providers', async () => {
+    const { ctx } = await setup()
+    const scoped = ctx.extend()
+    const dispose = ctx.typert.contexts.registerHost('gatewayFixture', contextProvider(scoped))
+    registerStrict(ctx, [renameDescriptor()])
+
+    await dispose()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-unavailable')
+
+    ctx.typert.contexts.registerHost('gatewayFixture', {
+      ...contextProvider(scoped),
+      resolve: () => { throw new Error('provider failed') },
+    })
+    const error = await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'rename',
+      args: { agentId: 'agent-1', request: { title: 'land' } },
+    }), 'context-failed')
+    expect(error.cause).toEqual(new Error('provider failed'))
+  })
+
+  it('never downgrades an observed strict endpoint after definition disposal', async () => {
+    const { ctx } = await setup()
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await dispose()
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('seeds the no-downgrade guard from definitions present before Gateway startup', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await ctx.plugin(TypertGatewayService)
+    await ctx.plugin(GoalService)
+    await dispose()
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('retains the no-downgrade guard across Gateway Service reloads', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    await ctx.plugin(GoalService)
+    const dispose = registerStrict(ctx, [passthroughDescriptor()])
+    await dispose()
+
+    await gatewayFiber.dispose()
+    await ctx.plugin(TypertGatewayService)
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: 'would pass through SRC' },
+    }), 'definition-unavailable')
+  })
+
+  it('rejects ambiguous SRC endpoints independently of reflection order', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(FirstSharedService)
+    await ctx.plugin(SecondSharedService)
+
+    const error = await expectCode(ctx.typertGateway.invoke({
+      namespace: 'shared',
+      method: 'run',
+      args: { value: 'ship' },
+    }), 'ambiguous-endpoint')
+    expect(error.message).toContain('firstShared, secondShared')
+  })
+
+  it('rejects SRC signatures that cannot map one wire field to each position', async () => {
+    const cases = [
+      { plugin: DefaultParameterService, namespace: 'invalid-default', args: { value: 'x' } },
+      { plugin: DestructuredParameterService, namespace: 'invalid-destructure', args: { value: { value: 'x' } } },
+      { plugin: RestParameterService, namespace: 'invalid-rest', args: { values: ['x'] } },
+    ] as const
+    for (const testCase of cases) {
+      const ctx = await setupGateway()
+      await ctx.plugin(testCase.plugin)
+      await expectCode(ctx.typertGateway.invoke({
+        namespace: testCase.namespace,
+        method: 'run',
+        args: testCase.args,
+      }), 'signature-invalid')
+    }
+  })
+
+  it('rejects a SRC parameter matching more than one lookup provider', async () => {
+    const { ctx } = await setup()
+    const provider = agentLookup({ id: 'agent-1' })
+    ctx.typert.lookups.register('gatewayFixture', provider)
+    ctx.typert.lookups.register('gatewayFixtureAlias', provider)
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'signature-invalid')
+  })
+
+  it('requires exact wire fields before invoking business code', async () => {
+    const { ctx, service } = await setup()
+    registerAgentLookup(ctx, { id: 'agent-1' })
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { request: { title: 'ship' } },
+    }), 'arguments-invalid')
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' }, optional: true },
+    }), 'arguments-invalid')
+    expect(service.calls).toEqual([])
+  })
+
+  it('distinguishes strict input and result validation failures', async () => {
+    const { ctx, service } = await setup()
+    registerStrict(ctx, [strictOnlyDescriptor()])
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'strictOnly',
+      args: { request: { title: 1 } },
+    }), 'input-invalid')
+
+    service.nextResult = { title: 1 }
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'strictOnly',
+      args: { request: { title: 'ship' } },
+    }), 'result-invalid')
+  })
+
+  it.each([
+    undefined,
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+    1n,
+    Symbol('value'),
+    () => 'value',
+    new Date(0),
+    new Map(),
+    [, 'sparse'],
+  ])('rejects non-JSON SRC input %#', async (value) => {
+    const { ctx } = await setup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value },
+    }), 'input-invalid')
+  })
+
+  it('rejects cyclic SRC input and non-JSON SRC results', async () => {
+    const { ctx, service } = await setup()
+    const cyclic: { self?: unknown } = {}
+    cyclic.self = cyclic
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: cyclic },
+    }), 'input-invalid')
+
+    service.nextResult = new Date(0)
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'passthrough',
+      args: { value: null },
+    }), 'result-invalid')
+  })
+
+  it('validates strict provider identity against generated wire metadata', async () => {
+    const { ctx } = await setup()
+    ctx.typert.lookups.register('gatewayFixture', {
+      ...agentLookup({ id: 'agent-1' }),
+      wire: 'differentAgentId',
+    })
+    registerStrict(ctx, [createDescriptor()])
+
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'create',
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }), 'provider-mismatch')
+  })
+
+  it('validates binding identity and active method availability', async () => {
+    const ctx = await setupGateway()
+    await ctx.plugin(WrongBindingService)
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'wrong-binding',
+      method: 'run',
+      args: { value: 'ship' },
+    }), 'binding-invalid')
+
+    await ctx.plugin(GoalService)
+    registerStrict(ctx, [{ ...passthroughDescriptor(), method: 'missing' }])
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'missing',
+      args: { value: 'ship' },
+    }), 'method-unavailable')
+  })
+
+  it('preserves business exception identity after invocation begins', async () => {
+    const { ctx, service } = await setup()
+    const failure = new Error('business identity')
+    service.businessError = failure
+
+    await expect(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'fail',
+      args: { request: { reason: 'fixture' } },
+    })).rejects.toBe(failure)
+  })
+
+  it('reports an absent endpoint without retaining receiver state', async () => {
+    const { ctx } = await setup()
+    await expectCode(ctx.typertGateway.invoke({
+      namespace: 'goals',
+      method: 'absent',
+      args: {},
+    }), 'invocation-unavailable')
+  })
+
+  it('mounts /api2 through an optional Connection and returns existing RPC results', async () => {
+    const ctx = new Context().extend({ fixtureScope: 'rpc-caller' })
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(FakeConnectionService)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    await ctx.plugin(GoalService)
+    const connection = rawConnection(ctx)
+    expect(connection).toMatchObject({ channel: '/api2', authority: 'trusted-host' })
+
+    registerAgentLookup(ctx, { id: 'agent-1' })
+    registerStrict(ctx, [createDescriptor()])
+    const signal = new AbortController().signal
+    const handler = connection.handler
+    if (handler === undefined) throw new Error('fixture Connection did not retain the /api2 handler')
+    await expect(handler('goals/create', {
+      args: { agentId: 'agent-1', request: { title: 'ship' } },
+    }, signal)).resolves.toEqual({
+      ok: true,
+      value: { agentId: 'agent-1', title: 'ship', scope: 'rpc-caller' },
+    })
+    const invalid = await handler('goals/create', { invalid: true }, signal)
+    expect(invalid).toMatchObject({
+      ok: false,
+      error: { code: 'internal' },
+    })
+    if (invalid.ok) throw new Error('invalid Remote payload unexpectedly succeeded')
+    expect(invalid.error.message).toMatch(/exactly one plain-object args field/)
+
+    await gatewayFiber.dispose()
+    expect(connection.handler).toBeUndefined()
+  })
+
+  it('dispatches a generated invocation through the real /api2 HTTP carrier', async () => {
+    const ctx = new Context().extend({ fixtureScope: 'http-caller' })
+    const routes: WebRoute[] = []
+    ctx.provide('httpServer', fakeHttpServer(routes) as HttpServerService)
+    const connectionFiber = ctx.plugin({ inject: [...connectionInject], apply: applyConnection })
+    await connectionFiber
+    await ctx.plugin(TypertRegistry)
+    const gatewayFiber = ctx.plugin(TypertGatewayService)
+    await gatewayFiber
+    const goalFiber = ctx.plugin(GoalService)
+    await goalFiber
+    const removeLookup = registerAgentLookup(ctx, { id: 'agent-1' })
+    const removeStrict = registerStrict(ctx, [createDescriptor()])
+    expect(routes).toHaveLength(1)
+    const server = await serveRoute(routes[0]!)
+
+    try {
+      const response = await fetch(`${server.origin}/api2/goals/create`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          type: 'client-request',
+          rpcId: 'rpc-http',
+          method: 'goals/create',
+          payload: { args: { agentId: 'agent-1', request: { title: '  ship  ' } } },
+        }),
+      })
+      expect(response.status).toBe(200)
+      await expect(response.json()).resolves.toEqual({
+        type: 'server-response',
+        rpcId: 'rpc-http',
+        result: {
+          ok: true,
+          value: { agentId: 'agent-1', title: 'ship', scope: 'http-caller' },
+        },
+      })
+    } finally {
+      await server.close()
+      await removeStrict()
+      await removeLookup()
+      await goalFiber.dispose()
+      await gatewayFiber.dispose()
+      await connectionFiber.dispose()
+    }
+    expect(routes).toHaveLength(0)
+  })
+})
+
+async function setup(): Promise<{
+  readonly ctx: Context
+  readonly service: GoalService
+  readonly serviceFiber: ReturnType<Context['plugin']>
+}> {
+  const ctx = await setupGateway()
+  const serviceFiber = ctx.plugin(GoalService)
+  await serviceFiber
+  return { ctx, service: rawGoalService(ctx), serviceFiber }
+}
+
+async function setupGateway(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(TypertRegistry)
+  await ctx.plugin(TypertGatewayService)
+  return ctx
+}
+
+function rawGoalService(ctx: Context): GoalService {
+  const receiver = ctx.get('goals') as unknown as GoalService & { [symbols.original]?: GoalService }
+  return receiver[symbols.original] ?? receiver
+}
+
+function rawConnection(ctx: Context): FakeConnectionService {
+  const receiver = ctx.get('connection') as unknown as FakeConnectionService & {
+    [symbols.original]?: FakeConnectionService
+  }
+  return receiver[symbols.original] ?? receiver
+}
+
+function registerStrict(ctx: Context, descriptors: readonly InvocationDescriptor[]): () => Promise<void> {
+  return ctx.typert.register({
+    package: '@fixture/gateway',
+    face: 'host',
+    schemas: [],
+    model: emptyModel,
+    invocations: descriptors,
+  })
+}
+
+function registerAgentLookup(ctx: Context, agent: FixtureAgent): () => Promise<void> {
+  return ctx.typert.lookups.register('gatewayFixture', agentLookup(agent))
+}
+
+function agentLookup(agent: FixtureAgent): TypeRTLookupProvider<FixtureAgent, string> {
+  return {
+    parameter: 'agent',
+    wire: 'agentId',
+    hostTypeSymbol: '@fixture/domain#Agent',
+    wireTypeSymbol: '@fixture/domain#AgentId',
+    resolve: id => id === agent.id ? agent : undefined,
+  }
+}
+
+function contextProvider(context: Context) {
+  return {
+    wire: 'agentId',
+    wireTypeSymbol: '@fixture/domain#AgentId',
+    resolve: (id: string) => id === 'agent-1' ? context : undefined,
+  }
+}
+
+function strictCodec(typeSymbol: string, schema: z.ZodType): InvocationDescriptor['result'] {
+  return { mode: 'strict', typeSymbol, schema }
+}
+
+function createDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/create',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'create',
+    invocation: { kind: 'direct' },
+    parameters: [
+      {
+        name: 'agent',
+        wire: 'agentId',
+        source: 'lookup',
+        lookup: 'gatewayFixture',
+        codec: strictCodec('@fixture/domain#AgentId', z.string()),
+      },
+      {
+        name: 'request',
+        wire: 'request',
+        source: 'json',
+        codec: strictCodec('@fixture/gateway#CreateRequest', z.object({
+          title: z.string().transform(value => value.trim()),
+        })),
+      },
+    ],
+    result: strictCodec('@fixture/gateway#CreateResult', z.object({
+      agentId: z.string(),
+      title: z.string(),
+      scope: z.string(),
+    })),
+  }
+}
+
+function renameDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/rename',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'rename',
+    invocation: {
+      kind: 'context',
+      context: 'gatewayFixture',
+      wire: 'agentId',
+      codec: strictCodec('@fixture/domain#AgentId', z.string()),
+    },
+    parameters: [{
+      name: 'request',
+      wire: 'request',
+      source: 'json',
+      codec: strictCodec('@fixture/gateway#RenameRequest', z.object({ title: z.string() })),
+    }],
+    result: strictCodec('@fixture/gateway#RenameResult', z.object({
+      title: z.string(),
+      scope: z.string(),
+    })),
+  }
+}
+
+function passthroughDescriptor(): InvocationDescriptor {
+  return {
+    id: '@fixture/gateway#goals/passthrough',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'passthrough',
+    invocation: { kind: 'direct' },
+    parameters: [{
+      name: 'value',
+      wire: 'value',
+      source: 'json',
+      codec: { mode: 'src-json' },
+    }],
+    result: { mode: 'src-json' },
+  }
+}
+
+function strictOnlyDescriptor(): InvocationDescriptor {
+  const value = strictCodec('@fixture/gateway#StrictValue', z.object({ title: z.string() }))
+  return {
+    id: '@fixture/gateway#goals/strictOnly',
+    service: 'goals',
+    namespace: 'goals',
+    method: 'strictOnly',
+    invocation: { kind: 'direct' },
+    parameters: [{ name: 'request', wire: 'request', source: 'json', codec: value }],
+    result: value,
+  }
+}
+
+async function expectCode(
+  promise: Promise<unknown>,
+  code: TypertGatewayError['code'],
+): Promise<TypertGatewayError> {
+  try {
+    await promise
+  } catch (error) {
+    expect(error).toBeInstanceOf(TypertGatewayError)
+    expect(error).toMatchObject({ code })
+    return error as TypertGatewayError
+  }
+  throw new Error(`expected TypertGatewayError ${code}`)
+}

packages/host/api-gateway/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../client/connection"
+    },
+    {
+      "path": "../../typert/type-meta"
+    }
+  ]
+}

packages/host/api-gateway/tsdown.config.ts

@@ -0,0 +1,3 @@
+import { clientBundle } from '../../client/tsdown.client.ts'
+
+export default clientBundle('@deepseek-ai/dsh-host-api-gateway', ['lib/types/index.js', 'lib/types/invariant.js'])

packages/host/apiproxy/src/api/index.ts

@@ -72,6 +72,11 @@ export type {
 // ---- Errors and ids ----
 export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+export {
+  clientRequestSchema,
+  serverRequestSchema,
+  serverResponseSchema,
+} from './rpc.schema.ts'
 
 // ---- Fixed session-search product bounds ----
 export {