export interface RemoteFailure {  // 一次远端调用的失败面：carrier 上报时的原始形状  readonly code: string  // code 在这里故意保持开放字符串——封闭的 RPC 码联合属于 carrier 包，写死会反转依赖方向  readonly message: string  // 面向调用方的诊断文本，不含敏感值  readonly details: object  // 结构化细节槽位，由业务方决定放什么}  // 结束该分支块export type RemoteResult<T> =  // 每个生成的 Remote 方法最终都解析成这个二元结果  | { readonly ok: true; readonly value: T }  // 成功分支：value 是 Host 方法的业务返回值  | { readonly ok: false; readonly error: RemoteFailure }  // 失败分支：carrier 的失败已折叠进这里，消费方无需再包一层 try/catch

export function bindTypertRemote<Service extends object>(  // 把一个可见 Service 字段绑定到 Cordis key 和 Remote namespace  service: Service,  // 持有该方法的 Service 实例，通常是 this  serviceKey: string,  // 精确的 Cordis 服务键，也是默认 wire namespace  options: TypertGatewayBindingOptions = {},  // 可选：用不同的 wire namespace 覆盖默认值): TypertGatewayBinding<Service> {  // 返回冻结、可检查的绑定对象  validateName('service key', serviceKey)  // 先校验键名只含 RPC endpoint 合法字符，非法直接抛错  const namespace = options.namespace ?? serviceKey  // 没显式指定 namespace 就沿用服务键——默认即约定  validateName('namespace', namespace)  // namespace 同样过一遍字符集校验  return Object.freeze({ service, serviceKey, namespace })  // freeze 保证绑定不可被运行时篡改，Gateway 侧可安全信任}  // 结束该分支块export abstract class TypertRemoteService<out T = never> extends Service<T> {  // Cordis Service 基类：注册时顺带暴露 typertRemote 绑定  readonly typertRemote: TypertGatewayBinding<this>  // Gateway 的 SRC 发现路径靠读这个字段找到"谁在导出 Remote"  protected constructor(ctx: Context, serviceKey: string, options: TypertGatewayBindingOptions = {}) {  // 子类构造时传入服务键    super(ctx, serviceKey)  // 先完成 Cordis Service 的常规注册    this.typertRemote = bindTypertRemote(this, this.name, options)  // 再用同一个 key 绑定 Gateway——一处声明，两处生效  }  // 结束该分支块}  // 结束该分支块

const markers = new WeakMap<object, Map<string, StoredRemoteMethodMarker>>()  // 私有标记表：原型 → {方法名 → marker}，WeakMap 让 Service 可被 GCfunction addMarkerInitializer<This extends object>(  // 装饰器入口：把"标记动作"推迟到实例化时执行  context: RemoteInitializerContext<This>,  // 标准 TC39 装饰器上下文，提供 addInitializer  invocation: RemoteInvocationMarker,  // direct（直调）或 context（按 Context 解析接收者）  exportName?: string,  // 可选导出名：endpoint 方法名与实现成员名解耦): void {  // 装饰器入口本身不做事——只注册实例化钩子，标记推迟到构造期执行  if (context.private || context.static || typeof context.name !== 'string') {  // Remote 只允许"公有实例方法 + 字符串名"，否则无法按名字寻址    throw new TypeError('typert-protocol: Remote decorators require a public instance method with a string name')  // fail loud：装饰器用错位置立即报错，不留到运行时才发现  }  // 结束该分支块  const method = context.name  // 记下方法名，稍后在原型上登记  context.addInitializer(function (this: This) {  // 注册实例初始化钩子——标记发生在构造时而非类定义时    const prototype = Object.getPrototypeOf(this) as object | null  // 取实例原型：marker 挂在原型上，全实例共享一份    if (prototype === null) {  // 无原型的对象（Object.create(null)）无法登记      throw new TypeError(`typert-protocol: cannot mark Remote method "${method}" on an object without a prototype`)  // 明确报错而不是静默丢失导出    }  // 结束该分支块    mark(prototype, method, invocation, exportName)  // 真正写入私有标记表  })}  // 结束该分支块function mark(prototype: object, method: string, invocation: RemoteInvocationMarker, exportName?: string): void {  // 把 marker 写进原型级 Map  let table = markers.get(prototype)  // 查该原型已有的标记表  if (table === undefined) {  // 首次出现：建表并挂到 WeakMap    table = new Map()  // 每个原型一张表，该类所有实例共享    markers.set(prototype, table)  // 挂上 WeakMap——Service 卸载后整张表随原型一起回收  }  // 结束该分支块  const marker: StoredRemoteMethodMarker = {  // 组装最终 marker；exportName 与实现名相同时省略，省一个字段    ...(exportName === undefined || exportName === method ? {} : { exportName }),  // 条件展开：只有别名导出才写 exportName    invocation: Object.freeze(invocation),  // freeze：调用模式不可变，Gateway 读到的就是声明时的样子  }  // 结束该分支块  const current = table.get(method)  // 同名方法被重复装饰？  if (current !== undefined) {  // 已有 marker    if (current.exportName === marker.exportName && sameInvocation(current.invocation, invocation)) return  // 完全相同的重复声明幂等放行    throw new Error(`typert-protocol: Remote method "${method}" has conflicting invocation markers`)  // 冲突（如 direct vs context）直接抛错，拒绝二义性  }  // 结束该分支块  table.set(method, Object.freeze(marker))  // 落表并冻结}  // 结束该分支块

export class GoalService extends TypertRemoteService {  // 继承基类 = 自动获得 typertRemote 绑定，namespace 默认 'goals'  static inject = ['agents']  // 声明依赖：Cordis 注入 agents 服务  constructor(ctx: Context, config: Config = {}) {  // 常规 Service 构造    super(ctx, 'goals')  // 注册为 'goals'，同时绑定 wire namespace 'goals'——endpoint 前缀由此而来  }  // 结束该分支块  @Remote('edit')  // 把 edit() 标记为 Remote 导出；exportName='edit' 与实现同名  edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView {  // 客户端将调用 goals/edit，wire args 按参数名命名    const cache = this.prepareMutation(agent)  // 取该 session 的 goal 变更缓存（业务逻辑）    const current = this.expectCurrent(cache, ref)  // 校验 ref.revision 与当前一致——乐观并发控制    if (request.objective === undefined && request.maxGoalRounds === undefined) {  // 两个字段都没给 = 空编辑，无意义      throw new GoalError('goal edit requires objective and/or maxGoalRounds', 'GOAL_INVALID_EDIT')  // 业务错误带稳定 code，网关会原样透传给客户端    }  // 结束该分支块  }  // 结束该分支块}  // 结束该分支块

export class TypertGatewayService extends Service implements TypertGateway {  // Gateway 本身也是一个 Cordis Service（键 'typertGateway'）  static inject = ['typert']  // 依赖 typert registry：strict 定义、lookup、context 都从它读  constructor(ctx: Context) {  // 构造即完成全部接线，无独立 start 阶段    super(ctx, 'typertGateway')  // 注册服务键    ctx.on('internal/service', () => {  // 监听服务表变化事件      this.srcClaims = undefined  // 缓存失效：SRC endpoint 集合随 Service 增删而变，必须重算    })    ctx.inject(['connection'], (connectionCtx) => {  // 拿到 connection 后在 RPC 通道上挂拦截器      connectionCtx.connection.rpc.intercept(  // intercept('/api', ...) = 认领 /api/* 前缀下的 endpoint        '/api',  // 命名空间前缀：Typert 网关只处理 /api 下的调用        endpoint => this.claimsEndpoint(endpoint),  // claimer：判断某个具体 endpoint 是否归本 Gateway        (endpoint, payload, signal) => this.dispatchRpc(endpoint, payload, signal),  // dispatcher：真正执行并返回 envelope        { authority: 'trusted-host' },  // 权限标记：只有受信 Host 通道能触发，外部不可伪造      )    })  }  // 结束该分支块  private claimsEndpoint(endpoint: string): boolean {  // 回答"这个 endpoint 我接不接"    const segments = endpoint.split('/')  // endpoint 语法是 <namespace>/<method> 两段    if (segments.length !== 2 || segments[0] === '' || segments[1] === '') return false  // 段数不对或空段：不是合法 Remote endpoint，直接不认领    if (this.ctx.typert.local.get(endpoint) !== undefined || this.ctx.typert.local.hasSeen(endpoint)) return true  // strict 定义在册（含已撤回）都算我的——hasSeen 防止撤回后被 SRC 路径偷接    this.srcClaims ??= this.collectSrcClaims()  // 首次需要时惰性收集 SRC marker endpoint，之后缓存    return this.srcClaims.has(endpoint)  // SRC 标记命中才认领  }  // 结束该分支块  private collectSrcClaims(): ReadonlySet<string> {  // 扫描所有活跃 Service，找出带 typertRemote 绑定 + Remote marker 的导出    const claims = new Set<string>()  // 收集 endpoint 集合    for (const [serviceKey, definition] of Object.entries(this.ctx.reflect.props)) {  // 遍历反射表里的全部服务定义      if (definition.type !== 'service') continue  // 只关心 service 类型条目      const receiver = this.ctx.get(serviceKey) as unknown  // 取活实例；ctx.get 读全局服务存储，不依赖注入拓扑      if (!isObject(receiver)) continue  // 未激活/不可用：跳过      const original = originalOf(receiver)  // 剥掉 Cordis 代理层，拿到原始对象（marker 挂在原对象原型上）      const binding = Reflect.get(original, 'typertRemote') as unknown  // 读 typertRemote 绑定字段——没有就不是 Remote Service      if (!isObject(binding) || typeof Reflect.get(binding, 'namespace') !== 'string') continue  // 绑定残缺：跳过，不猜      const namespace = Reflect.get(binding, 'namespace') as string  // 读出 wire 命名空间（namespace），后面拼 endpoint 用      for (const candidate of remoteMethods(original)) {  // 枚举该 Service 上所有 @Remote marker        claims.add(endpointOf(namespace, candidate.exportName ?? candidate.method))  // 拼出 <ns>/<method>；exportName 优先（别名导出）      }  // 结束该分支块    }  // 结束该分支块    return claims  // 返回完整 SRC endpoint 集合  }  // 结束该分支块

async invoke(request: InvokeRemoteRequest): Promise<unknown> {  // 一次 Remote 调用的总入口：从 wire args 到业务返回值  const endpoint = endpointOf(request.namespace, request.method)  // 拼规范 endpoint，后续所有错误信息都用它定位  const descriptor = this.resolveDescriptor(request.namespace, request.method, endpoint)  // 解析调用描述符：strict 定义优先，SRC marker 兜底  assertExactArguments(request.args, descriptor, endpoint)  // wire args 与描述符逐字段对账：多一个少一个都拒绝  const receiverContext = await this.resolveReceiverContext(descriptor, request.args, endpoint)  // context 模式：先按 identity 解析出目标 Context（接收者）  const receiver = receiverContext.get(descriptor.service) as unknown  // 在目标 Context 里取 Service 实例  if (!isObject(receiver)) {  // 服务不在该 Context 上（未激活/被卸载）    throw new TypertGatewayError('service-unavailable', endpoint, `active Service ${JSON.stringify(descriptor.service)} is unavailable`)  // 明确报 service-unavailable，不静默降级  }  // 结束该分支块  validateBinding(receiver, descriptor.service, descriptor.namespace, endpoint)  // 复核 typertRemote 绑定与描述符一致——防"张冠李戴"的 Service  const args = await Promise.all(descriptor.parameters.map(parameter =>  // 并行解析全部业务参数（json 解码 / lookup 换实体）    this.resolveParameter(parameter, request.args, endpoint)))  // 任一失败即整体拒绝，不会半执行  if (descriptor.cancellation !== undefined) args.push(request.signal ?? NEVER_ABORTED_SIGNAL)  // 声明了取消的：signal 追加为最后一个实参，不进 wire args  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)}`)  // 报 method-unavailable，区分"服务在但方法没了"  }  // 结束该分支块  let result: unknown  // 业务返回值暂存  try {  // 包住真正的业务调用，好把取消与业务失败分开处理    result = await Reflect.apply(method, receiver, args) as unknown  // 真正执行业务方法；receiver 绑定 this  } catch (error) {  // 执行抛错    if (request.signal?.aborted === true) throw new RemoteInvocationCancelled(endpoint, error)  // carrier 已取消：转成 cancelled 语义，不把业务错误当取消报    throw error  // 其余原样上抛——业务错误的身份必须保留给 rpcFailure 分类  }  // 结束该分支块  if (result === undefined && descriptor.result.mode !== 'strict') return result  // SRC（弱描述符）没声明返回类型：undefined 就是 void，直接放行  return decode(descriptor.result, result, 'result-invalid', endpoint, 'result')  // strict 模式：返回值也要过 schema——出边界前最后一道校验}  // 结束该分支块

private resolveDescriptor(namespace: string, method: string, endpoint: string): InvocationDescriptor {  // 描述符解析：strict 与 SRC 的仲裁点  const strict = this.ctx.typert.local.get(endpoint)  // 先查 strict 生成定义（registry local store）  if (strict !== undefined) return strict  // 在册：直接用，SRC 路径根本不参与  if (this.ctx.typert.local.hasSeen(endpoint)) {  // 该 endpoint 曾经注册过 strict 定义、后来被撤回    throw new TypertGatewayError('definition-unavailable', endpoint, 'its strict definition was withdrawn and SRC fallback is forbidden')  // 禁止降级到 SRC：防止"半严格"状态——要么全 strict，要么明确不可用  }  // 结束该分支块  return this.resolveSrcDescriptor(namespace, method, endpoint)  // 从未见过 strict 定义：走 SRC marker 推导（弱描述符）}  // 结束该分支块

private async resolveParameter(parameter: InvocationParameterDescriptor, args: Readonly<Record<string, unknown>>, endpoint: string): Promise<unknown> {  // 解析单个业务参数：wire 值 → Host 实体  if (!Object.hasOwn(args, parameter.wire)) return undefined  // 字段缺席：只有声明了 T|undefined 的 json 参数能走到这（assertExactArguments 已放行）；lookup id 永不缺席  const value = decode(parameter.codec, args[parameter.wire], 'input-invalid', endpoint, parameter.wire)  // strict codec 先 schema.parse，再断言 JSON-safe——入边界第一道门  if (parameter.source === 'json') return value  // json 参数：解码后直接交给业务方法  const key = parameter.lookup  // lookup 参数的 provider key（strict 必有；SRC 推导时已保证）  if (key === undefined) {  // 防御分支：理论上到不了，到了就是描述符坏了    throw new TypertGatewayError('lookup-unavailable', endpoint, `lookup parameter ${JSON.stringify(parameter.name)} has no provider key`, { field: parameter.wire })  // 报 lookup-unavailable 而不是 TypeError——错误分类稳定可机读  }  // 结束该分支块  const provider = this.ctx.typert.lookups.get(key)  // 从 registry 取 lookup provider（wire id → Host 对象的解析器）  if (provider === undefined) {  // provider 未注册    throw new TypertGatewayError('lookup-unavailable', endpoint, `lookup provider ${JSON.stringify(key)} is unavailable`, { field: parameter.wire })  // 明确报"provider 不在"，调用方知道该去装配而不是重试  }  // 结束该分支块  if (provider.wire !== parameter.wire  // provider 的 wire 字段必须与描述符一致    || (parameter.codec.mode === 'strict' && provider.wireTypeSymbol !== parameter.codec.typeSymbol)) {  // strict 模式还要类型符号对齐——防"同名不同型"的 provider 顶包    throw new TypertGatewayError('provider-mismatch', endpoint, `lookup provider ${JSON.stringify(key)} does not match its strict definition`, { field: parameter.wire })  // 报 provider-mismatch：装配错误，不是数据错误  }  // 结束该分支块  let resolved: unknown  // 解析出的 Host 实体  try {  // 包住 provider.resolve，好区分策略拒绝与 provider 崩溃    resolved = await provider.resolve(value)  // 调 provider：wire id → 活对象（如 agent id → Agent）  } catch (cause) {  // provider 抛错    if (cause instanceof TypertLookupFailure) throw cause  // 策略性拒绝（权限/不存在）保留原身份——它的 typed payload 要原样回给调用方    throw new TypertGatewayError('lookup-failed', endpoint, `lookup provider ${JSON.stringify(key)} failed`, { cause, field: parameter.wire })  // 其余归为 lookup-failed，cause 挂上供诊断  }  // 结束该分支块  if (resolved === undefined) {  // provider 返回 undefined = "查无此 id"    throw new TypertGatewayError('lookup-not-found', endpoint, `lookup provider ${JSON.stringify(key)} did not resolve the requested identity`, { field: parameter.wire })  // lookup-not-found：与 failed（provider 崩了）区分开  }  // 结束该分支块  return resolved  // 返回活对象——业务方法拿到的是真实体，不是 id}  // 结束该分支块

function assertJsonValue(value: unknown, ancestors: Set<object>): void {  // 递归断言一个值"JSON-safe"：能安全过 wire 的充分条件  if (value === null || typeof value === 'string' || typeof value === 'boolean') return  // 标量叶子直接放行  if (typeof value === 'number') {  // number 要单独审    if (Number.isFinite(value)) return  // 有限数 OK    throw new TypeError('non-finite number is not JSON-safe')  // NaN/Infinity 序列化后变 null——静默数据丢失，必须拒绝  }  // 结束该分支块  if (!isObject(value)) throw new TypeError(`${typeof value} is not JSON-safe`)  // function/symbol/bigint：JSON 表示不了，拒  if (ancestors.has(value)) throw new TypeError('cyclic value is not JSON-safe')  // 祖先链里见过 = 循环引用，JSON.stringify 会炸  ancestors.add(value)  // 入栈（递归深度标记）  try {  // 审完子节点后在 finally 里出栈，保证兄弟分支可复用同一对象    if (Array.isArray(value)) {  // 数组分支      if (Object.getOwnPropertySymbols(value).length > 0 || Object.keys(value).length !== value.length) {  // 带 symbol 属性或"键数≠长度"= 稀疏/装饰数组        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')  // 空洞数组：JSON.stringify 输出 null，拒        assertJsonValue(value[index], ancestors)  // 递归审元素      }  // 结束该分支块      return  // 数组审完即返回    }  // 结束该分支块    if (!isPlainObject(value)) throw new TypeError('non-plain object is not JSON-safe')  // class 实例/Date/Map：JSON 表示会变形，拒——wire 上只认 plain object    if (Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('symbol property is not JSON-safe')  // symbol 键序列化直接消失，拒    for (const key of Reflect.ownKeys(value)) {  // 逐属性审      const descriptor = Object.getOwnPropertyDescriptor(value, key)  // 取属性描述符      if (descriptor === undefined || !descriptor.enumerable || !('value' in descriptor)) {  // getter/setter/不可枚举：JSON.stringify 行为不一致，拒        throw new TypeError('non-data property is not JSON-safe')  // wire 边界只接受纯数据属性      }  // 结束该分支块      assertJsonValue(descriptor.value, ancestors)  // 递归审值    }  // 结束该分支块  } finally {  // 无论审查成功还是抛错都要出栈，否则祖先链残留会把后续兄弟误判为环    ancestors.delete(value)  // 出栈：兄弟分支可以合法复用同一对象（DAG），只有真循环才该被拒  }  // 结束该分支块}  // 结束该分支块

return { ok: true, value }  // void/缺席结果没有 value 字段——JSON 没有 undefined，可选槽位就是"缺席"的唯一表示function rpcFailure(error: unknown): ConnectionRpcResult {  // 把任意异常折叠成 wire 错误面  if (error instanceof RemoteInvocationCancelled) {  // carrier 取消：独立语义    return { ok: false, error: { code: 'cancelled', message: error.message, details: {} } }  // code='cancelled'，调用方可据此区分"被取消"与"业务失败"  }  // 结束该分支块  if (error instanceof TypertLookupFailure) {  // lookup 策略拒绝：typed payload 必须原样透传    return { ok: false, error: error.failure as ConnectionRpcError }  // failure 是边界适配器拥有的结构化错误，不折叠成 internal  }  // 结束该分支块  return {  // 其余一切：兜底 internal    ok: false,  // 失败分支标记——与成功分支的 ok:true 互斥    error: { code: 'internal', message: error instanceof Error ? error.message : String(error), details: {} },  // 保留原始 message 供诊断，但不暴露堆栈/内部结构  }  // 结束该分支块}  // 结束该分支块

const resolveArtifact = (pkgName: string): string | null => {  // 包名 → ./typert artifact 路径（带缓存）  const cached = artifactPath.get(pkgName)  // 命中缓存直接返回——负判定也缓存，永不重试  if (cached !== undefined) return cached  // 插件集变更靠重启生效，运行期不追  let pkgPath: string  // package.json 的绝对路径  try {  // 解析包根；loader builtin（cordis:include）/子路径会在这里失败    pkgPath = require.resolve(`${pkgName}/package.json`)  // 解析包根；loader builtin（cordis:include）/子路径会在这里失败  } catch (cause) {  // 解析不到    if (configured.has(pkgName)) {  // 但它是用户显式配置的包      throw new Error(`typert-loader: configured package "${pkgName}" cannot be resolved from the config tree — add it to the composition package dependencies or remove it from packages`)  // 显式配置必须响亮失败，错误信息直接给出修法    }  // 结束该分支块    artifactPath.set(pkgName, null)  // 隐式发现的：记负判定，永久跳过    return null  // 不是 typert contributor  }  // 结束该分支块  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as Record<string, unknown>  // 读 package.json  const rel = typertExportOf(pkgName, pkg.exports)  // 取 exports["./typert"]（支持字符串和一层条件对象两种形态）  if (rel === undefined && configured.has(pkgName)) {  // 显式配置却没导出 ./typert    throw new Error(`typert-loader: configured package "${pkgName}" does not export "./typert"`)  // fail loud：配置了就必须有 artifact  }  // 结束该分支块  const resolved = rel === undefined ? null : join(dirname(pkgPath), rel)  // 拼出 artifact 绝对路径  artifactPath.set(pkgName, resolved)  // 缓存（含负判定）  return resolved  // 交给 loadManifest 动态 import + 校验}  // 结束该分支块

ctx.on('internal/plugin', (fiber) => {  // 监听插件挂载事件：每个 entry 的 fiber 激活都算一次"脏"  const entryName = fiber.entry?.options.name  // 取 loader entry 名；无 entry 的 fiber（子插件/手动挂载）不是 loader 行，O(1) 丢弃  if (entryName === undefined) return  // 直接返回  dirty.add(entryName)  // 标记脏——Set 幂等，重复事件无害  if (flushQueued) return  // 已有微任务在排队：不重复排  flushQueued = true  // 置位防抖标志  queueMicrotask(() => {  // 微任务批量处理：同一 tick 内多个挂载只触发一次扫描    flushQueued = false  // 清标志    if (!active) return  // 插件已卸载：不再工作    for (const task of flush((err) => { ctx.logger.error(err) })) void task  // 逐个 entry 对账；稳态下单包损坏只记日志，不毒化其他包  })})for (const packageName of configured) dirty.add(packageName)  // 激活路径：显式配置的包先入脏集for (const entry of ctx.loader.entries()) dirty.add(entry.options.name)  // 再灌入当前全部 loader entries——初始扫描就是增量路径的特例const failures: Error[] = []  // 收集激活期失败await Promise.all(flush((err) => { failures.push(err) }))  // 并发处理所有脏 entry，等齐if (failures.length > 0) {  // 有失败  throw new AggregateError(  // 聚合成一个错误抛出——loader fiber FAILED，boot sweep 会报告    failures,  // 把每个失败包的原因都带上，一次看全而不是只看到第一个    `typert-loader: ${String(failures.length)} typert contributor(s) failed to register:\n${failures.map(e => `  - ${e.message}`).join('\n')}`,  // 逐条列出：哪个包、什么错，一次看全  )}  // 结束该分支块

调用路径（Client → Host）

▼

▼

▼

▼

▼