契约测试与模拟器

packages/node-sim 是 Bun 运行的 TypeScript workspace。参考服务器内存保存状态，仅供开发；不能作为生产控制面。

bun run --cwd packages/node-sim test
bun run --cwd packages/node-sim demo
bun run --cwd packages/node-sim reference

demo 启动参考服务器与模拟节点。reference 默认监听 127.0.0.1:8787，提供三台服务器和五十名用户；可用 --host、--port、--servers、--users 调整。注册令牌以仅所有者可读权限写入 .node-sim/enrollment-tokens.txt，可用 --tokens-out 指定其他受保护文件。不要在参数或 URL 中传入真实 token。

两类验证复制标题链接

面板契约套件通过 defineNodeContractSuite(title, setup) 接入被测 API；对真实面板的测试需要控制模块创建临时库夹具、修改配置、轮换/撤销 token 和检查记账。它验证的是面板对协议的行为。外部节点应连接参考服务器验证自己的客户端，然后连接通过契约套件的预发布面板进行端到端验证。

覆盖注册重试、ETag/304、配置变化、心跳、重复/乱序/冲突批次、同用户多入站、在线封禁、撤销凭据。模拟器支持丢响应、重复、乱序、序号重置、超大批次与错误 token；测试必须证明重试不会重复记账、重启不会丢失未确认流量。

测试仅写 scratch 数据库，不能使用 ppanel_edge。生产限流会延长套件运行，测试配置应明确隔离。工具接口和示例见节点参考。