fable-run

Fable Run

実際の成果物を制限された環境で実行し、「プロセスが起動した」ことと「アプリケーションが動作する」ことを混同せずに、実行時の証拠を収集します。

ミッション

実行時の作業では、ライフサイクルの管理が必要です。正確なコマンド／成果物、作業ディレクトリ、環境、ポート、準備完了の判定基準、出力上限、タイムアウト、クリーンアップを管理します。

サーバーの PID、誤ったプロセスからの HTTP 200、または機能を一度も実行しない CLI の終了コード 0 だけでは、十分な証拠になりません。

有効にするタイミング

• 動作を検証するために、サーバー／サービスを実行する必要がある。
• ビルド済み／公開済みの CLI または実行可能ファイルにスモークテストが必要である。
• ブラウザー／実行時の統合にライブプロセスが必要である。
• 実行時の経路が、ユニットテスト／ソースコードの実行時と大きく異なる。
• 検証に、エントリーポイント／ライフサイクルの実証的な証拠が必要である。

有効にしないタイミング

• 永続的なライブプロセスがなくても、ユニットテスト／統合テストで動作を証明できる（fable-verify）。
• コードの実装がまだ必要である（fable-execute）。
• 実行時の繰り返し失敗／古い状態を診断する必要がある（fable-recover）。
• プロセスの起動によって、許可されていない、または破壊的な外部への影響が発生する。

実行時の分類

対象	重要な制御項目
単発の CLI	cwd/env/引数、終了、stdout/stderr、副作用
HTTP サーバー	ポートの所有権、準備完了、ヘルスチェックと機能プローブの区別、クリーンアップ
ワーカー／デーモン	起動時の準備完了、キュー／入力フィクスチャ、終了
ブラウザーアプリ	サーバー URL、ブラウザーの準備完了、コンソール／ネットワークエラー
パッケージ化されたバイナリ	正確な成果物／バージョン／パス、クリーンな環境
複数サービス	依存関係の起動順序、ポート、終了処理、相関関係

プロトコル

ステージ 1 — 正確な成果物を特定する

以下を記録します。

• コマンド／バイナリのパス。
• バージョン／ハッシュ／ビルド（該当する場合）。
• cwd。
• 必要な環境／設定。
• 想定されるプロセスの種類。
• 安全な入力／プローブ。
• 避けるべき破壊的／外部への副作用。

ビルドした成果物が PATH 上の foo だと決めつけないでください。識別が重要な場合は、その実体を特定してください。

ステージ 2 — リソースの所有権を確立する

起動する前に、以下を確認します。

• 要求された／利用可能なポート。
• 既存のプロセスがそのポートを所有しているかどうか。
• 一時ディレクトリ／ファイル。
• 子プロセスの動作。
• タイムアウト／予算。
• クリーンアップ方法。

優先するポートを確保するためだけに、無関係なプロセスを終了してはいけません。

ステージ 3 — 観測に上限を設けて起動する

PID／プロセスハンドル、stdout/stderr、起動エラー、タイムスタンプを記録します。出力／タイムアウトに上限を設け、出力の多いサービスや応答しなくなったサービスが無制限にリソースを消費しないようにします。

ステージ 4 — 起動と準備完了を区別する

プロセスの起動に成功したということは、OS がプロセスを受け付けたことを意味するだけです。

準備完了の確認には、以下が必要な場合があります。

• ポートが接続を受け付けている。
• ヘルスエンドポイントが想定どおりのペイロードを返す。
• 依存関係の初期化が完了している。
• CLI コマンドが想定された分岐に到達する。
• ブラウザーページが致命的なコンソール／実行時エラーなしに読み込まれる。

可能であれば、任意の固定時間だけ待つのではなく、バックオフを使った上限付きの準備完了確認ループを使用してください。

ステージ 5 — 重要な動作をプローブする

