chord@earendil-works/chord

要点Key points

• 最大的单个文件是 delta/tracker.ts：它让提供方像改普通对象一样改状态（Draft 代理），再算出 op。The largest single file is delta/tracker.ts: it lets a provider change state like a plain object (a Draft proxy) and then computes the ops.
• ./delta 和 ./context 可以单独使用，不需要 facet 宿主；./bundler 与 ./node 只在 Node 上需要。./delta and ./context work on their own without the facet host; ./bundler and ./node are only needed on Node.
• durable 是最大的使用者：它的 viewState()、watch() 和任务图都是 chord 的复制状态，每次异步调用都带一个 chord Context。durable is the biggest user: its viewState(), watch() and task graph are chord replicated states, and every async call takes a chord Context.

工作原理How it works

1. defineService<T>(id) 定义令牌，defineFacet({ id, setup }) 定义功能单元。defineService<T>(id) defines a token, defineFacet({ id, setup }) a unit of functionality.
2. createFacetHost({ facets, serviceSources? }) 装配并激活，返回 { services, reload, dispose }。createFacetHost({ facets, serviceSources? }) assembles and activates, returning { services, reload, dispose }.
3. 跨进程时，一边 createRemoteServiceEndpoint(provider)，另一边 createRemoteServiceBinding({ transport, … })。Across processes, one side uses createRemoteServiceEndpoint(provider) and the other createRemoteServiceBinding({ transport, … }).

要点Key points

• setup 必须同步：返回 Promise 会被拒绝。这让依赖图在任何异步工作开始前就是完整、可校验的。setup must be synchronous: returning a Promise is rejected. That makes the dependency graph complete and checkable before any async work starts.
• 校验错误都带着服务和 facet 的名字："is provided by both …"、"… but no facet provides it"、"Facet dependency cycle: …"。Validation errors name the service and facets: "is provided by both …", "… but no facet provides it", "Facet dependency cycle: …".
• 任何一步失败，#terminate() 释放已经建好的部分，把原错误和清理错误合成一个 AggregateError 抛出。If any step fails, #terminate() disposes what was built and throws the original error together with cleanup errors as one AggregateError.
• 每个 facet 内部，own() 登记的释放函数也按逆序执行——后建的先拆。Within each facet, the disposals registered with own() also run in reverse — last built, first torn down.

工作原理How it works

1. FacetKernel.activate()：对每个 facet 调 setup，得到 FacetShape（requires / provides）。FacetKernel.activate(): call setup for each facet to get its FacetShape (requires / provides).
2. #resolveExternalServices() 读宿主的 serviceSources 目录 → validateFacets() → topologicalOrder()。#resolveExternalServices() reads the host's serviceSources catalogues → validateFacets() → topologicalOrder().
3. 绑定服务 → 等待 ready() → 按 #activationOrder 逐个 activate()。Bind services → await ready() → activate() each facet in #activationOrder.

要点Key points

• 形状不变是硬性要求：重载不能增删依赖或提供的服务（"must preserve its service requirements and provisions"）。改形状需要新的一代。Unchanged shape is a hard rule: a reload cannot add or remove dependencies or provisions ("must preserve its service requirements and provisions"). Changing the shape needs a new generation.
• 切换之前失败：释放候选，宿主回到 active，旧实现继续工作。切换之后失败：整个代被中止（"Facet reload failed after cutover"）。A failure before the cutover disposes the candidates and returns to active with the old code still working. After the cutover, the whole generation is aborted ("Facet reload failed after cutover").
• 句柄是代理：每次访问都通过 ServiceSlot.resolve() 取当前实现，所以重新 bind 之后已有句柄立即用上新代码。Handles are proxies: every access resolves the current implementation through ServiceSlot.resolve(), so after a rebind existing handles use the new code immediately.
• keyed 实例按 generation 区分：重载后旧实例关闭，新实例以新的 generation 出现，观察者会看到 closed 再 spawned。Keyed instances are generation-specific: after a reload the old ones close and new ones appear with new generations, so observers see closed then spawned.

工作原理How it works

