公共包与界面设计
packages
五套职责独立的 Rust 工程能力
这五个 Rust 公共包按任务独立选择：Base 处理值、配置与文件，System 管理主机资源，Remote 执行远程工作，Telemetry 传递观测，Yaostate 维护事务与原请求结果。每个包说明自己的输入、效果与资源收尾；目标选择、授权和业务数据模型仍由项目决定。
组合公共能力，完成一个真实任务 发布应用材料时，先检查完整内容，再通过明确连接交付，并保留实际结果与剩余资源责任。业务决定是否激活服务；观测和事务能力按需要加入，无需启动一条固定的多层流水线。
公共能力从明确的职责开始
项目按任务选择所需入口。只读取配置时，不需要同时启动远程连接或遥测运行时；需要发布远端文件时，再组合连接、传输和文件核验能力。五个包的排列不代表必须依次经过的层级。
公共包负责承诺的调用行为、结果解释和资源收尾，业务决定目标、授权与数据关系。例如，Remote 完成文件传输和可见切换后，是否激活服务、何时回滚仍由具体业务决定；Yaostate 提交事务，也不会替业务执行事务外的支付或通知。
从要完成的任务选择最小能力组合
只需要解析配置时，选择 Base 的严格输入与值处理即可。需要向远端交付文件时，再加入 Remote 的连接和完整传输；需要掌握进程、挂载、网络或虚拟机生命周期时，才使用 System。业务持久状态选择 Yaostate 的事务能力，Telemetry 则提供独立观察。
选择包之前先写清楚输出是什么：一份通过检查的配置、一份已经可见的远端文件、一个仍需持有的运行对象，或一项已提交的数据库结果。它们的完成条件不同，不能统一简化为一个“成功”布尔值。
准备与发布材料
Base 检查本地材料与稳定内容，Remote 完成所选传输和可见切换；业务另行决定是否同步持久化或激活接收端。
运行并结束工作
System 或 Remote 返回实际运行与关闭结果。调用方保留仍有工作要结束的持有者，不把超时当作资源已释放。
保存业务关系
Yaostate 原子提交业务自行定义的关系与索引。支付、通知和外部文件写入仍需放在相应外部效果边界处理。
| 公共包 | 负责的能力 | 留给业务 |
|---|---|---|
| Base | 值、配置、文件与本地状态 | 输入来源、独占条件与授权 |
| System | 进程、网络、磁盘与虚拟机 | 主机权限、分配与业务就绪 |
| Remote | SSH、SFTP 与远程调用 | 远端身份、目标与激活 |
| Telemetry | 上下文、请求观察与遥测导出 | 信任策略、信号与分析解释 |
| Yaostate | 有序事务与原请求结果 | 实体、索引、约束与外部效果 |
按任务选择所需公共包；排列不表示依赖或启动顺序。业务授权、数据模型与外部效果仍由项目负责。
围绕一个完整任务调用
读取配置时，Base 严格检查未知字段和重复声明，保留明确的路径、大小与期限。核验文件必须读到真实末尾才形成摘要；保留文件句柄只能固定对象身份，调用方还要维持字节不变。
Remote 按明确命令、参数和环境执行远程程序，等通道与双路输出结束再返回。进程内 SSH 用于受信网络；验证预期主机时，OpenSSH 入口使用已知主机密钥文件 known_hosts。SSH 上的 Connect 远程服务调用仍保留逻辑目的地与 HTTPS 验证。
System 在指定的隔离资源视图（命名空间）启动程序，持有确切接口与挂载，或把引导、磁盘和网络描述交给虚拟机。地址服务、启动信息代理、启动文件传输（TFTP）与域名转发（DNS），分别声明资源限制并独立关闭。
运行时保留所有权，也保留观察来源
资源取得后，实际持有者负责结束。子进程退出与输入输出结束是两件事；普通子进程控制也不覆盖所有后代。要终止后代范围，调用方需先取得主机的相应授权。失败或取消留下的资源仍由原持有者处理，不能随等待结束而丢弃。
虚拟机区分运行状态、客户机停止、宿主进程退出与客户机程序结果。远程超时也不意味着动作没有发生；关闭仍保留原连接与责任，重新连接和重发不能消除未知结果。
Telemetry 记录追踪上下文，也就是一次调用与上下游的关联。HTTP 响应头、正文结束、错误和放弃分别可见，Connect 复用同一次观察。调用方决定信任上游追踪，还是仅保留不可信关联；认证成功和内网来源不会自动提升信任。
先交付完整材料，再决定何时使用
Base 通过暂存、核验与发布交付文件。原子可见意味着读取者看到旧文件或完整新文件；持久化还需文件和父目录同步。复用原验证结果要求文件身份与字节继续稳定。
Remote 在目标目录内暂存，传输完整内容并设置模式，最后原子重命名。远端可见切换之后，内容读回、持久同步、服务激活和业务回滚由具体操作选择。
本地状态把一批修改一起写入并同步保存。遇到需要重开的存储故障时，先停止新的工作，再打开同一存储目录查看当前状态。重开能回答现在保存了什么，却不能凭相同内容断定先前丢失回复的写入是否成功。
让事务结果保留确定性与未知性
Yaostate 用有限字段、稳定的数据空间（Space）和有序键，提供单条、批量与受条数和字节限制的分页读取。同一数据库的多个空间可一次原子提交；业务在同一事务检查唯一性、关联与索引。跨事务分页会取得新快照，不是整份数据的固定导出。
普通事务区分确定未提交和结果未知。Once 原请求结果记录把完整输入、输出与业务修改一起保存，相同请求可恢复原输出。处理函数可能执行多次，因此只使用给定事务和稳定输入，不能在其中发消息、调用支付渠道或写外部文件。
未知结果仍对应原数据库、操作、请求编号与输入。关闭运行时不证明未提交，读不到记录也不证明以后不会完成。模型变化通过停写、将旧空间设为只读、分批转换、业务验证和切换处理；旧结果保留与清理由业务决定。
| 观察 | 可以建立的事实 | 仍需独立完成 |
|---|---|---|
| 原子文件发布 | 目标名称已切换到完整内容 | 所需持久同步与业务激活 |
| 进程退出 | 选定进程已有终止结果 | 相关输出、后代或外部协议的结束 |
| 事务结果未知 | 原请求仍有恢复责任 | 以原身份读取或按原协议恢复 |
| 遥测转发回应 | 转发调用获得当前结果 | 后端是否保存、观察是否完整与业务是否成功 |
错误也应交回足够的事实与责任
取得资源失败时，要区分完全没有取得资源与仍有残留资源需要收尾；修改失败时，要区分确定未发生与效果未知。调用方据此决定能否开始后续工作，而不是根据异常名称猜测操作有没有执行。原期限用于限制同一次工作，不因重新等待或重新拿到句柄而刷新。
例如，一批文件按顺序上传到远端，中途失败可以留下已经完成的前缀，不能称作整批回滚；数据库提交未知也不能因客户端关闭而变成未提交。恢复要保留原目标和业务身份，先利用相应能力取得真实结果，再由业务决定下一步。
可以依赖：公共结果明确报告的完成范围
完整传输、已提交事务和已结束资源各有自己的结果，应按该范围组合业务流程。
不能推断：停止等待即远端效果消失
命令、写入或提交可能已经发生；剩余资源与未知效果继续由原任务持有和解释。
继续核对：Once 处理函数的外部效果
处理函数可能重入，只能使用给定事务与稳定输入。外部支付、消息和文件写入不能藏在可重试事务函数中。
用独立结果核对真实调用
验证用公共入口读取实际材料与结果。System 的可复用测试系统镜像与独立输入镜像，承载涉及全局资源的检查；Yaostate 的隔离真数据库支持客户端重启后读取同一历史；Remote 的 SSH 测试虚拟机核对真实连接、命令和传输。业务预期由调用方独立提供。
Telemetry 使用队列和并发受限的官方导出组件。队列满或接收端不可达会留下观察缺口，不能推断没有故障。转发保留原来源，退出时先结束数据生产再关闭导出。设计验证关注派发目标、独立读回、失败后的资源与不完整结果，不能只看日志或一次返回值。