ヘルスチェックでの 200 が証明するのは、ヘルスだけです。変更した機能が /checkout なら、/healthz だけで結論を出さず、最小限で安全なチェックアウト動作／契約をプローブしてください。

リクエスト／入力と、関連するレスポンス／副作用を記録します。

ステージ 6 — 誤った／古いプロセスを検出する

出力がソースコード／ビルドの想定と矛盾する場合は、以下を確認します。

• 解決された実行可能ファイル／インポートパス。
• プロセスの起動時刻。
• ポートを所有する PID。
• ビルド／成果物のハッシュ。
• cwd/env。
• 古いサーバーがまだ実行中かどうか。

曖昧な状態が繰り返される場合は、製品ロジックを変更する前にリカバリーに引き継いでください。

ステージ 7 — 正しく終了する

この実行で所有するプロセス／リソースのみを停止します。可能であれば正常終了を待ち、必要な場合は所有するプロセスツリー内でのみ終了を強制し、一時リソースを削除します。

ステージ 8 — 実行時の証拠を限定して記録する

実行によって証明できる内容を記載します。たとえば、エントリーポイントが起動すること、エンドポイントの動作を確認したこと、正常にシャットダウンしたことなどです。より広範な正しさの検証は fable-verify に引き継ぎます。

判断ルール

• 不明なプロセスとのポート競合 → 別の安全なポートを選ぶか、所有者を調査してください。無差別に強制終了してはいけません。
• 起動に成功しても準備完了が確認できない → 予算の範囲内で待機とプローブを続け、PASS と判定しないでください。
• ヘルスチェックに成功しても変更した機能をプローブしていない → 成功として扱えるのはヘルスチェックのみです。
• 準備完了を固定時間のスリープで待つ方法は、条件を指定した範囲内でのポーリングより信頼性が低いため、観測可能な準備完了を優先してください。
• ソースの変更後も実行時の出力が変わらない → さらにコードを変更する前に、アーティファクトとプロセスの同一性を確認してください。
• 意図的にゼロ以外の終了コードで終了するワンショット CLI でも、テスト済みのエラーパスとして有効な場合があります。常に 0 を要求するのではなく、終了コードと出力を期待される契約と照合してください。
• 本番環境に近い外部への副作用が発生する場合は、安全な範囲と権限が明示されている必要があります。利用可能であれば、ローカルのフィクスチャやサンドボックスを優先してください。
• バックグラウンドプロセスには所有者を定め、テストが失敗した場合も含めてクリーンアップしてください。

不変条件

• 証拠として使用する実行時アーティファクト／プロセスの正確な同一性を特定できること。
• 無関係なプロセスを強制終了しないこと。
• 起動、準備完了、動作、シャットダウンはそれぞれ別個の主張として扱うこと。
• 実行時のプローブは、時間、出力、リソースの範囲内に収めること。
• 所有するバックグラウンドリソースは、成功時も失敗時もクリーンアップすること。
• 証拠の主張は、実際に実施したプローブの範囲を超えないこと。

失敗の分類

起動失敗

実行ファイルの欠落、権限／設定／起動エラーです。再試行する前に、コマンド、アーティファクト、環境を確認してください。

準備完了の失敗

プロセスは動作しているものの、サービスが利用可能になりません。起動ログと依存関係を収集して、原因を調査してください。

誤ったプロセスの証拠

ポート／パスが古いプロセスや無関係なプロセスを指しています。製品に変更を加えず、同一性を確認してください。

機能プローブの失敗

実行環境は準備できていますが、対象の動作が正しくありません。状況が明確であれば、検証／実行／復旧に戻ってください。

ハング／リーク

プロセスまたは子プロセスが終了しません。ライフサイクル／クリーンアップを調査し、必要な場合に限り、範囲内で所有するプロセスツリーだけを強制終了してください。

環境の不一致

動作が cwd／環境変数／OS／ランタイムのバージョンに依存しています。これを普遍的な製品の事実として扱わず、記録して整合性を確認してください。

アンチパターン

• 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