1. 宿主先用 loader 的 load() 拿到候选的 LoadedFacets。The host first gets the candidate LoadedFacets from a loader's load().
2. host.reload(loaded.facets)；失败就释放候选。host.reload(loaded.facets); on failure, dispose the candidate.
3. 成功后再释放退役的那一代 LoadedFacets，旧代码随之可以被回收。After success, dispose the retired LoadedFacets, so the old code can be collected.

要点Key points

• 远程约束在类型层面检查（RemoteServiceContract<T>），运行时在边界上再校验一次（validateRemoteServiceImplementation）。The remote constraint is checked in the type system (RemoteServiceContract<T>) and again at runtime at the boundary (validateRemoteServiceImplementation).
• coding-agent 的实验服务就是例子：pi.transcript 只有一个 state: ReplicatedState<ConversationView>；pi.local.presentation-ui 是本地服务。coding-agent's experimental services are examples: pi.transcript has just state: ReplicatedState<ConversationView>; pi.local.presentation-ui is a local service.
• 每个调用最后一个参数都是 Context：它携带取消信号和调用范围的值。awaitWithContext() 取消时只拒绝等待者，不会中止正在进行的工作。Every call's last argument is a Context: it carries cancellation and call-scoped values. awaitWithContext() on cancellation rejects only the waiter, never the work in progress.
• ID 以 $chord. 开头的服务是保留的：那是 chord 自己的控制调用。Service IDs starting with $chord. are reserved: that prefix is chord's own control calls.

工作原理How it works

1. export const Models = defineService<Models>("pi.models")——类型和令牌同名。export const Models = defineService<Models>("pi.models") — the type and the token share a name.
2. 在 facet 的 setup 里：const models = env.use(Models)；在 onActivate 或之后调用 await models.select(m, ctx)。In a facet's setup: const models = env.use(Models); from onActivate on, call await models.select(m, ctx).
3. 取消：const { context, cancel } = withCancel(parent)，把 context 传下去。Cancellation: const { context, cancel } = withCancel(parent) and pass context down.

要点Key points

• 订阅更新有 6 种：state（某成员的一批 op）、reset、unavailable、replaced、spawned、closed。Subscription updates come in 6 kinds: state (a batch of ops for one member), reset, unavailable, replaced, spawned, closed.
• 背压：每个订阅最多 100 个待发更新；第 101 个到来时整个队列换成一个 reset，带着当前完整快照和新的 sequence 基线。Backpressure: at most 100 pending updates per subscription; when the 101st arrives the whole queue becomes one reset with a full current snapshot and new sequence baselines.
• 普通 state 更新绝不允许跳号；传输适配器必须保持快照 / reset / 更新的顺序，不能丢批。An ordinary state update never permits a gap; transport adapters must keep snapshot / reset / update order and must not drop batches.
• 能跨边界的错误只有 8 个 service_* 码，例如 service_not_found、service_stale_instance、service_invalid_value。Only 8 service_* codes may cross the boundary, e.g. service_not_found, service_stale_instance, service_invalid_value.

工作原理How it works

1. 提供方：用宿主的 provider 创建 createRemoteServiceEndpoint(provider)，把收到的调用交给它。Provider: create createRemoteServiceEndpoint(provider) from the host's provider and hand it incoming calls.
2. 使用方：实现 RemoteServiceTransport；再实现一个 RemoteServiceSource（catalogue() + open()），在 open() 里用 createRemoteServiceBinding({ services, transport })，作为宿主的 serviceSources 传入——coding-agent 的 experimental/services/connection.ts 就是这样做的。Consumer: implement RemoteServiceTransport; then a RemoteServiceSource (catalogue() + open()) whose open() uses createRemoteServiceBinding({ services, transport }), passed to the host in serviceSources — as coding-agent's experimental/services/connection.ts does.
3. 同进程测试：createLoopbackServiceTransport(provider) 直接把两边接起来。In-process tests: createLoopbackServiceTransport(provider) wires both sides directly.

要点Key points

