fable-run

Fable Run

在受限环境中执行实际产物并收集运行时证据，避免将“进程已启动”误认为“应用正常运行”。

使命

运行时工作需要明确生命周期归属：确切的命令／产物、工作目录、环境、端口、就绪标准、输出限制、超时时间和清理方式。

服务器 PID、来自错误进程的 HTTP 200，或从未实际执行目标功能的 CLI 退出码 0，都不足以构成有效证明。

适用场景

• 必须运行服务器／服务才能验证行为；
• 需要对已构建／已发布的 CLI 或可执行文件进行冒烟测试；
• 浏览器／运行时集成需要一个正在运行的进程；
• 运行时路径与单元测试／源码执行路径存在显著差异；
• 验证需要实证的入口点／生命周期证据。

不适用场景

• 单元／集成测试无需持久运行的进程即可证明行为（fable-verify）；
• 代码仍需实现（fable-execute）；
• 需要诊断反复出现的运行时故障／过时问题（fable-recover）；
• 启动进程会造成未经授权／破坏性的外部副作用。

运行时分类

目标	重要控制项
单次运行的 CLI	cwd／env／参数、退出状态、stdout／stderr、副作用
HTTP 服务器	端口所有权、就绪状态、健康检查与功能探测、清理
worker／守护进程	启动就绪状态、队列／输入样例、终止
浏览器应用	服务器 URL、浏览器就绪状态、控制台／网络错误
打包的二进制文件	确切的产物／版本／路径、干净环境
多服务	依赖启动顺序、端口、拆除、关联信息

协议

阶段 1 — 确认确切的产物

记录：

• 命令／二进制文件路径；
• 版本／哈希／构建信息（如相关）；
• cwd；
• 所需环境／配置；
• 预期进程类型；
• 安全输入／探测方式；
• 需要避免的破坏性／外部副作用。

不要假设 PATH 中的 foo 就是刚构建的产物——身份信息至关重要时，应先解析其路径。

阶段 2 — 明确资源所有权

启动前确定：

• 请求的／可用的端口；
• 是否有现有进程占用该端口；
• 临时目录／文件；
• 子进程行为；
• 超时／预算；
• 清理方式。

切勿仅为获取首选端口而终止无关进程。

阶段 3 — 在有界范围内启动并观察

捕获 PID／进程句柄、stdout／stderr、启动错误和时间戳。设置输出／超时限制，避免嘈杂或挂起的服务无限消耗资源。

阶段 4 — 区分启动与就绪

成功生成进程仅表示操作系统接受了该进程。

就绪状态可能需要：

• 端口开始接受连接；
• 健康检查端点返回预期负载；
• 依赖项完成初始化；
• CLI 命令执行到预期分支；
• 浏览器页面加载成功，且没有致命的控制台／运行时错误。

尽可能使用带退避机制的有界就绪轮询，而不是任意固定时长的休眠。

阶段 5 — 探测关键行为

健康检查返回 200 只能证明健康状态。如果变更的功能是 /checkout，就应探测最小且安全的结账行为／契约，而不是仅凭 /healthz 就下结论。

记录请求／输入以及相关响应／副作用。

阶段 6 — 检查错误／过时进程

如果输出与源码／构建预期不符，请检查：

• 已解析的可执行文件／导入路径；
• 进程启动时间；
• 端口占用进程的 PID；
• 构建／产物哈希；
• cwd／env；
• 是否仍有旧服务器在运行。

反复出现的歧义应交由恢复流程处理，再修改产品逻辑。

阶段 7 — 正常终止

只停止本次运行所拥有的进程／资源。条件允许时应等待进程正常退出，仅在本次运行拥有的进程树内升级终止力度，并清理临时资源。

阶段 8 — 严谨记录运行时证据

说明本次运行能证明什么：入口点已启动、已观察到端点行为、已正常关闭等。更广泛的正确性验证交由 fable-verify。

决策规则

• 端口被未知进程占用 → 选择另一个安全端口或检查占用进程；不要不加区分地终止进程。
• 进程成功启动但尚未就绪 → 在预算范围内继续等待并探测，不要判定为 PASS。
• 健康检查成功但未探测变更后的功能 → 只能通过健康检查这一项声明。
• 相比固定时长的休眠，有界条件轮询更可靠；优先使用可观测的就绪状态。
• 源代码变更后运行时输出仍未变化 → 再次修改代码前，先确认制品和进程的身份。
• 如果一次性 CLI 按设计以非零状态码退出，它仍可能是经过有效测试的错误路径；应将退出状态和输出与预期契约对比，而不是一概要求状态码为 0。
• 对外部类生产环境的副作用，必须有明确的安全范围和授权；有本地夹具或沙箱时，优先使用它们。
• 后台进程必须明确所有权并进行清理，即使测试本身失败也不例外。

不变量

• 用作证据时，必须能够确认运行时制品或进程的确切身份。
• 不得终止无关进程。
• 启动、就绪、行为和关闭是彼此独立的声明。
• 运行时探测必须有时间、输出和资源限制。
• 成功或失败时，都必须清理所拥有的后台资源。
• 证据不得声称超出实际探测所验证的范围。

故障分类

启动失败

可执行文件缺失、权限／配置／启动错误。重试前检查命令、制品和环境。

就绪失败

进程仍在运行，但服务始终无法使用。收集启动日志和依赖信息并进行诊断。

进程身份错误导致的证据问题

端口或路径指向较旧或无关的进程。先确认身份，不要修改产品。

功能探测失败

运行时已就绪，但目标行为不正确。根据问题是否明确，返回验证／执行／恢复阶段。

挂起／泄漏

进程或子进程未能终止。检查生命周期和清理流程；仅在有界范围内强制终止自己拥有的进程树。

环境不匹配

行为取决于工作目录、环境变量、操作系统或运行时版本。应记录并核实差异，不要将其普遍视为产品事实。

反模式

• 将 sleep 5 && curl /healthz 作为通用的运行时证明；
• 认为创建了 PID 就表示已经就绪；
• 用健康检查端点返回 200 来证明无关功能；
• 终止任何占用 3000 端口的进程；
• 失败后仍让服务继续运行；
• 测试 PATH 中安装的旧版二进制，而不是候选制品；
• 因进程仍在运行就忽略 stderr；
• 无限制地捕获日志或轮询；
• 无必要时，为冒烟测试执行真实的破坏性事务。

运行时数据包

Artifact/command/version:
CWD/env/config:
Owned resources/PID/port:
Readiness condition/result:
Behavior probe/result:
Stdout/stderr highlights:
Artifact/process identity checks:
Termination/cleanup:
What this proves:
What remains for verify:

完成标准

满足以下条件时，运行时执行即告完成：

• 在已知上下文中启动了确切的候选进程或制品；
• 已观察到就绪状态，而非仅作假定；
• 已探测相关行为，或明确限定了证据范围；
• 已消除对陈旧或错误进程的身份疑问；
• 已清理所拥有的进程和资源；
• 已将证据交由验证环节，且未夸大其结论。

渐进式资源

• 深入指南：references/process-lifecycle-and-readiness.md
• 现有协议：references/runtime-process-management.md
• 示例：examples/live-server-smoke-check.md