04 · chord — 应用组合运行时

包路径：packages/chord（registry 名 @earendil-works/chord） 定位：独立的"应用组合运行时"——服务（RPC）、复制状态（replicated state）、facet（切面）、插件（bundle）、不可变 delta（CRDT 风格）。被 pi-durable 与 pi-coding-agent 当作底座使用。 配套：src/delta/README.md（delta 设计说明）。

1. 目录结构与关键文件（30 个 src 文件）

目录 / 文件	作用
src/index.ts	导出：defineService / defineFacet / createFacetHost / replicatedState / combineFacetLoaders / createRemoteServiceBinding 等
src/api.ts	公共 API 装配
src/types.ts	Context / Service / ReplicatedState / Facet / JsonValue 等核心类型
src/json.ts	copyJson / isJsonValue（JSON 深拷贝与类型守卫）
src/node/*	node.ts（运行单元）/ bundle.ts / manifest.ts / package.ts / bundle-loader.ts
src/services/*	服务与 RPC：provider.ts（远端服务端点）/ state-codec.ts（状态编解码）/ wire.ts（catalogue/subscribe/unsubscribe 线协议）/ consumer.ts / handle.ts / instances.ts / loopback.ts / state.ts / errors.ts
src/delta/*	不可变 delta：track / diff / draft / apply-immutable-trusted / revision-validator / tracker / index
src/facets/*	host.ts / loader.ts（facet 加载与宿主）
src/context/*	BackgroundContext 等上下文原语

2. 四大支柱

(1) Replicated State（复制状态）

replicatedState(source) 把一个"源"（如 chord 内部已提交状态）包装成可观察、可推进的 ReplicatedState。src/services/state.ts 的 StateSubscriber 是订阅实现：

• 每个订阅独立推进，互不阻塞（背压：pending 超过 100 帧时丢弃非首帧，避免冷副本重入堆积）。
• 每次交付带 Context 与 ReplicatedStateDelivery（来源/版本等元信息）。
• drain() 串行消费 pending 帧；listener 返回 Promise 时异步继续。

这是 Pi 跨进程/跨会话共享状态的基础（如 TUI 渲染、多面板同步）。

(2) Services & RPC（services/*）

• defineService 定义一个可被远程调用的服务；createRemoteServiceEndpoint / RemoteServiceProvider 暴露端点。
• wire.ts 定义线协议：createServiceCatalogueCall / createServiceSubscribeCall / createServiceUnsubscribeCall / 各类 parseWire*（catalogue、provider update、subscription snapshot）。
• state-codec.ts：服务状态的编码器/解码器（createServiceStateEncoder/Decoder）。
• errors.ts：RemoteServiceError 与错误码（isRemoteServiceErrorCode / REMOTE_SERVICE_ERROR_CODES）。
• loopback.ts：本进程内环回绑定；consumer.ts / instances.ts：消费端与实例管理。

(3) Delta（delta/*）

chord 的状态变更走不可变 delta：

• track(value) 创建一个带 tracker 的可追踪值。
• diff / draft：计算差异 / 生成草稿。
• apply-immutable-trusted.ts：以不可变、可信方式应用 delta。
• revision-validator.ts（JsonRevisionValidator）：校验 delta 修订版本，防止乱序/冲突。
• tracker.ts：维护值与增量。

durable 的文档观察（observedOperations 返回 Op[]）正是基于这套 delta。

(4) Facets & Bundles（facets/* / node/*）

• defineFacet + createFacetHost：把能力（facet）挂载到宿主；combineFacetLoaders / createStaticFacetLoader 组合加载器。
• node/bundle.ts / manifest.ts / package.ts / bundle-loader.ts：把一组服务/facet 打包成可分发、可加载的"bundle"（对应 Pi 的扩展包机制）。

3. 与上下层的关系

pi-coding-agent ──┐
pi-durable ───────┼──► chord（服务/RPC + 复制状态 + delta + facet/bundle）
pi-(其他) ────────┘

• pi-durable 用 chord 的 replicatedState / track / Context 实现文档观察与回放。
• pi-coding-agent 用 chord 的 bundle/facet 机制加载扩展，用 service 做进程间/面板间通信。

4. 阅读清单

1. src/index.ts —— 看清四大能力的导出。
2. src/delta/README.md —— delta 设计意图（必读）。
3. src/services/state.ts —— StateSubscriber 与复制状态交付语义。
4. src/services/wire.ts + state-codec.ts —— 线协议与状态编解码。
5. src/delta/track.ts + revision-validator.ts —— 不可变 delta 与版本校验。
6. src/facets/host.ts + node/bundle.ts —— facet 宿主与 bundle 打包。

5. 自测

• replicatedState 的订阅者之间为什么互不影响？背压策略是什么？
• chord 的 delta 与 git 的 diff/patch 在"不可变/可信/版本校验"上有何相似？
• 一个 Pi 扩展（package）在 chord 视角下对应什么概念（bundle / facet / service）？