Pi Agent 源码级教程
M12

对象与热重载 —— 改代码为什么不用重启

10,615 字 · 含 334 行代码 · 约 47 分钟

凌晨两点,线上有 400 个会话开着。

你刚修完一个分词器的 bug,一行改动,改完了。Ctrl-C。四个 worker 进程重启,十几秒里所有会话的 WebSocket 断开,前端显示"连接已丢失",用户明天早上会看到一堆中断的对话。于是"先发布吧,明天再修"成了常态。

真正难的不是改代码。是改代码时不把状态弄丢。

你的会话对象内存里有两样东西:一份对话历史(数据),一个分词器实例(代码)。前者属于用户,不能丢;后者属于你的这次提交,需要换。这两样东西现在死绑在同一个进程里,所以换一个必须重启另一个。

chord 做的就是把这根绑线剪断。剪断之后,换代码不需要换对象,换对象不需要停服务。它的 README 三句话就是这件事的全貌:

Chord builds applications out of objects that live in several processes (a server, workers, browser tabs) and can be hot reloaded while they run.

对象、多进程、热重载。三者不是并列关系——前两个是第三个的前提。

只有当"对象"和"调用它的代码"分开住,换代码才不需要换对象; 只有当"状态"和"状态的所有者"分开住,换代码才不需要停服务。

50,101 行,216 个文件。这是仓库里最大的包,也是 durable 唯一非可选的依赖。

接着 M11 往下说:那边用 generation 交接,让旧循环把控制权交给新循环; chord 的 reload 是同一件事的另一种实现——换代码,不换状态。

先给结论,好在细节里找不到方向:整个包的努力都花在一件事上—— 让"引用"活得比"实现"长。 对象可以死,实现可以换,但调用方手里那个引用必须一直是有效的。 下面每一个设计,都是在为这句话补漏洞。


零、读这章之前,你需要先知道四件事

这四个词读源码时绕不开,但它们都不是和弦自己的发明,而是分布式系统里的通用概念:

租约(lease):不是"永久占有",而是先签一段时间的使用权,到期自动失效。 两阶段提交:先"准备"(谁都能反悔),再"提交"(不可反悔)。 幂等:同一个请求发两次,结果和发一次一样。 祖父亲条款:老的不动,新的按新规矩。

没有它们会怎样:把热重载当成"重启进程",于是看不懂为什么正在跑的请求没被杀掉—— 它们靠的是"新旧两个版本同时活一会儿",不是靠杀进程。

本书哪里用到:§一 五个词(本章自己的术语),§七 提交协议。


一、五个词

先把术语钉死,后面全部靠它们。这五个词里只有一个(reload)是 chord 自己发明的。

词 一句话 落在哪
object 一个地址上的状态 + 代码,按需创建 object.ts(1,932)
reference 调用方拿到的永远是引用,不是对象 RefImpl(object.ts:759)
principal 每个对象知道自己在为谁服务 ctx.principal
state 可观察的 JSON:先快照,后增量 state.ts(424) + delta/
reload 换代码,不换状态,不停服务 reload.ts(724)

README 里还有一句容易被跳过的话,它其实是这五个词的总纲:

Everyone gets a reference, never the object. References work the same locally and across processes, and survive reloads.

"survive reloads"——引用能活过一次热重载。这句话是整章要解释的东西。

1.1 它和 Actor 差在哪

长得像 Actor:有地址、有状态、有消息。差别在两处,都很关键:

  • Actor 的方法调用是消息,发出去就不保证回。chord 的方法调用是 await,有返回值、 有异常、有取消。
  • Actor 的代码是固定的。chord 的对象在自己的生命周期里可以换三次代码。

第一处让它能当普通 API 用;第二处让它能在生产环境里改自己。

把三个参照物摆在旁边,位置就清楚了:

普通 RPC 框架 插件宿主 chord
调用形状 函数调用 不提供 函数调用
状态归谁 服务端私有 — 对象自己,可订阅
换代码 重启 重启宿主 不重启
跨进程 是 — 是,同一套引用

第二行和第三行是它真正的差异:状态是公开可观察的,并且不跟着代码版本走。

1.2 durable 站在哪一层

M11 说过 durable 的 storage/store/ 是两个 SQL 后端共享的一层。那一层不是它自己写的:

ts
// durable/src/storage/store/storage.ts:14-15} from "@earendil-works/chord/next";import type { SqliteExecutor } from "@earendil-works/chord/sqlite";

commit.ts / documents.ts / queries.ts / tables.ts 四个文件都从 chord/next 拿东西。 所以层级是:

text
durable 的调度器与任务   |   +-> durable 的 storage/store/(文档表、提交、查询)         |         +-> chord/next 的 store(文档寻址、历史、退休)               |               +-> chord/sqlite(可移植的 SqliteDatabase)

chord 不是"又一个库",是 durable 的地基。 M11 讲的那套提交语义, 最后是这一层的 SQL 在保证。


二、包的地图

chord/src/ 216 个文件 / 50,101 行,按目录切:

目录 文件 行数 是什么
根层 25 10,438 v1 API:对象、契约、主机、热重载、链路
next/ 146 28,733 v2(实验):契约、文档、存储、任务、状态
next-node/ 29 5,743 v2 的 Node 侧实现
delta/ 7 3,976 事务性 JSON 跟踪器与线格式
telemetry-sqlite/ 2 536 遥测的 SQLite 落盘
sqlite/ 6 513 可移植的 SqliteDatabase
context/ 1 162 取消、遥测、调用值

注意最后两行的对比:sqlite/ 只有 513 行,telemetry-sqlite/ 536 行。 一个包里的"存储抽象"可以比"存储的实现"还小——因为真正的实现挂在 peer 依赖上。

2.1 v1 根层的七个大文件

文件 行 职责
object.ts 1,932 对象、引用、生命周期、闸门
connection.ts 1,328 一条链路上的引用、调用、状态单元
host.ts 1,306 主机:服务表、代码版本、根、插件
reload.ts 724 一次热重载的 prepare / gate / commit
remote.ts 659 远端引用的代理与转发
watch.ts 493 可观察值的订阅与快照
manager.ts 444 子主机进程的托管

object.ts 一个人占了根层的 18%。它不只是"对象",是引用的生命周期账本—— 后面 §三 会看到,一个 ObjectImpl 上有六种引用持有者。

2.2 next/ 是什么

src/next/index.ts 第一行就写了:

ts
// Chord v2 (`@earendil-works/chord/next`, experimental): every layer's API// for apps, and the store's surface for adapters (Durable's `StoreStorage`),// marked internal.

v2 是"文档 + 存储"的重写,v1 是"对象 + 热重载"。两者并存,通过不同的导出路径区分:

ts
// package.json 的 exports(节选)".":              v1 顶层"./next":         v2"./delta":        独立导出"./sqlite":       可移植 SQLite

九个 v2 子目录,行数分布很不均匀:

子目录 文件 行数
host/ 31 8,846
store/ 34 6,117
jobs/ 10 2,495
documents/ 13 2,222
link/ 12 2,052
contracts/ 13 1,835
state/ 7 991
registries/ 7 853
data/ 8 574