• 一次 change() 恰好发布一个原子版本；回调抛错时值和 sequence 都不变；没有产生 op 就不发布。A successful change() publishes exactly one atomic revision; if the callback throws, value and sequence stay unchanged; no ops, no publication.
• 回调必须同步，也不能在回调里再次 change（"cannot be changed reentrantly"）。The callback must be synchronous and cannot change the state again from inside ("cannot be changed reentrantly").
• 公开订阅最多积压 100 个值，溢出时只留最新的——所以公开的 sequence 可能跳号；异步回调里应读捕获的 value 而不是 state.value。Public subscriptions keep at most 100 pending values and keep only the newest on overflow — so public sequences may skip; async callbacks should read the captured value, not state.value.
• 远端副本严格按序：update 要求 sequence 正好是上一个加一，否则清空并抛出 "update sequence has a gap"。The remote replica is strictly ordered: update requires exactly the previous sequence plus one, else it clears and throws "update sequence has a gap".

工作原理How it works

1. status.change(ctx, d => { d.output += "done\n"; d.count += 1 })。status.change(ctx, d => { d.output += "done\n"; d.count += 1 }).
2. 内部：tracker.beginChange() → 回调 → prepare() → adopt() → publisher.publish(value, ops, ctx)。Internally: tracker.beginChange() → callback → prepare() → adopt() → publisher.publish(value, ops, ctx).
3. 远端：ReplicatedStateReplica.hydrate(seq, ops) 建立基线，之后每个 update(seq, ops) 用 applyImmutable 重放。Remote: ReplicatedStateReplica.hydrate(seq, ops) sets the baseline, then each update(seq, ops) replays with applyImmutable.

要点Key points

• 超过 4,096 个 op 时折叠成 ["r", 整个根]；去头 + 追加的重叠扫描最多 65,536 个字符。More than 4,096 ops fold into ["r", whole root]; the truncate-plus-append overlap scan covers up to 65,536 characters.
• 路径在第二次使用时才定义编号（["#", id, path]），因为定义比路径本身还长，只用一次的路径内联更省。A path gets an id on its second use (["#", id, path]), because a definition costs more than the path; paths used once stay inline.
• 省略路径只在同一批内有效；跨批的唯一状态是编号字典，遇到 r 就清空——每个 r 都是一个恢复点。Omitted paths only work within a batch; the only cross-batch state is the id dictionary, cleared at every r — each r is a recovery point.
• 值是不可变、结构共享的：没变的子树在版本之间共用，不做防御性拷贝也不冻结。Values are immutable and structurally shared: unchanged subtrees are reused across revisions, with no defensive copies and no freezing.

工作原理How it works

1. const tracker = track(initial)；const change = tracker.beginChange()；改 change.state。const tracker = track(initial); const change = tracker.beginChange(); mutate change.state.
2. const prepared = change.prepare()；tracker.adopt(prepared)；副本用 applyImmutable(prepared.base, prepared.ops)。const prepared = change.prepare(); tracker.adopt(prepared); a replica uses applyImmutable(prepared.base, prepared.ops).
3. 跨边界：encoder().encode(ops) → 发送 → decoder().decode(wire)。Across a boundary: encoder().encode(ops) → send → decoder().decode(wire).

要点Key points

• 输出先写到临时目录，再整体改名替换；旧目录先挪到 .old-<uuid>，替换失败就挪回来——加载方永远看不到写了一半的包。Output goes to a temporary directory and is renamed into place; the old directory is moved to .old-<uuid> first and moved back if the swap fails — a loader never sees a half-written bundle.
• 入口文件名带内容哈希（facet-<短哈希>-[hash].cjs），不同版本不会互相覆盖。Entry file names carry content hashes (facet-<short hash>-[hash].cjs), so versions never overwrite each other.
• 也可以把整个包读成一个 artifact（readFacetBundleArtifact）再加载，适合把插件作为一个值传递。A bundle can also be read as one artifact (readFacetBundleArtifact) and loaded from that, handy for passing a plugin around as one value.

工作原理How it works

1. 构建：bundleFacetPackage({ packagePath, outdir })。Build: bundleFacetPackage({ packagePath, outdir }).
2. 加载：createFacetBundleLoader({ manifestPath, entry, resolveExternal? }) → load() 得到 LoadedFacets；完整性校验默认开启（verifyIntegrity）。Load: createFacetBundleLoader({ manifestPath, entry, resolveExternal? }) → load() gives LoadedFacets; the integrity check is on by default (verifyIntegrity).
3. 交给 host.reload(loaded.facets) 热替换，或作为新一代的 facets。Hand them to host.reload(loaded.facets) for a hot swap, or use them for a new generation.