protocol@earendil-works/pi-protocol

要点Key points

• 没有任何 Node 专用 API：同一份代码可以用在浏览器、Bun 或 worker 里；传输（Unix socket、WebSocket…）由 client / server 提供。No Node-only APIs: the same code works in a browser, Bun or a worker; transports (Unix sockets, WebSockets…) come from client / server.
• schema 是 additionalProperties: false 的 StrictObject，所以多一个字段也会被拒绝。Schemas are StrictObjects with additionalProperties: false, so even one extra field is rejected.
• coding-agent 把 protocol、client、server 三个包都只列为 devDependencies，供 experimental/ 下的 server 与 client 运行时使用。coding-agent lists protocol, client and server only as devDependencies, for the server and client runtime under experimental/.

工作原理How it works

1. 发送：transport.send(encodeClientMessage({ type: "hello", version: PROTOCOL_VERSION }))。Send: transport.send(encodeClientMessage({ type: "hello", version: PROTOCOL_VERSION })).
2. 接收：const decoder = new ServerMessageDecoder({ maxFrameLength })，然后 for (const m of decoder.push(chunk)) …，流结束时 decoder.end()。Receive: const decoder = new ServerMessageDecoder({ maxFrameLength }), then for (const m of decoder.push(chunk)) …, and decoder.end() when the stream ends.
3. 两端的 maxFrameLength 要一致（默认 16 MiB）。Both peers must use the same maxFrameLength (16 MiB by default).

要点Key points

• 任何失败都变成 ProtocolValidationError：CborError 与 FrameError 被包装，错误消息截断到 500 个字符。Every failure becomes a ProtocolValidationError: CborError and FrameError are wrapped and the message is cut to 500 characters.
• 解码器失败后进入 failed：之后的 push() 和 end() 都直接抛错，没有“跳过坏帧”这回事——调用方应该断开连接。A failed decoder stays failed: every later push() and end() throws; there is no “skip the bad frame” — the caller should drop the connection.
• 被拒绝的非 JSON 值：Uint8Array、非有限数、undefined、带原型的对象和环。Rejected non-JSON values: Uint8Array, non-finite numbers, undefined, objects with prototypes, and cycles.

工作原理How it works

1. encodeProtocolMessage(value, parse, kind)：先 parse(value)，再 encodeFrame(encodeCbor(validated, { maxByteLength }))。encodeProtocolMessage(value, parse, kind): parse(value) first, then encodeFrame(encodeCbor(validated, { maxByteLength })).
2. ValidatedMessageDecoder.push(chunk)：对每个完整帧 parse(decodeCbor(frame))，返回 0..n 条消息。ValidatedMessageDecoder.push(chunk): parse(decodeCbor(frame)) for every complete frame, returning 0..n messages.
3. 流结束时调用 end()：还有半帧就报 "Truncated frame at end of stream"。Call end() when the stream ends: a partial frame reports "Truncated frame at end of stream".

要点Key points

• 客户端 hello 的 version 是任意非负整数，服务端的则是字面量 8：版本不符由服务端用 hello_error { code: "version" } 回答。The client's hello.version is any non-negative integer, the server's the literal 8: a mismatch is answered by the server with hello_error { code: "version" }.
• 请求 id 是客户端选的非空字符串（pi-client 用 request-1、request-2…），回应用同一个 id 关联。Request ids are non-empty strings chosen by the client (pi-client uses request-1, request-2…); responses correlate by the same id.
• service_update 只按 subscriptionId 寻址，不带 target：订阅已经属于某个连接和附着。service_update is addressed by subscriptionId only, without a target: the subscription already belongs to a connection and attachment.

工作原理How it works

1. 所有消息都是 Type.Union：ClientMessageSchema 有 3 个成员，ServerMessageSchema 有 5 个（ResponseEnvelope 自身又是 ok / not-ok 的联合）。All messages are a Type.Union: ClientMessageSchema has 3 members and ServerMessageSchema 5 (ResponseEnvelope is itself an ok / not-ok union).
2. 类型从 schema 推导：type ClientMessage = Static<typeof ClientMessageSchema>。Types are derived from the schemas: type ClientMessage = Static<typeof ClientMessageSchema>.
3. void 回应：{ type: "response", id, ok: true }，没有 result 字段。A void response: { type: "response", id, ok: true }, without a result field.

要点Key points

• 管理服务的 attach() / detach() 不返回任何路由 id：服务器装好路由后才发 attachment，解除时发 attachment: null。Management attach() / detach() return no route ids: the server sends attachment once the route is installed, and attachment: null when it is cleared.
• 切换或重新附着后，带旧 attachmentId 的延迟帧被拒绝（session_not_attached）。After switching or reattaching, delayed frames with an old attachmentId are rejected (session_not_attached).
• 一个 Session 可以同时被多个 presentation 附着；同一连接重复 attach 同一个 Session 是幂等的。A Session can have several presentation attachments at once; repeating attach for the same Session on one connection is idempotent.
• isServerId() 是导出的校验函数；client 与 server 的构造函数都用它拒绝非规范的 id。isServerId() is the exported check; the client and server constructors both use it to reject non-canonical ids.

工作原理How it works

1. 服务器级：client.request({ serverId: client.hello.serverId }, call)。Server-wide: client.request({ serverId: client.hello.serverId }, call).
2. Session：client.request(client.attachment, call)——attachment 是最近一次带外消息给出的完整路由。Session: client.request(client.attachment, call) — the attachment is the full route from the latest out-of-band message.
3. 服务端先比较 target.serverId（wrong_server），再在 SessionRouter 里比较 sessionId 与 attachmentId。The server compares target.serverId first (wrong_server), then sessionId and attachmentId in the SessionRouter.