store/ 就是 M11 §5.7 那次提交的落点。它和 v1 的 object.ts 几乎一样重, 说明在 v2 里"文档与提交"取代了"对象与引用"成了中心。

本章讲 v1——因为"改代码不用重启"是 v1 的能力,v2 还没接上热重载。 v2 只在 §九 和 §13.2 出现。


三、object:地址 + 状态 + 代码

3.1 一个对象是怎么被定义的

契约先写,实现在后。contract.ts 的 remote 描述"这个类型长什么样、住在哪台主机":

ts
// contract.ts:214-247(签名节选)export function remote<const D extends RemoteDef>(	name: string,	def: D,): RemoteContract<D>;

RemoteDef 有四个必填部分(contract.ts:102-108):

字段 作用
version 契约版本,用于兼容性判定
input 创建对象时的输入 schema,也决定它住在哪台主机
host hostNamed("server") 或 hostFamily("session:", "session")
variants 变体表,每个变体有自己的 state 与 methods

实现挂在主机上(host.ts 的 serve)。同一个契约,不同的主机可以给出完全不同的实现—— 因为 host 字段决定了"这个类型的对象只在某台主机上创建"。

hostFamily 更细:它按输入里的某个字符串字段路由。

ts
// contract.ts:72-76export function hostFamily<const K extends string>(	prefix: string,	key: K,): HostFamily<K>;

hostFamily("session:", "session") 的意思是:输入里的 session 字段是 "abc", 这个对象就住在 session:abc 这台主机上。前缀 + 输入字段 = 主机名,纯数据推导, 所以每台主机都能独立算出"这个对象该不该归我"(resolveHost,contract.ts:84)。

3.2 self:工厂能声明的五样东西

工厂的第二个参数是 self,它是唯一能"声明"的入口。Self 接口(object.ts:155-197) 有五个方法,每个都用"重载时要怎么处理"来定义:

方法 声明什么 重载时
state(name, schema, init) 一个可观察的 cell 保留值(升版则迁移)
derive(...) 一个同步投影 每次重建
resource(...) 一个依赖(文件、连接) 保留,exclusive 则替换
on(...) 一个订阅 重新订阅
task(...) 长期工作 重启

三行"每次重建"、"重新订阅"、"重启",两行保留。这条分界线不是随意的:

  • 状态是数据。数据没有代码版本,只有语义版本。所以它跳代。
  • 派生是投影。用新代码重算一遍最准;保留旧值反而可能和新的输入对不上。
  • 订阅是连接。旧监听器闭包着旧代码,必须换掉。
  • 任务是动作。让旧代码的动作继续跑,等于没重载。

换成一句话:跨代的是数据与外部句柄,不跨代的是行为。

resource 那一行的例外很关键——exclusive: true 的资源(比如一个写锁)不能两代共用, 必须等闸门。这就是 §6.2 里第二种进闸门的理由。

3.3 引用不是对象

这是全章第一个反直觉的点。调用方手里的那个东西是个 Proxy:

ts
// object.ts:758-759/** One reference on an object. Exposed through a Proxy so members * bind late to the current implementation. */export class RefImpl {

注释里 "bind late to the current implementation" 是热重载能工作的第一个前提。 把这句话拆开:

  • 引用上存的是地址,不是函数指针。
  • 每次调 ref.increment(...),代理才去问"这个地址现在由哪份代码实现"。
  • 所以换掉实现之后,同一个引用下一次调用的就是新代码。

如果引用在创建时就抓住了 increment 的函数对象,热重载就必须重新分发所有引用—— 那就等于重启。

引用的解引用还有一层:bind(contract.ts:321)在"消费者契约"和"提供者实现"之间 插适配器。所以引用不是直接拿到实现,而是拿到"按我的契约版本翻译过的视图"(object.ts:880)。

3.4 principal:同一个地址,两个对象

README 说:

Every object knows its principal: an owner and a guest get different objects, with different methods.

这句话容易被当成权限校验。它比权限更强:owner 和 guest 拿到的是两个不同的对象实例, 只是共用一个地址。各自的工厂调用会收到不同的 principal,返回不同的变体。

ts
// contract.ts:417-424(节选)export type ImplementationOf<C, P = unknown> =	C extends RemoteContract<infer D> ? ... : never;

infer D 是条件类型里"就地取一个类型变量"的写法:句子读作"如果 C 长得像 RemoteContract<D>,就把那个 D 记下来"。读源码时见到 infer,后面跟的一定是 一个待推导的名字。

与 as 的差别:infer 是从结构反推,推不出来就落到 never,编译器替你算; as 是你向编译器断言,真错了也没人拦,运行时才炸。附录 B §2.5 有对比。

P 就是应用自己定义的 principal 类型。factory 的签名里它是个参数(object.ts:78), 于是"给谁创建"是一个构造期的输入,不是每次调用都重新判断的运行时检查。

好处很直接:owner 看到的方法集可以比 guest 多,而且多出来的方法在 guest 那侧根本不存在—— 不是调了被拒绝,是代理上就没有这个成员。

3.5 生命周期:谁还拿着引用

Lifetime 只有两个值(object.ts:75):

值 含义
"referenced" 没有引用就回收,回收前还能再等 linger 毫秒
"host" 和主机同生共死,永不回收

linger(object.ts:51)是给"引用刚放掉、马上又要"的场景留的缓冲。 默认值由服务选项决定,不是硬编码。

真正复杂的是谁在持有引用。RefOwner 有六种(object.ts:560):

owner 谁 会不会挡住热重载的闸门
"object" 另一个对象 会
"call" 一次正在进行的调用 会
"host" 主机自己 会
"external" 宿主代码直接持有 会
"connection" 另一台主机 会(集群一起重载)
"client" 浏览器 不会

最后一行是 §六 的关键:浏览器的引用不阻塞热重载。它拿不到新代码, 提交之后会被标成 upgrade_required,让前端自己决定刷新。

这一条是整个设计里最尖锐的取舍,值得单独说清楚。

你可能会想: 既然如此,为什么浏览器不能像服务端引用一样, 重新绑定到新提供方就行?

因为服务端的"重新绑定"有一份同一代代码的主机做中介:新实现就在这台 主机的模块表里,重绑只是一次查表。而浏览器里跑的是你打包发过去的那份代码, 它在 commit 之前就已经下载完毕、已经实例化。主机换了代码,浏览器手里的 Proxy 也找不到对应物——重绑过去也只能绑到旧代码的拷贝。

那让它阻塞闸门呢? 那就是另一条路:浏览器不刷新,重载就不提交。 代价是热重载变成"必须所有标签页都关闭"——很多用户把标签页开着过夜。

reload.ts:424-427 的注释把结论说死了:

ts
/** * Every reference that survives into the new code version must bind to * the new provider. Browser references don't block a reload: after the * commit they get `upgrade_required` instead. */

"don't block" 和 "get upgrade_required instead" 是同一个决定的两半: 服务端的连续性,优先于客户端的连续性。 客户端被告知世界变了, 但服务端永远不用为了一个没关的标签页而停在旧代码上。

