Runのライフサイクルと復旧

このページは、Runを運用するすべての人のためのものです。Runが通る状態、status の読み方、Runが中断したときに何が起こるか、結果の分からない書き込みをどう解決するか、キャンセルの仕方、Resultの受け取り方を示します。各段階の背後にある保証は、実行モデルと保証にあります。

状態Copy Anchor Link

Runは常に、次のいずれか1つの状態にあります。

preparing → running → succeeded
                   ↘ waiting_checkpoint → resuming → running
                   ↘ needs_reconciliation → running | succeeded | failed
                   ↘ failed
                   ↘ cancelled

succeeded、failed、cancelled は最終状態です。結果が1つでも不明なあいだは、これらの状態にはなりません。

ポリシーは、Runができる前に要求を保留することもあります。CLIでは held、SDKでは RequestHeld として報告されます。同じ approve か reject で解決し、承認されるとRunが始まります。

statusの読み方Copy Anchor Link

actql status <run> は、現在の状態と、状態に応じてCheckpoint、Effectとその項目、または失敗の内容を表示します。

$ actql status run_…
Run run_…
  Status      waiting_checkpoint
  Checkpoint  ckpt_…
  Effect      update  (Salesforce Account)
  Items       2
  Changes
    Acme Corp     Churn_Risk__c   low     → high
                  Risk_Reason__c  (empty) → falling usage and a competitor evaluation
    Globex Inc    Churn_Risk__c   medium  → high
                  Risk_Reason__c  (empty) → support tickets about pricing

$ actql status run_…
Run run_…
  Status   succeeded
  Effect   update  (Salesforce Account)   2 items
    Acme Corp     applied
    Globex Inc    applied
  Results  updates  2 rows

$ actql status run_…
Run run_…
  Status   needs_reconciliation
  Effect   update  (Salesforce Account)   2 items
    Acme Corp     applied
    Globex Inc    unknown   reply lost after send; reconciling with Salesforce

status は現在の状態を1回読むだけで、外部システムには何も送りません。status --watch は変化を表示し、あなたの対応が必要な次の状態（waiting_checkpoint、needs_reconciliation、または最終状態）で戻ります。--watch --until final は承認をまたいで最後まで追いかけ、--timeout 10m はどちらの待ち時間も区切ります。--json はRunの状態をデータとして返すので、自動化ではテキストを解析せずこちらを使ってください。なお、run と status の終了コードは、コマンド自体が成功すれば 0 です。Runが waiting_checkpoint や failed でも同じで、状態は出力の中にあります。

コードからは、execution.status() が待たずに状態を読み、execution.wait() が次の安定した状態、つまり待機状態か最終状態で戻ります。Runがすでに安定した状態なら、wait() はその状態をすぐに返します。その次の状態を待つには、見た状態のrevisionを渡します：wait({since: state.revision})。

中断と再開Copy Anchor Link

Runは、どの時点でも止まることがあります。プロセスが落ちる、マシンが再起動する、ネットワークが切れる、判断に1日かかる、などです。Runがそれまでに見たもの、つまり取り込んだ読み取り、LLMの答え、プレビュー、Effectの結果はすべてStoreにあるので、最初からやり直すのではなく、止まったところから続きます。

• 読み取りは繰り返しません。取り込んだ観測を再利用します。
• LLMに聞き直すことはありません。採用した答えを再利用します。
• applied と記録されたEffectを再送することはありません。

再起動のあとに続けるには、同じStoreを開いてRunに接続します。

actql status run_…           # 中断していれば、Hostが再開する

復旧はHostの仕事です。Storeを開くと、Hostは進行中だった処理を続けます。status と explain --run は読むだけで、外部への操作を始めたり再送したりすることはありません。

const client = await connect({mode: 'local', installation: {directory: '.actql'}});
const execution = await client.attach(ref);      // ref は execution.ref から保存したもの
const state = await execution.wait();

waiting_checkpoint だったRunは、再起動をまたいでもその状態のままです。あとで承認すれば続きます。Runが頼りにしているStore、権限、保持期間が失われている場合、Runは黙って最初からやり直すのではなく、何が足りないかを報告します。

不明な結果と突き合わせCopy Anchor Link

書き込みは、はっきりした答えのないまま終わることがあります。リクエストは送られたのに、応答が失われた場合です。ActQLはその項目を unknown として記録し、Runを needs_reconciliation に移し、書き込みを再送しません。もう一度送れば、二重に適用されるかもしれないからです。

reconcile は、元の操作の識別情報を使って、何が起きたかをConnectorに調べさせます。

$ actql reconcile run_…
Effect  update  (Salesforce Account)
  Globex Inc    applied   confirmed: Salesforce returned the operation for request marker actql-7f3…
Run run_…  succeeded

Connectorが結果を確定できれば、項目は applied か failed になり、Runは先に進みます。確定できなければ、つまりそのシステムに操作を照会する手段がないか、証拠が決め手にならなければ、項目は unknown のままで、試みは記録され、Runは待ち続けます。あとでもう一度 reconcile を実行しても安全です。証跡として数えるのは、Connectorが認めるものだけです。リクエストのマーカーで見つかった操作、プロバイダーの操作ID、元のリクエストと相関できる監査記録などです。外部システムに同じ値が入っていることや、送信のあとにレコードが変更されたことは証拠になりません。別の何かが変えたのかもしれないからです。

実行そのものが失われた場合も、同じ状態で扱います。ある処理単位が終わったかどうかをHostが判断できなければ、続ける前にそれを突き合わせます。

キャンセルCopy Anchor Link

$ actql cancel run_…
Run run_…  cancelling

キャンセルは、新しい処理の開始を止め、実行中の処理には停止を求めます。停止が確認され、不明なものが残っていないと分かって、はじめてRunは cancelled になります。送信中に unknown で終わった書き込みは、先に突き合わせが必要です。キャンセルは巻き戻しではありません。送った読み取りも、適用したEffectも、そのまま残ります。

ResultCopy Anchor Link

プログラムの名前付きResultは、プログラムが終わったときに公開されます。run が表示するのはRunの状態で、レコードは表示しません。読むには result を使います。

actql result run_… --result updates --format jsonl       # 標準出力にレコードを出す
actql result run_… --deliver updates=csv:updates.csv      # ファイルに書く

--deliver は複数のResultに対して繰り返し指定でき、完了した配信を1つずつ覚えています。同じResultを同じ出力先に二重に書くことはなく、失敗した配信は同じコマンドで再試行されます。別の出力先を指定すれば、それは新しい配信です。コードからは、execution.result('updates').all() がレコードを返します。

Resultも、Runのほかのすべてと同じく、Hostの保持期間だけ保持されます。残しておきたいものは書き出してください。

次に読むCopy Anchor Link

• Effectと承認：Checkpointと、その解決の仕方
• デバッグとトラブルシューティング：失敗の読み方
• CLIリファレンス：status、reconcile、cancel、result のすべてのフラグ