要点Key points

• 服务端握手超时默认 5 秒；第一条消息不是 hello、或之后再发 hello，都会以 hello_error { code: "invalid_request" } 结束连接。The server's handshake timeout is 5 seconds by default; a first message that is not hello, or a later hello, ends the connection with hello_error { code: "invalid_request" }.
• 客户端检查服务端报告的 serverId 是否就是它期望的那台逻辑服务器，不符就断开。The client checks that the reported serverId is the logical server it expects, and disconnects otherwise.
• 握手期间到达的请求不会丢：服务端在握手完成后再处理它们。Requests arriving during the handshake are not lost: the server handles them once the handshake completes.
• cancel 只取消同一连接上、同一 id 且同一 target 的活动请求；被取消的请求以 cancelled 回应。cancel only cancels an active request with the same id and the same target on the same connection; the cancelled request answers cancelled.

工作原理How it works

1. Server.dispatchMessage()：awaitingHello → handshaking → ready；ready 之后按类型调用 handleRequest 或 handleCancel。Server.dispatchMessage(): awaitingHello → handshaking → ready; after that it calls handleRequest or handleCancel by type.
2. Connection.#handleMessage()（客户端）：连接中只接受 hello / hello_error；连上后 hello 类消息都是协议错误。Connection.#handleMessage() (client): while connecting only hello / hello_error are accepted; once connected, any hello-type message is a protocol error.
3. attach 的顺序：路由安装 → 带外 attachment → attach 调用的 response。Attach ordering: route installed → out-of-band attachment → the attach call's response.

要点Key points

• 负载总是被复制：返回的帧不引用调用方传入的 chunk，调用方可以复用自己的缓冲区。Payloads are always copied: returned frames never alias the caller's chunks, so callers may reuse their buffers.
• 按 64 KiB 分块分配，所以一个声明很大但迟迟不到的帧不会一次性占用全部内存。Allocation is in 64 KiB blocks, so a frame that declares a large size but arrives slowly does not reserve all of its memory up front.
• maxFrameLength 可以是 0 到 0xffffffff；客户端与服务端还要求它 ≥ 1。maxFrameLength may be 0 to 0xffffffff; the client and server additionally require at least 1.

工作原理How it works

1. encodeFrame(payload)：分配 4 + n 字节，写长度，复制负载。encodeFrame(payload): allocate 4 + n bytes, write the length, copy the payload.
2. push() 的外层循环：头还没齐就继续读头；齐了就检查长度并开始收集负载；负载齐了就产出一帧并重置。push()'s outer loop: keep reading the header until complete; then check the length and start collecting; when the payload is complete, emit a frame and reset.
3. end()：头或负载只读了一部分 → failed + FrameError。end(): a partially read header or payload → failed + FrameError.

要点Key points

• 编码器为整数选最短的参数；非整数与 -0 写成 float64（0xfb）；非有限数、非安全整数直接报错。The encoder picks the shortest argument for integers; non-integers and -0 are written as float64 (0xfb); non-finite numbers and unsafe integers are errors.
• 文本按 fatal UTF-8 解码并保留开头的 BOM；编码时孤立代理项会被检测并拒绝。Text is decoded as fatal UTF-8 and keeps a leading BOM; lone surrogates are detected and rejected on encode.
• 解码出的对象用 defineProperty 设置属性，所以 __proto__ 只是普通的数据键。Decoded objects set properties with defineProperty, so __proto__ is just a data key.
• 字节串（主类型 2）在 CBOR 层是合法的，但信封层的严格 JSON 检查会拒绝它。Byte strings (major type 2) are legal at the CBOR layer but rejected by the envelope's strict-JSON check.

工作原理How it works

1. encodeCbor(value, { maxByteLength, maxContainerLength, maxDepth }) → Uint8Array。encodeCbor(value, { maxByteLength, maxContainerLength, maxDepth }) → Uint8Array.
2. decodeCbor(bytes, options) → 恰好一个值；尾随数据是错误。decodeCbor(bytes, options) → exactly one value; trailing data is an error.
3. hello 的编码是 25 字节：4 字节长度 + 21 字节 CBOR（见图中的例子）。hello encodes to 25 bytes: a 4-byte length + 21 bytes of CBOR (see the example in the diagram).

要点Key points

• 因此服务端可以把 Session 调用原样转发给 Session worker，而不需要加载那个服务的契约。So the server can forward a Session call to the Session worker as is, without loading that service's contract.
• client 在服务适配边界用 chord 的解析器（parseServiceCall、parseServiceCatalogue、createServiceStateDecoder），server 用 decodeServiceControlCall 与 createServiceStateEncoder。At the service-adapter boundary the client uses chord's parsers (parseServiceCall, parseServiceCatalogue, createServiceStateDecoder), the server decodeServiceControlCall and createServiceStateEncoder.
• 不在公共协议里：服务器与 worker 的生命周期（实验性的本地协调器只是不透明的消息路由），以及对端认证。Not in the public protocol: server and worker lifecycle (the experimental local coordinator is just an opaque message router), and peer authentication.

工作原理How it works

1. coding-agent：createClientServiceTransport(client, () => client.attachment) 把 Session 路由变成一个 chord 传输，再交给应用的类型化服务绑定。coding-agent: createClientServiceTransport(client, () => client.attachment) turns the Session route into a chord transport for the application's typed service bindings.
2. 服务端收到订阅时为它建一个 ServiceStateEncoder，之后的更新都经它编码。On a subscription the server creates a ServiceStateEncoder for it, and later updates are encoded through it.
3. 应用的 payload 语义校验在 chord 服务里完成，而不是在协议层。Semantic payload validation happens in the chord services, not in the protocol.