这也是一个值得抄走的模式:遇到"远端无法跟随"的情况, 不要让远端阻塞本地——给它一个可识别的错误码,让它自己决定何时追上。 错误码的名字里已经包含了这条设计意旨:upgrade_required,不是 upgrade_failed。

一个对象什么时候死?object.ts:1645 的注释写得很短: "No references and no invocations: dispose (after linger for a live object)." 两个条件同时成立才回收——没有引用,而且没有正在跑的调用。 少一个都不行,因为"引用放掉了"和"活干完了"是两件事。

3.6 根:租约的来源

上面那张表里的 "call" / "host" / "external",在代码里全都统一成一个概念:租约。 object.ts:1045 有一行不起眼但承重的字段:

ts
readonly leases = new Map<string, number>();

key 是根 id,value 是代码版本号。 一行同时回答了"谁还拿着"和"他手里是第几代代码"。

登记发生在一次调用的入口(object.ts:1533-1542):

ts
if (this.gate !== undefined && !this.gate.grandfathered.has(ctx.rootId)) {	// 闸门开着且你不是祖父:排队}if (this.leases.has(ctx.rootId)) return;this.leases.set(ctx.rootId, ctx.codeVersion);this.host.touch(ctx.rootId, this);

"根"就是 host.root(async (ctx) => { ... }) 那个作用域。它结束的时候, 沿途碰过的所有对象的租约一起释放(object.ts:1627-1630):

ts
rootEnded(rootId: string): void {	this.leases.delete(rootId);	// ...	if (gate?.grandfathered.delete(rootId)		&& gate.grandfathered.size === 0) gate.drained();}

最后一行把 §6.3 的闸门闭环了:每个旧租约释放时,都在检查是不是最后一个。

跨进程的根要多一步。call 帧带着它(wire.ts:132-133):

ts
/** Absent: the receiving host starts a root (browsers never carry roots). */root: opt(RootRefSchema),

root_end 帧负责收工(wire.ts:163-164):

ts
/** The root ended at its origin: its leases on objects end * (sent on every link the root's calls used). */Open({ t: lit("root_end"), rootId: Name }),

"sent on every link the root's calls used"——根得在它走过的每一条链路上各通知一遍。 因为租约是分散在多台主机上的,没有任何一条链路知道全部。

还有一个例外(object.ts:1550):

ts
if (ctx.rootId.startsWith("task:")) return;

任务的根不登记租约。 因为它们会被 stopTasks() 直接停掉(§6.3), 用租约挡只会让闸门等一个不会自己结束的根。

于是"引用能活过重载"可以拆成三层,每层一个机制:

层 靠什么
引用不失效 引用存地址,成员晚期绑定(§3.3)
对象不销毁 有租约在,就不算"无人引用"
闸门知道等谁 租约的 key 就是根,value 是代码版本(§6.3)

四、state:可观察的 JSON

状态不是"字段",是"订阅源"。区别在于:读字段不会告诉你它变了,订阅会。

4.1 一个 cell 是怎么声明的

ts
// README 的 Quick start(节选)const count = self.state("count", num(), 0);

三个参数:名字、schema、初值。self.state 返回的东西能读、能改、能订阅。 它的选项里有一个容易被忽略的字段(object.ts:133-137):

ts
export interface StateOptions<T> {	/** The meaning of the cell's value (default 1).	 * A reload that raises it runs `migrate`. */	version?: number;	...}

version 是"这个值的语义版本",不是包版本、不是契约版本。默认 1。

§六 会看到它为什么存在:热重载时,只有 version 提高了的 cell 才需要迁移和闸门。 一个改了方法体、没改状态语义的 reload,根本不需要迁移。

4.2 快照 + 增量

远端看到的状态是两段式:先一个 snapshot,然后是一串 ops。

ts
// wire.ts:148-158Open({	t: lit("state"),	hold: Id,	m: Name,	/** `snap`/`reset` without `value`: the value is `undefined`. */	as: union([lit("snap"), lit("reset"), lit("ops"), lit("error")]),	value: opt(unknown()),	/** Encoded with the stream's delta encoder; the decoder	 * validates each op. */	ops: opt(List(List(unknown()))),	error: opt(WireErrorSchema),}),

四种子类型,各管一件事:

as 什么时候用
snap 第一次,或订阅被重置
ops 之后每次变化
reset 上游换了(转发链断了),必须整份重来
error 读这个成员失败了

为什么要区分 snap 和 reset?因为两者都带完整值,但语义不同: snap 是"这就是当前值",reset 是"之前的增量作废了"。收到 reset 的消费者必须 丢掉本地缓存,不能尝试合并。

4.3 replicatedState 有三种形态

state.ts 导出三样东西,名字很像,用途完全不同(state.ts:404-413 的三个重载):

形态 谁来写 典型场景
MutableReplicatedState 本地 对象自己的状态,本机是权威
AttachedReplicatedState 上游一个源 转发别人的状态,自己只读
ReplicatedState(只读) 没人 交给消费者

AttachedReplicatedState 的注释说得很克制(state.ts:85-90): "A synchronously hydrated publication-only state backed by one source attachment"。 同步水合——订阅的那一刻值已经在了,不需要等一次异步往返。

代价是它必须有一个"源"。源的帧是有序的(state.ts:45-51):

ts
// state.ts:45-51(节选)export interface ReplicatedStateSourceFrame<T> {	/** Monotonic source cursor. The first frame after a snapshot must	 * be `snapshot.cursor + 1`. */	cursor: number;	readonly value: T;	readonly ops: ...;}

cursor 必须严格 +1。跳号就是源坏了,消费者不应该猜。

为什么要有三种形态,而不是一个可变对象?因为"谁有权写"是一个必须显式回答的问题:

形态 写权在谁 类型上有什么
MutableReplicatedState 本机 change() 等写方法
AttachedReplicatedState 上游一个源 只有读与订阅
ReplicatedState(只读) 没人 连"能改"都不暴露

这是类型上的减法:消费者拿到的类型里没有写方法,就写不出"顺手改一下"的代码。 和 §3.4 里"guest 的代理上就没有 owner 的方法"是同一个手法—— 把权限做在类型里,而不是做在运行时检查里。


五、contract:运行时值,不是类型

这是 chord 和绝大多数 RPC 框架最大的分歧点。

5.1 契约有 JSON 形态

contract.ts 里有一个 DescriptionSchema(:139-151),契约能被序列化成 Description:

ts
export type Description = Static<typeof DescriptionSchema>;

而且 hold 帧里就带着它(wire.ts:99-100):

ts
/** The consumer's contract token; the provider checks that it covers it. * Remote tokens carry `host`. */token: DescriptionSchema,

调用方把自己的契约发给提供方,提供方判断"我能不能覆盖你"。这就是 coverage (contract.ts:284):

Returns why provider does not cover consumer, or undefined when it does.

注意返回值:不是布尔,是失败原因。这个选择让错误信息不用另写一遍。

remote 不是唯一的契约形状。contract.ts 里有三种,切的是"这些成员能不能跨链路":

构造 能跨链路吗 需要什么
remote(name, def) 能 version / input / host / variants
local(name, def) 不能 methods 与 state,没有 host
opaque("name@version") 不能 一个已存在的原生对象

local 的 LocalDef(contract.ts:113-127)里没有 host 也没有 input,因为它不需要路由。 而 LOCAL_VARIANT = ""(contract.ts:132)——本地契约只有一个无名变体。

opaque 更有意思(contract.ts:37-41):

ts
/** A native in-process object identified by `name@version` * (local contracts only). */export const opaque = <T = unknown>(id: string): OpaqueSpec<T> => {

它把"一个已经存在的对象"包成契约成员,不经过工厂、不经过 serve, 而且只在 local 契约里能用。name@version 这个字符串形状本身就是答案: 它不参与 coverage 那套版本协商,因为它压根不跨链路。

三个构造对应三种边界的远近:跨机器、同进程跨对象、包一层已存在的东西。 写契约之前先回答"它会跨链路吗",选错构造后错的不是类型,是整个生命周期语义。

5.2 同一个版本号不能装两种东西

reload.ts:321 有一条校验,注释只有一句:

ts
/** Same contract version must cover the old description (forgotten bump); * facets' `uses` must bind. */

也就是说:如果你改了契约但忘了升 version,热重载会拒绝。 不是警告,是失败。这条规则的动机很实际——忘了升版本是这类框架最常见的 bug, 而它的后果(老消费者按旧 schema 解析新数据)极难排查。

同一个思路在状态里也有(reload.ts:396-397):

ts
else if (!deepEqual(cell.schema, run.decls.cellSchemas.get(name)))	throw invalid(		"state",		`${object.address}: schema of state ${name} ` +			"changed without a version bump",	);

改了 schema 必须升 version,改了就报 invalid。

两条规则合起来是一个原则:版本号是声明,不是装饰。 声明变了就必须动它, 否则系统会替你拒绝。

5.3 accepts:按版本号索引的适配器

版本不兼容怎么办?不是"必须同时升级",而是提供方可以写适配器:

ts
// contract.ts:316-318export type Adapter = (	current: Record<string, unknown>,) => Record<string, unknown>;export type Accepts = Readonly<Record<number, Adapter>>;

Accepts 的键是版本号。bind(:321)拿着消费者报的版本去查表:

ts
// contract.ts:321-323export function bind(	provider: AnyContract,	accepts: Accepts | undefined,	consumer: AnyContract,): Adapter | undefined;

于是"老前端连新后端"有了第三种解法:不改前端,后端加一个 accepts[3] = ...。 这和 HTTP API 的版本化是同一个思路,但落在方法返回值的形状上,粒度更细。

三条路一起看,才能理解 chord 的兼容性模型:

情况 手段
只加不改 升 version,什么都不用做
改了返回值形状 提供方写 accepts[v] 适配器
状态语义变了 升 cell 的 version + 写 migrate

三张表,没有第四种。


六、hot reload:一次 reload 到底做了什么

这是全章的核心。先看总入口。

6.1 prepare() 的九步

ts
// reload.ts:205-224async prepare(): Promise<void> {	try {		await this.waitForRetirement();		this.load();		this.checkProviders();		await this.prepareAll();		// From here new objects of changed types are rejected		// (upgrade_conflict, retryable) until commit or abort,		// so the candidate set is final once the activations		// already in flight have been prepared.		this.host.gating = this.changed;		await this.withDeadline(			this.prepareAll(), "activations in flight did not finish",		);		this.checkRefs();		this.tables = this.host.buildTables(this.entries());		await this.gate();		this.#alive();		this.#stage();	} catch (error) {		await this.rollback();		throw reloadError(error);	}}

九步,分三类:

步 做什么 失败了会怎样
waitForRetirement 等上一代代码退休 超时就强制退休
load 加载新模块 旧代码继续跑
checkProviders 新服务表能不能覆盖旧契约 同上
prepareAll 对每个活对象跑一遍新工厂 同上
host.gating = changed 候选集冻结 —
prepareAll 第二遍 跑到不动点(在飞行的激活也要准备完) 同上
checkRefs 每个活着的引用都要能绑到新提供方 同上
gate 闸门:等老根结束 超过 gateDeadline 则 abort
#stage 提前订阅新监听器(缓冲事件) 同上

第五步值得单独说。host.gating 一设,变更类型的新对象就被拒了—— 错误码是 upgrade_conflict,而且标着可重试。为什么必须拒? 因为候选集一旦还在长,prepareAll 就永远追不上它。

注释里那句 "so the candidate set is final" 是一个设计决定: 宁可变重载期间拒绝新建,也不要一个永远在变的集合。

6.2 只有两种变更需要闸门

这是整章最值得记住的一条。prepareObject 里,需要闸门的理由(reasons)只有一个来源: 状态语义版本提升 和 独占资源替换。

ts
// reload.ts:388-398// Each cell carries its own version: a raised one gates and// migrates, a schema change without one is refused.for (const [name, cell] of run.decls.cells) {	if (object.decls.cells.get(name) !== cell) continue;	const from = object.decls.cellVersions.get(name) ?? 1;	const to = run.decls.cellVersions.get(name) ?? 1;	if (to < from)		throw invalid(			"state",			`${object.address}: version of state ${name} ` +				`lowered from ${from} to ${to}`,		);	if (to > from)		candidate.reasons.push(`state ${name} version ${from} -> ${to}`);	else if (!deepEqual(cell.schema, run.decls.cellSchemas.get(name)))		throw invalid(			"state",			`${object.address}: schema of state ${name} ` +				"changed without a version bump",		);}

三行分支,三种结局:

版本比较 结局
to < from 抛 invalid——版本号不许降
to > from 进闸门,待会儿迁移
to === from 但 schema 变了 抛 invalid——改 schema 必须升版本

另一处是独占资源(reload.ts:399-409):新跑的工厂里有 exclusive 资源, 或者依赖了一个被推迟的资源,就推到 atGate;旧的那个如果还开着,落到 replaced。 然后:

ts
if (deferred.size > 0) candidate.reasons.push("exclusive resource replaced");

结论很硬:改方法体、改派生函数、加新方法、加新状态字段——这些都不进闸门。

于是"热重载看起来毫不费力"有了机制上的解释:不是它把难事藏起来了,是很难的变更本来就少。 大多数提交只是改了一个函数体,而那些对象仍然可以直接换代码, 一根引用都不用动。

那两条路径在代码里是分开跑的(reload.ts:410-421):

ts
await object.open(	run.created.resources.filter((resource) => !deferred.has(resource)),	run.created.refs,	this.abort.signal,);await object.waitHydrated(run);// Cells this reload adds read their first value once the new// resources are open (gated objects: at the gate); the// derivations over them are checked after.if (candidate.reasons.length === 0) {	await object.initCells(run, this.abort.signal);	dryRun(candidate);}

三段各管一件事:

  • open(...) 开的是不需要闸门的资源。deferred 里那些(独占的、或依赖了被推迟的资源的) 得等闸门。
  • waitHydrated(run) 等的是引用水合:新工厂拿到的远端成员,得先有值。
  • 最后那个 if 是分水岭:只有不进闸门的对象在这里初始化 cell 并跑 dryRun。

进闸门的对象要等到 gate() 之后才做这两件事——因为迁移还没跑,新 cell 还读不出值。

所以"闸门"这个名字有两层含义:它既是一道队列,也是一个阶段边界。 闸门之前的对象只做到一半,闸门之后的才是完整的新版本。

6.3 闸门:祖父条款

进闸门的那一小拨对象,要等什么?

ts
// reload.ts:457-468async gate(): Promise<void> {	this.gated = [...this.candidates.values()].filter(		(candidate) =>			candidate.reasons.length > 0 && candidate.object.status === "live",	);	const drained = this.gated.map(({ object }) => {		const grandfathered = new Set(object.leases.keys());		return new Promise<void>((resolve) => {			object.gate = { grandfathered, queue: [], drained: resolve };			object.stopTasks();			if (grandfathered.size === 0) resolve();		});	});

grandfathered 是"祖父条款"——已经在旧代码上持着租约的引用。 这些引用不会被赶走,它们手里的活儿跑完才算数。

object.gate 里同时放了三样东西:

字段 作用
grandfathered 允许继续跑完的租约集合
queue 新调用的缓冲区——不拒绝,排队
drained 全部跑完时 resolve

再加 stopTasks():旧的长任务直接停。于是"in flight 的活儿跑完旧代码" 就有了精确含义:方法调用能跑完,长期任务不能。

这个区别不是随意的。方法调用有调用方在等结果,砍掉就是错误; 长期任务是自由的,停掉之后可以在新代码里重新开始。

闸门等的时候,object.ts:1538 那个 #touch 在记账:

ts
/** Records that the root of `ctx` touched this object (a reload gate * grandfathers it). */

新来的根不算祖父。 只有已经碰过这个对象的根才被放行,新根得等闸门开。

6.4 commit():一次同步安装

ts
// reload.ts:561-582/** * Publishes the new code version in one synchronous step. Everything * fallible ran in prepare (factories, opens, migration and derivation * checks against the prospective schemas, listener subscriptions), so * this only installs. * ... */commit(beforeStart?: () => void): ReloadReport {	try {		return holdPublications(() => {			const report = this.#publish();			beforeStart?.();			for (const start of this.#starts.splice(0)) start();			return report;		});	} catch (error) {		this.host.fail(error);		throw reloadError(error);	}}

注释第一句是全章最该背下来的一句: "Everything fallible ran in prepare, so this only installs."

所有会失败的事——跑工厂、开资源、迁移并校验、订阅监听器——都在 prepare 里做完了。 commit 只剩下把新版本挂上去,所以它可以是同步的。

为什么同步那么重要?因为"同步"等于"没人能插进来"。 一旦 commit 里有一个 await,就会有代码在"旧版本已卸、新版本未装"的中间态里跑。

#publish 只动三个字段(reload.ts:587-594):

ts
const previous = host.current;const next: CodeVersionState = host.pending!;host.pending = undefined;host.codeVersions.set(next.id, next);host.previous = previous;host.current = next;

换代码就是换一个指针。 对象、引用、状态全没动,只有一个 host.current 指向了新版本。

6.5 三件事的顺序,为什么不能乱

commit 里那三行看着像收尾,其实是一个顺序约束:

text
#publish()         挂上新版本(观察者通知被 holdPublications 攒住)   |beforeStart?.()    协调者把 commit 帧发给子主机   |#starts            新版本的任务、注册、监听器才开始

注释(reload.ts:571-573)说得很具体: 没有这一步,"this code version starts"的东西可能先到子主机。

换成大白话:先让所有人知道新版本存在,再让新版本开始干活。 否则子主机可能收到一条"新版本发起"的消息,而它那边还不知道有个新版本。

6.6 三种失败,三种结局

失败在 处理 后果
prepare 里 rollback() 旧代码继续跑,抛 reloadError
协调者中途喊停 #alive() 抛 aborted 同 rollback
commit 里 host.fail(error) 主机终态,不再接任何活

第三种是整套设计里最狠的一处取舍。注释(reload.ts:564-565)写着: "the code version is half-published: the host fails terminally and admits no more work"。

为什么不回滚?因为 commit 的设计前提是"这里不会失败"。真失败了,说明有个假设破了, 此时磁盘上的状态处于一个谁也没设计过的形状。 宁可整台机器停掉让人来查,也不要带着半装版本继续对外服务。

这和 M11 里"预留阶段抛错就整个 Session 判死"是同一个态度(M11 §5.1 的 #failSession)。

#alive()(reload.ts:240-242)是第二种的实现细节:

ts
#alive(): void {	if (this.rolledBack)		throw new ChordError("aborted", "reload aborted while preparing", {			reason: "aborted",		});}

它在 prepare 里每一个 await 之后都调用一次。因为 abort 是异步到来的, 只能在每个可能让出執行权的位置检查。

6.7 旧代码什么时候退休

主机同时持有两个代码版本(reload.ts:259-263):

Retires the previous code version before loading the next one (a host keeps two). Waits until its roots ended and, on a child host, its parent retired it too (retire frame), at most retireDeadline. Past the deadline it is retired anyway: its remaining roots are aborted first and get a short grace to stop, so they see cancellation before the resources only that code version used are closed; their next call is superseded.

三个细节:

  • 只留两个。不是 n 个。还在跑上上代的根,说明它已经跨了两轮 reload,不正常。
  • 先给取消信号,再关资源。顺序反了,那些根会在资源已关的情况下继续跑。
  • 下一次调用是 superseded。不是 gone——对象还在,只是你手里那个代码版本没了。

superseded 这个错误码本身就是给"热重载了,你的调用被跳过了,重试就好"准备的。 它和 upgrade_required(浏览器引用)是同一类:都是"你没坏,只是世界变了"。


七、集群:五个帧的两阶段提交

单机热重载靠闸门。多主机靠什么?靠投票。

wire.ts:166-182 里有五个专用帧,方向看前缀就清楚:

ts
// wire.ts:166-182(节选)Open({ t: lit("prepare"), reload, codeVersion, plugins, options }),Open({ t: lit("vote"), reload, error: opt(...), report: opt(...) }),Open({ t: lit("commit"), reload }),Open({ t: lit("retire"), codeVersion }),Open({ t: lit("abort"), reload }),
帧 方向 作用
prepare 父 → 子 "我要重载,你去准备"
vote 子 → 父 "我准备好了(或拒绝了)",带 ReloadReport
commit 父 → 子 "装"
abort 父 → 子 "撤"
retire 父 → 子 "我不再用这个版本了"

这是教科书里的两阶段提交,但有一处不一样:协调者的 commit 在自己的准备完成之后、 子机的 commit 之前。

ReloadReport.children(reload.ts:47-51)就是这一步留下的车辙:

ts
/** * Cluster reloads: what each participating child host prepared, by host name * (its vote; the child commits it after the server). Absent for local reloads. */readonly children?: Readonly<Record<string, ReloadReport>>;

注释里那句 "the child commits it after the server" 是顺序声明: 服务器先,子主机后。

为什么不能反过来?因为"哪个代码版本算数"由服务器定。子主机先装,就会有一段 "子机已经是 v5、服务器还是 v4"的窗口;而 v5 的对象可能已经开始向 v4 的服务器发调用。

服务器先装,窗口就变成了"服务器 v5、子机 v4"——这个方向是安全的: 新版本声明自己能覆盖旧契约(§5),所以 v5 的服务器可以接受 v4 子机的调用。


wire.ts 开头有一段注释,是整个协议的目录:

ts
// JSON frames between two hosts (or a host and a client). Ids are chosen by// the side that creates the hold, call or subscription; every frame type has// one direction, so ids never collide://   consumer -> provider: hold, release, call, cancel, sub, unsub, resync//   provider -> consumer: shape, gone, result, state//   both: hello, ping, pong, bye, root_end, ack//   parent -> child: invalidate, prepare, commit, abort, retire//   child -> parent: vote

一句话概括:每个帧只有一个方向,所以 id 不会撞。( 7 + 4 + 6 + 5 + 1 = 23 个帧)

这是协议设计里最省事的一个决定。双向帧要让两侧各自维护 id 空间, 单向帧就不用——谁创建的谁发包。

方向 帧 数
消费方 → 提供方 hold release call cancel sub unsub resync 7
提供方 → 消费方 shape gone result state 4
双向 hello ping pong bye root_end ack 6
父 → 子 invalidate prepare commit abort retire 5
子 → 父 vote 1

8.1 hold 是"我要一个对象"

七个消费方帧里,hold 是最重的一个:

ts
// wire.ts:91-114(节选)Open({	t: lit("hold"),	id: Id,	at: Name,	/** The consumer's contract token; the provider checks that it covers it. */	token: DescriptionSchema,	input: unknown(),	/** A forwarded principal. Honored only on frames from the parent link. */	principal: opt(unknown()),	/** The client connection the hold comes from ... */	origin: opt(Name),	/** False: no state for this hold until `sub`. */	state: opt(lit(false)),	/** The consumer already has values (a re-hold after a link loss). */	again: opt(lit(true)),}),

五个字段,各管一个真实场景(token 和 input 必填,其余四个可选):

字段 场景
token 让我核一下你的契约版本能不能被我覆盖
principal 这是替另一个人建的(只在父链路生效,防止伪造)
origin 这是某个浏览器发起的,不算重载参与者
state: false 我只调方法,不要状态
again: true 链路断了又连上,我手里已有值,不急

principal 和 origin 那句 "Honored only on frames from the parent link" 是一道安全边界: 只有上级主机能替别人说话。 同级主机转发一个伪造的 principal 会被忽略。

8.2 shape:先给目录,再给内容

状态不是一次性发过来的,而是分成"单元":先一个 shape,然后每个状态成员一个 snap。

ts
// wire.ts:116-124Open({	t: lit("shape"),	id: Id,	variant: opt(str()),	members: List(str()),	contract: str(),	/** The state members whose snapshots follow this frame;	 * the consumer applies the shape once they are here. */	state: List(Name),}),

四个字段各管一件事:

字段 作用
variant 这个对象对你给出的是哪个变体(§3.4)
members 你这个变体看得见的成员列表
contract 契约指纹,用来确认"我看到的是我以为的那个版本"
state 后面跟几个 snap,到齐了才应用 shape

最后一行是最讲究的:shape 要等它的快照都到齐才生效。 否则客户端会有一瞬间知道"有个成员叫 count",但它的值还没来—— 那一瞬间任何读 count 的代码都会拿到 undefined。

这条规则把"订阅"变成了一个原子动作:要么你什么都没有,要么你有一致的目录加快照。

8.3 三种链路,一种帧

link.ts 里三个实现,接口完全一样:

构造 跑在哪 文件行
memoryLinkPair() 同进程 link.ts:272
ipcLink(channel) Node 子进程 link.ts:339
webSocketLink(socket) 跨机器、浏览器 link.ts:414

三个类都继承 BaseLink(link.ts:242 的 MemoryLink 是第一个)。帧的编码、校验、 重传逻辑全在基类里,子类只负责"怎么把一段字符串发出去"。

所以"同进程两个主机"和"跨机器两个主机"走的是同一套代码, 区别只在传输层。测试能跑全链路,原因就在这里。

8.4 64 KB 之后压缩

ts
// link.ts:108-113// whose JSON exceeds `PACK_THRESHOLD` characters is sent deflated. A host// that only relays the frame forwards ...export const PACK_THRESHOLD = 64 * 1024;

超过 64 KB 的 JSON 先 deflate 再发。注释里那句 "a host that only relays the frame forwards" 说明了设计意图:中转主机不重新压缩,直接把已经压好的字节转出去。

这是个容易被忽略的细节:状态快照很容易超过 64 KB,而每个中继节点重新压一遍 会是纯浪费。


九、delta:不可变是所有权约定

delta/ 3,976 行,是 chord 里最独立的一块(有自己独立的导出路径 ./delta)。 它的 README 第二段是全包最诚实的一句话:

Immutability is an ownership contract. Nothing is frozen or defensively copied, so an illegal mutation is not detected. It silently corrupts state.

翻译过来:不可变是约定,不是检查。 你毁了约,它不会报错,只会静默地坏掉。

这是一个明确取舍:要零拷贝的性能,就得把正确性交给调用方。 反过来,每一次修改都做深拷贝或者冻结,chord 就不可能在每秒钟几千次状态变更下工作。

9.1 谁有写权

README 里给了一张表(这里只摘五条最常用的):

值 能改吗
传给 track() 的初始值 不能。所有权已转移
change.state 能,但只在那个 change 开着的时候
赋进 draft 的外部对象 能。draft 存的是校验过的拷贝
tracker.value / prepared.base 不能
apply() 的批 被吞了。它把 payload 收进了副本

第二行是使用中最容易出错的:change.state 只在 change 期间可变, prepare() 之后任何一次访问都会抛。这不是防御性检查,是句柄被作废了。

9.2 一次变更的四个动词

ts
// delta/README.md 的示例(节选)const tracker = track(initial);   // 所有权转移const change = tracker.beginChange();change.state.output += "done\n";  // 只有这里能改const prepared = change.prepare(); // 句柄作废,产生不可变修订assert(prepared.base);            // base + ops = valuetracker.adopt(prepared);          // tracker.value === prepared.value

关键在 prepare() 的产物:base、value 和 ops。

ops 是一串精确的增量,把它应用到 base 上,必然得到 value。 于是有两件事同时成立:

  • 本地直接换 tracker.value(零成本,因为已经是同一个对象)
  • 远端按 ops 重放出同样的值(有成本,但不需要传全量)

applyImmutable(base, ops) 就是远端那一步。它是纯函数:同样的输入永远同样的输出, 不碰 base,不碰 ops,返回一个新值。

9.3 这套东西和热重载的关系

chord 的 cell 值就是这种不可变修订。三个环节因此变得廉价:

环节 为什么便宜
迁移(§6.2) 迁移函数拿到旧值、返回新值,不需要冻结旧值
快照(§4.2) 直接发当前修订,不用拷贝
订阅(§4.3) 每次变化就是一个 ops 数组,订阅者按需重放

一个不可变修订,同时是三个功能的输入。 这是 delta 那 3,976 行真正的价值: 它不是"一个 diff 库",它是 chord 状态层的公共前提。

9.4 积压的批可以一次性重放

applyImmutable 一次一批。链路断开重连时可能积压了几十批,一批一批地应用会产生 几十个中间修订——每一个都不需要,也都不该被看到。

applyImmutableBatches 处理这个(delta/README.md:53-60):

ts
replica = applyImmutableBatches(	replica,	queuedFrames.map((frame) => frame.ops),);

注释里那句 "no intermediate revision is exposed or safe to retain" 是要点: 整个调用共享一个写时复制作用域,所以中间态从来没存在过。

这和 §6.4 的 holdPublications 是同一个手法:把一串变化攒进一个作用域,最后一次性公布。 一个用于重放,一个用于发布;都在利用"不可变"这个前提。


十、完整链路

把前面几节拼起来,一次本地热重载的时序:

text
reload()  |  +-> prepare()  |     |  |     +-> waitForRetirement   上一代还在吗(retireDeadline, 5s)  |     |  |     +-> load                 加载新模块,得到新服务表  |     +-> checkProviders       新实现能覆盖旧契约吗  |     |  |     +-> prepareAll           每个活对象跑一遍新工厂(记录模式)  |     |     |  |     |     +-> cell.version 提升 -> reasons.push() -> 进闸门  |     |     +-> 独占资源换了     -> reasons.push() -> 进闸门  |     |     +-> 都没有           -> 可直接换,一根引用不动  |     |  |     +-> host.gating = changed  候选集冻结(新对象 -> upgrade_conflict)  |     +-> prepareAll 第二遍        跑到不动点  |     +-> checkRefs               每个引用都能绑到新提供方(浏览器除外)  |     |  |     +-> gate                    只等进闸门的那几个  |     |     |  |     |     +-> grandfathered = 已在旧代码上持租约的引用  |     |     +-> stopTasks()      长期任务直接停  |     |     +-> queue = []        新调用排队  |     |     +-> 租约全释放 -> drained(超过 5s 就 abort)  |     |  |     +-> #stage                 新监听器先订阅,事件先缓冲  |  +-> commit()        |        +-> holdPublications       攒住观察者通知        +-> #publish               host.current = 新版本(换一个指针)        +-> beforeStart            协调者把 commit 帧发给子主机        +-> #starts                新版本的任务与监听器才开跑        +-> 解散通知                状态、形状、注册表一起公布

注意最后四行的顺序。它回答了一个容易被忽略的问题: 为什么新版本不能一起去掉旧版本? 因为还有很多根在旧代码上跑。 两个版本同时活着,是靠 host.previous 和 host.current 两个字段做到的。


十一、工程暗坑

1. 改了状态 schema 不升 version,直接报错。 reload.ts:396-397 是 to === from 但 schema 变了就 invalid。不是警告,是拒绝。 理由很实在:老消费者会按旧 schema 解析新数据,而这类 bug 几乎无法复现。

2. cell.version 不能降。 to < from 直接 invalid(reload.ts:393-394)。降版本意味着"把新数据当旧语义读", 没有任何迁移函数能救。

3. gateDeadline 超时是 abort,retireDeadline 超时是强制执行。 两个都是 5 秒,结局完全不同(reload.ts:26-28)。 闸门里还有人在干活 → 已经太久,放弃这次重载;上一代还有根 → 已经跨了一代,不管了。

4. 浏览器引用不阻塞重载,但会变成 upgrade_required。 reload.ts:424-426 写得很直白:RefOwner 为 "client" 的不算重载参与者。 所以 commit 之后,浏览器手里那个引用下一次调用会拿到这个错误——前端得自己刷新。

5. superseded 不等于 gone。 对象还在,只是你那个代码版本没了。这两个错误码分开,前端才能区分"重试就行"和"没这个东西"。

6. commit 失败没有回滚,主机直接终态。 reload.ts:578-581 的 catch 里是 this.host.fail(error)。 "半装版本"不是一个可以恢复的状态,它只能停机。

7. state: false 的 hold 永远收不到状态。 wire.ts:110-111:这种 hold 只绑方法。想要状态就得再发一个 sub(wire.ts:143)。 而 again: true(:113)是"链路断了又连上"专用,首次 hold 加它只会让状态单元变慢。

8. hostFamily 的主机名是从输入里算的。 输入里的 key 字段一变,"这个对象住在哪里"就变了——但对你来说那是另一个对象: 新地址、新状态、新生命周期。把主机名当目录结构理解会出大错。

9. delta 的不可变没有任何运行时检查。 改了一个 prepared.value 里的嵌套对象,不报错,直接静默污染。 这类 bug 唯一的发现方式是"某个订阅者看到的值和源头不一致"。

10. prepareAll 是两遍,不是一遍。 reload.ts:205-224 里 prepareAll() 出现了两次,中间隔着 host.gating。 第一遍后,准备过程中可能有新对象激活了;第二遍把它们也追上,才能叫"候选集固定"。

11. 三个版本号,各管一件事。 契约的 version(remote 的 def.version)、cell 的 version(StateOptions)、 协议的 PROTOCOL_VERSION = 4(wire.ts:40),改错一个,报的错完全看不懂: 前者报 contract_mismatch,中者报 invalid/state,后者直接断链路。

11.1 十二个错误码,只有两个能重试

errors.ts 只有 77 行,但它是调用方面对失败时的全部词汇。12 个错误码里, 只有两个是可重试的(errors.ts:24):

ts
const RETRYABLE: ReadonlySet<ChordErrorCode> = new Set([	"superseded", "upgrade_conflict",]);
码 什么情况 能重试
superseded 你的代码版本已被换掉 能
upgrade_conflict 重载期间该类型暂停新建(§6.1) 能
upgrade_required 浏览器引用需要刷新 不能,解法是刷新
contract_mismatch 契约不覆盖(§5.1) 不能
invalid 参数、状态或实现不合规 不能
not_ready 对象还没水合 可以等
gone / released 对象没了 / 引用放掉了 不能
not_in_variant 这个变体没这个成员 不能
forbidden principal 被拒 不能
aborted 取消了 不能
unavailable 底层坏了 看情况

这张表真正的价值是那个 retryable 字段(errors.ts:42): 框架直接把"这次失败是不是该重试"算好了告诉你,不用字符串匹配。

还有一行值得记住(errors.ts:1): "A refused or aborted reload keeps the code of its cause"。 重载失败不会被包成一个笼统的 reload_failed,你会直接看到 contract_mismatch 或 invalid/state——排查时省掉一层嵌套。


十二、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

chord 的测试不需要额外环境,cd packages/chord 直接跑。六个实验,前五个都只是读。

实验 1:跑一遍热重载的核心用例

bash
cd packages/chordnpx vitest --run test/reload.test.ts

判据:全绿。这个文件里每条用例都是一个"变更类型 + 预期结局"的表格。

实验 2:看对象层面的重载

bash
npx vitest --run test/host-objects-reload.test.ts

判据:能看到"引用活过重载"的断言——同一个 ref,重载前后调用的实现不同。 这一条就是第一章 "survive reloads" 的可执行版本。

实验 3:看集群的两阶段提交

bash
npx vitest --run test/cluster.test.ts

判据:用例里会出现"子机 vote 失败 -> 整次重载 abort"。 把它和 §七 那五个帧对着看。

实验 4:自己触发一次闸门

找 test/reload.test.ts 里任意一个带 state 的实现,把 self.state(...) 的选项 从默认改成 { version: 2 },再跑。

判据:ReloadReport.gated 里多了那个对象的地址。 把 version 改成 1(比原来的小),则 reload() 直接抛 invalid。

实验 5:从教程跑一遍全链路

bash
npx vitest --run test/tutorial.test.ts

判据:共 55 个测试文件里,这一个对应 README 的 Quick start(共享待办清单)。 它跑通了,说明契约、主机、引用、状态、链路五个环节都对。

实验 6:把闸门卡死,看两种超时差在哪

在 test/reload.test.ts 里找一条带闸门的用例,把 gateDeadline 改成 1 再跑; 再用同样的方式把 retireDeadline 改成 1。

判据:两件事完全不一样——

  • gateDeadline 太小 → reload() 抛 aborted,旧代码继续正常服务(走 rollback)。
  • retireDeadline 太小 → reload 成功,只是上一代被强制退休,它的根被 abort 掉。

这个对比把 §6.6 那张表的第二行和 §6.7 的最后一个细节同时验证了。

最后一个实验不为验证代码,为验证你自己的理解: 看完这章再读一遍 README 的 Quick start,应该能说出每一行背后发生了几次帧交换。


五句话

如果只记五句:

  1. 引用活得比实现长。 调用方拿的是 Proxy,成员在访问时才绑到当前实现。
  2. 跨代的是数据与外部句柄,不跨代的是行为。 state 和 resource 保留,derive / on / task 重建。
  3. 闸门只等两类人。 状态 schema 升版的对象,和持着独占资源的对象。
  4. 两阶段提交:先准备(能反悔),再提交(不能)。 prepare 跑两遍到不动点。
  5. 远端不阻塞本地。 浏览器引用不挡重载,换成一个可重试的错误码。

本章小结

  1. chord 的对象 = 地址 + 状态 + 代码,三样分开存。
  2. 热重载靠引用存地址不存函数,换实现不用重新分发。
  3. prepare 与 commit 分开,安装就没有中间态。
  4. 只有两种变更过闸门:状态语义版本提升、独占资源替换。
  5. 集群重载是两阶段提交:一个子机投反对,整次 abort。

概念回顾

术语 一句话 在哪
object 地址 + 状态 + 代码,三样拆开 §三
state 可观察的 JSON,版本号带语义 §四
contract 运行时值,不是类型声明 §五
hot reload 换代不换引用 §六
两阶段提交 prepare 之后才 commit §七

练习

练习 1(读):§十二 实验 6 里两种超时结果完全不同。 为什么一个回滚、一个继续成功?→ 回 §6.6 的表与 §6.7。

练习 2(改):照 §十二 实验 4 把 self.state(...) 的 version 改成 2 再跑。预期:ReloadReport.gated 里多出那个地址; 改成 1 则 reload() 抛 invalid;回滚:改回默认。

常见误区

  1. 你会以为 热重载要重新分发引用;实际是 引用存地址,不用重发; 证据 §三、§六。
  2. 你会以为 状态只是个 JSON 块;实际是 版本号带语义,提升就得过闸门; 证据 §6.2。
  3. 你会以为 集群重载是各子机各自换;实际是 两阶段提交,一个失败全 abort; 证据 §七。

读完自检

三条,能不能不看稿说出来?

自检 一句话答案 不会就去
热重载靠什么成立? 引用存地址不存函数,换实现不用重新分发引用 §三、§六
prepare 和 commit 为什么必须分开? 会失败的放一边、不可失败的放一边,安装就没有中间态 §6.1、§6.4
哪些变更才需要过闸门? 只有两种:状态语义版本提升、独占资源替换 §6.2

十三、收束

13.1 三个可迁移的方法

一、要热重载,先让"引用"和"实现"解耦。 引用存地址不存函数,所以换实现不需要重新分发引用。 任何想支持热更新的系统都绕不开这一条:函数指针一旦被拷出去,就只能重启。

二、把"会失败的事"和"不可失败的事"分开。 prepare 装下所有会抛异常的东西(跑工厂、开资源、迁移、校验、订阅), commit 只负责把指针换一下。于是"安装"变成了一个不会有中间态的动作。 这个分法比"先备份再安装"更强:备份只能事后恢复,而这里压根不需要恢复。

三、闸门要窄,不要宽。 只有"状态语义版本提升"和"独占资源替换"两种变更需要排队,其余全部无缝。 一个把所有变更都当不兼容的系统,每次发布都是一次停服。

13.2 这章的边界

没讲的部分:

  • next/(28,733 行):v2 的文档与存储层。本章只在 §1.2 讲了它和 durable 的接缝, 因为 v2 还没接上热重载,讲它会把主线撕成两半。
  • connection.ts(1,328 行):一条链路上引用、调用、状态单元的完整状态机。本章只讲到帧。
  • manager.ts(444 行)、next-node/(5,743 行):子进程托管。只在本章边界处出现。
  • output.ts(410 行)、telemetry-sqlite/(536 行):与主线无关。

一个必须说清楚的数字修正:chord 是 216 文件 / 50,101 行,不是流传的 45,619。 后者只算了 src/ 的一部分。

13.3 下一站

M13 讲 mcp 与 codemode:模型自己写的代码,怎么在一个受控环境里跑。 那里会出现 chord 的第三种用法——不是宿主应用,也不是存储层,而是沙箱的边界。

下一章:M13 mcp + codemode——模型写的代码怎么在受控环境里跑。


本章源码索引

文件 行数 职责
chord/src/object.ts 1,932 对象、引用、生命周期、闸门、RefOwner
chord/src/connection.ts 1,328 一条链路上的引用与状态单元
chord/src/host.ts 1,306 主机:服务表、代码版本、根、插件
chord/src/reload.ts 724 本章核心:prepare / gate / commit
chord/src/remote.ts 659 远端引用的代理与转发
chord/src/watch.ts 493 可观察值的订阅与快照
chord/src/manager.ts 444 子主机进程托管
chord/src/contract.ts 436 契约、Description、coverage、accepts
chord/src/state.ts 424 replicatedState 的三种形态
chord/src/link.ts 416 三种链路与 64 KB 压缩阈值
chord/src/cell.ts 403 单个 cell 的值与版本
chord/src/wire.ts 200 23 个帧的 schema,协议版本 4
chord/src/delta/ 3,976 不可变修订与操作批
chord/src/sqlite/ 513 可移植的 SqliteDatabase
chord/src/next/store/ 6,117 durable 的 StoreStorage 建在这一层
chord/docs/spec.md 43 KB 兼容性、生命周期、重载的规格说明
chord/README.md 268 行 五个概念与七个导出路径