export type Step = {
  name: string;
  run: (orderId: string) => Promise<void>;
  compensate: (orderId: string) => Promise<void>;
};
 
export type SagaResult =
  | { status: "completed" }
  | { status: "compensated"; failedStep: string }
  | { status: "stuck"; failedStep: string; stuckStep: string };
 
export async function runSaga(
  steps: Step[],
  orderId: string,
  log: string[] = [],
  maxCompensateAttempts = 3,
): Promise<SagaResult> {
  const attempted: Step[] = [];
  for (const step of steps) {
    attempted.push(step); // 失敗した step も補償対象に含める
    try {
      log.push(`run:${step.name}`);
      await step.run(orderId);
    } catch {
      for (const done of [...attempted].reverse()) {
        let ok = false;
        for (let i = 0; i < maxCompensateAttempts && !ok; i++) {
          try {
            log.push(`compensate:${done.name}`);
            await done.compensate(orderId);
            ok = true;
          } catch {
            /* 同じ補償を再試行する */
          }
        }
        if (!ok) {
          return { status: "stuck", failedStep: step.name, stuckStep: done.name };
        }
      }
      return { status: "compensated", failedStep: step.name };
    }
  }
  return { status: "completed" };
}

import type { Step } from "./saga.ts";
 
export type FaultPoint = { step: string; when: "before" | "after" };
 
export function createWorld(
  fault?: FaultPoint,
  compensateFailsOnce?: string,
) {
  const state = {
    stock: 5,
    reservations: new Set<string>(),
    charges: new Map<string, number>(), // orderId -> 正味の請求額
    labels: new Set<string>(),
  };
  const failedCompensations = new Set<string>();
 
  // after: 副作用は成功したのに応答だけ失敗した状況(タイムアウト等)
  async function withFault<T>(name: string, effect: () => T): Promise<void> {
    const hit = fault?.step === name ? fault.when : undefined;
    if (hit === "before") throw new Error(`injected:${name}:before`);
    effect();
    if (hit === "after") throw new Error(`injected:${name}:after`);
  }
 
  async function failOnceIfAsked(name: string) {
    if (compensateFailsOnce === name && !failedCompensations.has(name)) {
      failedCompensations.add(name);
      throw new Error(`compensation-failed:${name}`);
    }
  }
 
  const steps: Step[] = [
    {
      name: "reserve",
      run: (id) => withFault("reserve", () => {
        if (state.reservations.has(id)) return; // 冪等
        state.reservations.add(id);
        state.stock -= 1;
      }),
      compensate: async (id) => {
        await failOnceIfAsked("reserve");
        if (!state.reservations.delete(id)) return; // 無ければ何もしない
        state.stock += 1;
      },
    },
    {
      name: "charge",
      run: (id) => withFault("charge", () => {
        if (state.charges.has(id)) return;
        state.charges.set(id, 3000);
      }),
      compensate: async (id) => {
        await failOnceIfAsked("charge");
        if (!state.charges.has(id)) return;
        state.charges.set(id, 0); // 返金済み。2回目も結果は同じ
      },
    },
    {
      name: "label",
      run: (id) => withFault("label", () => { state.labels.add(id); }),
      compensate: async (id) => {
        await failOnceIfAsked("label");
        state.labels.delete(id);
      },
    },
  ];
  return { state, steps };
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { runSaga } from "./saga.ts";
import { createWorld, type FaultPoint } from "./services.ts";
 
const names = ["reserve", "charge", "label"];
const points: FaultPoint[] = names.flatMap((step) => [
  { step, when: "before" as const },
  { step, when: "after" as const },
]);
 
type World = ReturnType<typeof createWorld>;
 
function snapshot(w: World) {
  const { stock, reservations, charges, labels } = w.state;
  const rows = [stock, [...reservations], [...charges], [...labels]];
  return JSON.stringify(rows);
}
 
function netCharge(w: World) {
  return [...w.state.charges.values()].reduce((a, b) => a + b, 0);
}
 
const verbs = (log: string[], prefix: string) =>
  log.filter((l) => l.startsWith(prefix)).map((l) => l.slice(prefix.length));
 
for (const fault of points) {
  const label = `${fault.step}/${fault.when}`;
 
  test(`失敗注入 ${label}: 元に戻り、補償は逆順`, async () => {
    const w = createWorld(fault);
    const log: string[] = [];
    const result = await runSaga(w.steps, "o-1", log);
    assert.equal(result.status, "compensated");
    assert.equal(w.state.stock, 5);
    assert.equal(w.state.reservations.size, 0);
    assert.equal(netCharge(w), 0);
    assert.equal(w.state.labels.size, 0);
    const ran = verbs(log, "run:");
    assert.deepEqual(verbs(log, "compensate:"), [...ran].reverse());
  });
 
  test(`冪等性 ${label}: 補償を再実行しても同じ`, async () => {
    const w = createWorld(fault);
    await runSaga(w.steps, "o-1");
    const before = snapshot(w);
    for (const s of [...w.steps].reverse()) await s.compensate("o-1");
    assert.equal(snapshot(w), before);
  });
}
 
test("補償が一度失敗しても再試行で収束する", async () => {
  const w = createWorld({ step: "label", when: "before" }, "charge");
  const log: string[] = [];
  const result = await runSaga(w.steps, "o-1", log);
  assert.equal(result.status, "compensated");
  assert.equal(netCharge(w), 0);
  assert.equal(verbs(log, "compensate:").filter((n) => n === "charge").length, 2);
});
 
test("正常系は完了し、補償は呼ばれない", async () => {
  const w = createWorld();
  const log: string[] = [];
  assert.equal((await runSaga(w.steps, "o-1", log)).status, "completed");
  assert.equal(verbs(log, "compensate:").length, 0);
  assert.equal(w.state.stock, 4);
});

## サーガのテスト
- ステップは `{ name, run, compensate }`。`compensate` は冪等にする
  (未実行でも、2回目でも何も壊さない)
- 失敗注入は全ステップ × before/after の総当たり。
  失敗したステップ自身も補償対象に含める
- 補償の期待順序は仕様として決め、順序をテストで固定する
- 実装を意図的に壊してテストが落ちることを確認する(補償を
  順方向にする / 失敗ステップを外す / 返金を非冪等にする)
- 完了報告には `npx tsx --test` の出力を付ける

注文サーガ(reserve → charge → label)に補償を実装して。
先に saga.test.ts を書き、全ステップ × before/after に失敗を注入して
状態が初期値に戻ること、補償が実行順の逆であること、補償を再実行
しても状態が変わらないことを検証して。全部通るまで直し、最後に
テストの出力を貼って。

---
name: saga-fault-reviewer
description: サーガの実装とテストを読み、失敗注入の抜けを指摘する。サーガのテストを書いた後に使う
tools: Read, Grep, Glob
---
 
サーガの実装とテストを読み、次を表にして報告する。
1. ステップごとの before/after 注入が、テストにあるか
2. 補償が「未実行でも何もしない」「2回目も同じ」になっているか
3. 補償自体が失敗する経路のテストがあるか
実装やテストは編集しない。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "npx tsx --test saga.test.ts 1>&2 || exit 2" }
        ]
      }
    ]
  }
}