@alexkroman1/aai-cli 7.0.0 → 8.0.0

package/dist/templates/retail/cancel.ts

@@ -0,0 +1,116 @@
+/**
+ * Cancelling a pending order, as a PLAN and an APPLY.
+ *
+ * The split is what the confirmation gate is built out of, and it is the same
+ * split in all seven mutating actions here: `plan*` validates everything and
+ * computes the effect without touching the store, `apply*` performs it and
+ * cannot fail. A staged plan is what the caller says yes to, so the validation
+ * has to happen BEFORE the readback — a "yes" followed by a refusal is the one
+ * sequence this gate exists to make impossible.
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { creditRefund, REFUND_DELAY_NOTE, REFUND_IMMEDIATE_NOTE } from "./refund.ts";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, money } from "./store.ts";
+
+/** The only two reasons the store records. */
+export const CANCEL_REASONS = ["no longer needed", "ordered by mistake"] as const;
+export type CancelReason = (typeof CANCEL_REASONS)[number];
+
+/**
+ * A validated cancellation, holding only storable primitives.
+ *
+ * No `Order` or `PaymentMethod` reference: a plan is written into the session
+ * slot and rides across turns, so a live object here would alias the store and
+ * a persisted session could not carry it. Ids and amounts are enough, and
+ * looking them up again at apply time is what keeps {@link applyCancel}
+ * total.
+ */
+export interface CancelPlan {
+  /** The sentence the agent reads back before asking for a yes. */
+  readBack: string;
+  orderId: string;
+  reason: CancelReason;
+  refunds: { methodId: string; amount: number }[];
+  total: number;
+}
+
+export function planCancel(
+  state: RetailState,
+  spokenOrderId: string,
+  reason: CancelReason,
+): CancelPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  // The enum makes this unreachable from a well-formed call; it stays because
+  // the reason is the one field a caller supplies in free speech, and an LLM
+  // tool call arrives untyped.
+  if (!CANCEL_REASONS.includes(reason)) {
+    return {
+      error: `'${reason}' is not an accepted cancellation reason. It must be 'no longer needed' or 'ordered by mistake'.`,
+    };
+  }
+
+  // Exactly 'pending'. A 'pending (item modified)' order has spent its one
+  // modification and is past cancelling.
+  if (order.status !== "pending") {
+    return {
+      error: `Order ${order.order_id} is ${order.status}, and only a pending order can be cancelled.`,
+    };
+  }
+
+  const refunds = order.payment_history
+    .filter((payment) => payment.transaction_type === "payment")
+    .map((payment) => ({ methodId: payment.payment_method_id, amount: payment.amount }));
+  const total = money(refunds.reduce((sum, refund) => sum + refund.amount, 0));
+
+  const items = order.items.map((item) => item.name).join(", ");
+  const destinations = [...new Set(refunds.map((refund) => refund.methodId))].join(" and ");
+  return {
+    readBack:
+      `cancel order ${order.order_id} (${items}) as '${reason}' and refund ` +
+      `$${total.toFixed(2)} to ${destinations}`,
+    orderId: order.order_id,
+    reason,
+    refunds,
+    total,
+  };
+}
+
+/** The effect. Total by construction: every id in the plan was resolved from
+ *  this same store, and nothing between staging and confirming can remove one. */
+export function applyCancel(state: RetailState, plan: CancelPlan) {
+  const order = state.store.orders[plan.orderId];
+  const user = order ? state.store.users[order.user_id] : undefined;
+  let immediate = false;
+
+  if (order && user) {
+    for (const refund of plan.refunds) {
+      immediate = creditRefund(user, refund.methodId, refund.amount).immediate || immediate;
+      order.payment_history.push({
+        transaction_type: "refund",
+        amount: refund.amount,
+        payment_method_id: refund.methodId,
+      });
+    }
+    order.status = "cancelled";
+    order.cancel_reason = plan.reason;
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: "cancelled" as const,
+    cancel_reason: plan.reason,
+    refunded: plan.total,
+    refund_immediate: immediate,
+    message: `Order ${plan.orderId} is cancelled and $${plan.total.toFixed(2)} is being refunded. ${
+      immediate ? REFUND_IMMEDIATE_NOTE : REFUND_DELAY_NOTE
+    }`,
+  };
+}

package/dist/templates/retail/client.tsx

@@ -13,6 +13,7 @@ import type {
   OrderStatus,
   OrderView,
   PaymentMethodView,
+  PendingView,
   StoreView,
   SwapOptionView,
 } from "./shared.ts";
@@ -155,6 +156,42 @@ function OrderCard({ order, focused }: { order: OrderView; focused: boolean }) {
 
 /** Character select. Rendered before authentication, because a user with no
  *  email to give cannot start the conversation at all. */
+/**
+ * The change waiting on the caller's word.
+ *
+ * The one panel that renders BECAUSE nothing has happened. A staged change is
+ * the agent's promise about what it is going to do, so showing it beside the
+ * orders it has not touched is what lets a watcher catch a readback that does
+ * not match the request — which is the failure the whole gate is aimed at, and
+ * the one nobody can see from a transcript alone.
+ */
+function PendingChange({ pending }: { pending: PendingView }) {
+  return (
+    <div
+      className="rounded-lg p-3"
+      style={{
+        background: "#fffbeb",
+        border: "1px solid #fcd34d",
+        animation: "rt-slide-in 180ms ease-out",
+      }}
+    >
+      <div
+        className="text-[10px] font-semibold uppercase tracking-wider mb-1.5 flex items-center gap-1.5"
+        style={{ color: "#b45309" }}
+      >
+        <span style={{ animation: "rt-pulse 1.4s ease-in-out infinite" }}>●</span>
+        Awaiting the caller's yes
+      </div>
+      <div className="text-xs leading-relaxed" style={{ color: "#78350f" }}>
+        {pending.readBack}
+      </div>
+      <div className="text-[10px] mt-1.5" style={{ color: "#a16207" }}>
+        Nothing has changed yet — {pending.kind}
+      </div>
+    </div>
+  );
+}
+
 function PersonaList() {
   return (
     <div className="flex flex-col gap-2">
@@ -489,6 +526,8 @@ function App() {
             className="rt-scroll overflow-y-auto p-3 flex flex-col gap-3"
             style={{ background: "#f4f4f5" }}
           >
+            {view.pending && <PendingChange pending={view.pending} />}
+
             {!view.customer && (
               <Panel title="Who to be">
                 <PersonaList />

package/dist/templates/retail/payment.ts

@@ -0,0 +1,107 @@
+/**
+ * Changing which payment method a pending order is charged to, as a plan and an
+ * apply (see `cancel.ts` for why every mutating action is split that way).
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, findPaymentMethod, isGiftCard, money } from "./store.ts";
+
+export interface PaymentPlan {
+  readBack: string;
+  orderId: string;
+  /** Where the order is charged after the change. */
+  newMethodId: string;
+  /** Where the original charge goes back to. */
+  oldMethodId: string;
+  amount: number;
+}
+
+export function planPayment(
+  state: RetailState,
+  spokenOrderId: string,
+  newMethodId: string,
+): PaymentPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  if (!order.status.startsWith("pending")) {
+    return {
+      error: `Order ${order.order_id} is ${order.status}, and only a pending order's payment method can be changed.`,
+    };
+  }
+
+  const newMethod = findPaymentMethod(user, newMethodId);
+  if (isToolFailure(newMethod)) return newMethod;
+
+  const original = order.payment_history[0];
+  if (order.payment_history.length !== 1 || original?.transaction_type !== "payment") {
+    return {
+      error: `Order ${order.order_id} does not have exactly one payment on record, so its payment method cannot be changed.`,
+    };
+  }
+  if (original.payment_method_id === newMethodId) {
+    return {
+      error: `Order ${order.order_id} is already paid with ${newMethodId}. The new method must be different.`,
+    };
+  }
+
+  const amount = original.amount;
+  if (isGiftCard(newMethod) && newMethod.balance < amount) {
+    return {
+      error: `Gift card ${newMethodId}'s balance ($${newMethod.balance.toFixed(2)}) does not cover the $${amount.toFixed(2)} order total.`,
+    };
+  }
+
+  return {
+    readBack:
+      `charge order ${order.order_id} — $${amount.toFixed(2)} — to ${newMethodId} instead, ` +
+      `refunding ${original.payment_method_id}`,
+    orderId: order.order_id,
+    newMethodId,
+    oldMethodId: original.payment_method_id,
+    amount,
+  };
+}
+
+export function applyPayment(state: RetailState, plan: PaymentPlan) {
+  const order = state.store.orders[plan.orderId];
+  const user = order ? state.store.users[order.user_id] : undefined;
+
+  if (order && user) {
+    order.payment_history.push(
+      {
+        transaction_type: "payment",
+        amount: plan.amount,
+        payment_method_id: plan.newMethodId,
+      },
+      {
+        transaction_type: "refund",
+        amount: plan.amount,
+        payment_method_id: plan.oldMethodId,
+      },
+    );
+
+    const newMethod = user.payment_methods[plan.newMethodId];
+    if (newMethod && isGiftCard(newMethod)) {
+      newMethod.balance = money(newMethod.balance - plan.amount);
+    }
+    const oldMethod = user.payment_methods[plan.oldMethodId];
+    if (oldMethod && isGiftCard(oldMethod)) {
+      oldMethod.balance = money(oldMethod.balance + plan.amount);
+    }
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: order?.status ?? "pending",
+    amount: plan.amount,
+    paid_with: plan.newMethodId,
+    refunded_to: plan.oldMethodId,
+    message: `Order ${plan.orderId} is now charged to ${plan.newMethodId}, and $${plan.amount.toFixed(2)} is going back to ${plan.oldMethodId}.`,
+  };
+}

package/dist/templates/retail/pending.test.ts

@@ -0,0 +1,196 @@
+import type { ToolContext } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
+import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import type { StagedResult } from "./pending.ts";
+import { retailSlot } from "./store.ts";
+import cancelChange from "./tools/cancel_change.ts";
+import cancelPendingOrder from "./tools/cancel_pending_order.ts";
+import confirmChange from "./tools/confirm_change.ts";
+import findUserIdByEmail from "./tools/find_user_id_by_email.ts";
+import getOrderDetails from "./tools/get_order_details.ts";
+import modifyUserAddress from "./tools/modify_user_address.ts";
+import returnDeliveredOrderItems from "./tools/return_delivered_order_items.ts";
+import transferToHumanAgents from "./tools/transfer_to_human_agents.ts";
+
+/** Aarav Anderson: one pending order (#W9300146, $153.23 on a gift card) and
+ *  one delivered order (#W4316152), which is every shape these cases need. */
+async function aaravCtx(): Promise<ToolContext> {
+  const ctx = createToolContext();
+  ok(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
+  return ctx;
+}
+
+const stageCancel = (ctx: ToolContext) =>
+  cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx);
+
+describe("staging", () => {
+  test("a staging tool changes NOTHING and moves the call to awaitingConfirmation", async () => {
+    const ctx = await aaravCtx();
+    const before = structuredClone(retailSlot.get(ctx).store.orders["#W9300146"]);
+
+    const staged = okPosition<StagedResult>(await stageCancel(ctx));
+
+    expect(staged.state).toBe("serving.awaitingConfirmation");
+    expect(staged.result.staged).toBe("cancel_pending_order");
+    // The whole claim of this template's policy section, as one assertion: the
+    // tool that used to cancel and refund on its first call now does neither.
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]).toEqual(before);
+    const card =
+      retailSlot.get(ctx).store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    expect(card?.source === "gift_card" && card.balance).toBe(17);
+  });
+
+  test("the readback names the order, the items, the amount and where the money goes", async () => {
+    const ctx = await aaravCtx();
+    const staged = ok<StagedResult>(await stageCancel(ctx));
+    expect(staged.read_back).toContain("#W9300146");
+    expect(staged.read_back).toContain("153.23");
+    expect(staged.read_back).toContain("gift_card_7245904");
+    expect(staged.read_back).toContain("no longer needed");
+  });
+
+  test("the result says out loud that nothing has happened", async () => {
+    const ctx = await aaravCtx();
+    const staged = ok<StagedResult>(await stageCancel(ctx));
+    expect(staged.message).toContain("NOTHING HAS CHANGED YET");
+    expect(staged.message).toContain("confirm_change");
+  });
+
+  test("a second stage is refused, and the refusal names the one already waiting", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    // A DIFFERENT change, so this is not a repeat of the first call.
+    const second = await modifyUserAddress.execute(
+      {
+        user_id: "aarav_anderson_8794",
+        address1: "1 A St",
+        address2: "",
+        city: "Springfield",
+        state: "OR",
+        country: "USA",
+        zip: "97477",
+      },
+      ctx,
+    );
+    expect(isToolFailure(second)).toBe(true);
+    // Naming the waiting sentence is why the staging tools are gated on
+    // `serving` rather than on `serving.helping`: a state's instruction is
+    // static and could only have said which STATE the call is in.
+    expect(isToolFailure(second) && second.error).toContain("#W9300146");
+    expect(isToolFailure(second) && second.error).toContain("cancel_change");
+    expect(retailSlot.get(ctx).store.users.aarav_anderson_8794?.address.city).not.toBe(
+      "Springfield",
+    );
+  });
+});
+
+describe("confirming", () => {
+  test("confirm_change applies the staged change and returns to helping", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const done = okPosition<{ confirmed: string; status: string }>(
+      await confirmChange.execute({}, ctx),
+    );
+    expect(done.state).toBe("serving.helping");
+    expect(done.result.confirmed).toBe("cancel_pending_order");
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("cancelled");
+    expect(retailSlot.get(ctx).pending).toBeNull();
+  });
+
+  test("confirm_change with nothing staged is refused by the GATE, before its body", async () => {
+    const ctx = await aaravCtx();
+    const result = await confirmChange.execute({}, ctx);
+    expect(isToolFailure(result)).toBe(true);
+    // The SDK writes this refusal from `when` plus the state's instruction, so
+    // it says where the call is rather than merely that this was not allowed —
+    // and the body, which is the only thing in the template that mutates, never
+    // ran to find out.
+    expect(isToolFailure(result) && result.error).toContain("serving.helping");
+    expect(isToolFailure(result) && result.error).toContain("STAGES");
+  });
+
+  test("confirming twice is refused — the second call has nothing staged", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    ok(await confirmChange.execute({}, ctx));
+
+    const again = await confirmChange.execute({}, ctx);
+    expect(isToolFailure(again)).toBe(true);
+    // One cancellation, one refund: a double-apply would have credited the card
+    // twice, which is the failure a "did we already do this?" flag gets wrong.
+    const card =
+      retailSlot.get(ctx).store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    expect(card?.source === "gift_card" && card.balance).toBe(170.23);
+  });
+});
+
+describe("cancelling a staged change", () => {
+  test("cancel_change drops it, changes nothing, and frees the call", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const dropped = okPosition<{ dropped: string | null; message: string }>(
+      await cancelChange.execute({}, ctx),
+    );
+    expect(dropped.state).toBe("serving.helping");
+    expect(dropped.result.dropped).toBe("cancel_pending_order");
+    expect(dropped.result.message).toContain("#W9300146");
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("pending");
+    expect(retailSlot.get(ctx).pending).toBeNull();
+  });
+
+  test("a corrected change can be staged straight after", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    ok(await cancelChange.execute({}, ctx));
+
+    // The caller changed their mind about which order — the very thing
+    // `cancel_change` exists for.
+    const restaged = ok<StagedResult>(
+      await returnDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
+    );
+    expect(restaged.staged).toBe("return_delivered_order_items");
+  });
+});
+
+describe("what stays legal while a change waits", () => {
+  test("a read is still answerable — 'what was the total again?'", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    // `when: "serving"` matches both children, which is what makes this work.
+    const read = okPosition<{ order_id: string }>(
+      await getOrderDetails.execute({ order_id: "#W9300146" }, ctx),
+    );
+    expect(read.result.order_id).toBe("#W9300146");
+    // A read does not settle anything, so the change is still waiting.
+    expect(read.state).toBe("serving.awaitingConfirmation");
+  });
+
+  test("a caller can still ask for a human, and everything refuses afterwards", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const transferred = okPosition(
+      await transferToHumanAgents.execute({ summary: "wants a human" }, ctx),
+    );
+    // `TRANSFERRED` is declared on the `serving` PARENT, which is what lets it
+    // fire from inside the confirmation.
+    expect(transferred.state).toBe("transferred");
+    expect(transferred.done).toBe(true);
+
+    // Including the two settling tools: a call given away cannot be finished.
+    expect(isToolFailure(await confirmChange.execute({}, ctx))).toBe(true);
+    expect(isToolFailure(await cancelChange.execute({}, ctx))).toBe(true);
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("pending");
+  });
+});

package/dist/templates/retail/pending.ts

@@ -0,0 +1,137 @@
+/**
+ * The change waiting on the caller's word — what is staged, and what applying
+ * it does.
+ *
+ * Retail's policy has always said "confirm every change out loud … never act on
+ * an implied yes", and for a long time the only thing carrying that was prose:
+ * the sentence sat in the system prompt and in seven tool descriptions, and
+ * `cancel_pending_order` cancelled and refunded on its first call whether or not
+ * a word had been said. A rule enforced by asking a model nicely is not a rule.
+ *
+ * It is a MECHANISM now, and the mechanism is two halves that need each other:
+ *
+ * 1. **No tool mutates.** The seven changing tools validate everything, price
+ *    it, write a {@link PendingAction} here and return the sentence to read
+ *    back. `confirm_change` is the only thing in the template that writes to
+ *    the store.
+ * 2. **`confirm_change` is gated on a STATE.** `callFlow`'s
+ *    `serving.awaitingConfirmation` (`store.ts`) is reachable only by staging,
+ *    so confirming a change nobody staged is refused by the SDK before the body
+ *    runs — and the refusal says where the call is and what has to happen first.
+ *
+ * The half that is not enforceable stays honest about it: nothing here can know
+ * that the agent really SAID the sentence, or that the caller really answered
+ * yes. What the gate buys is that a change cannot happen in the same turn it was
+ * described in — the model has to come back for a second call, with the caller's
+ * answer in between — which is the property the prose could not have.
+ *
+ * Adapted from `travel-concierge`, whose `stageAction`/`confirm_action` pair is
+ * the same shape one domain over. The difference worth noting: its plans are
+ * re-derived at confirm time, and these are computed once at stage time and held
+ * as primitives. That is deliberate — see `cancel.ts`. A "yes" must never be
+ * followed by a refusal.
+ */
+
+import type { ToolFailure } from "@alexkroman1/aai";
+import type { OrderAddressPlan, UserAddressPlan } from "./address.ts";
+import { applyOrderAddress, applyUserAddress } from "./address.ts";
+import { applyCancel, type CancelPlan } from "./cancel.ts";
+import { applyPayment, type PaymentPlan } from "./payment.ts";
+import { applyReturn, type ReturnPlan } from "./returns.ts";
+import type { RetailState } from "./shared.ts";
+import type { ExchangePlan, ModifyItemsPlan } from "./swap.ts";
+import { applyExchange, applyModifyItems } from "./swap.ts";
+
+/**
+ * A validated, priced, not-yet-applied change.
+ *
+ * `kind` is the NAME OF THE TOOL that staged it, so the activity feed, the
+ * sidebar and every refusal can say which change is waiting in the same words
+ * the model called it by.
+ */
+export type PendingAction =
+  | { kind: "cancel_pending_order"; plan: CancelPlan }
+  | { kind: "modify_pending_order_address"; plan: OrderAddressPlan }
+  | { kind: "modify_pending_order_items"; plan: ModifyItemsPlan }
+  | { kind: "modify_pending_order_payment"; plan: PaymentPlan }
+  | { kind: "modify_user_address"; plan: UserAddressPlan }
+  | { kind: "return_delivered_order_items"; plan: ReturnPlan }
+  | { kind: "exchange_delivered_order_items"; plan: ExchangePlan };
+
+/** What a staging tool answers with: the sentence, and nothing done yet. */
+export interface StagedResult {
+  staged: PendingAction["kind"];
+  read_back: string;
+  message: string;
+}
+
+/**
+ * Put a change in front of the caller.
+ *
+ * A SECOND stage is refused rather than queued, and the refusal names the
+ * sentence already waiting — which is the whole reason the staging tools are
+ * gated on `serving` (either child) rather than on `serving.helping`. A state
+ * gate could only say "you are at serving.awaitingConfirmation", a state's
+ * instruction being static; this can say *which* change is waiting, which is
+ * what lets the model settle that one and re-stage the other. Same resolution
+ * as `travel-concierge`, and for the same reason.
+ */
+export function stageAction(state: RetailState, action: PendingAction): StagedResult | ToolFailure {
+  const waiting = state.pending;
+  if (waiting) {
+    return {
+      error:
+        `A change is already waiting on the caller's yes: "${waiting.plan.readBack}". ` +
+        "Settle that one with confirm_change or cancel_change, then stage this one.",
+    };
+  }
+  state.pending = action;
+  return {
+    staged: action.kind,
+    read_back: action.plan.readBack,
+    message:
+      `NOTHING HAS CHANGED YET. Read this back to the caller — "${action.plan.readBack}" — ` +
+      "and wait for an explicit yes. Then call confirm_change, or cancel_change if they say no.",
+  };
+}
+
+/**
+ * Perform the staged change.
+ *
+ * Total: every plan was validated against this same store, and nothing between
+ * staging and confirming can invalidate one — `confirm_change` and
+ * `cancel_change` are the only tools legal in `awaitingConfirmation`, and
+ * neither is a mutation the other's plan depends on. That totality is the
+ * point. An `applyAction` that could fail would mean a caller saying yes and
+ * hearing "actually, no", which is exactly the outcome staging exists to
+ * prevent.
+ */
+export function applyAction(state: RetailState, action: PendingAction) {
+  switch (action.kind) {
+    case "cancel_pending_order":
+      return applyCancel(state, action.plan);
+    case "modify_pending_order_address":
+      return applyOrderAddress(state, action.plan);
+    case "modify_pending_order_items":
+      return applyModifyItems(state, action.plan);
+    case "modify_pending_order_payment":
+      return applyPayment(state, action.plan);
+    case "modify_user_address":
+      return applyUserAddress(state, action.plan);
+    case "return_delivered_order_items":
+      return applyReturn(state, action.plan);
+    case "exchange_delivered_order_items":
+      return applyExchange(state, action.plan);
+    default: {
+      // Unreachable: the seven arms above exhaust `PendingAction`, and this
+      // ASSIGNMENT is what keeps that true — an eighth member of the union
+      // stops compiling here rather than falling silently through to a change
+      // nobody applies. It exists because biome's `useDefaultSwitchClause`
+      // wants an arm, not because a call can reach it, which is why it throws
+      // rather than answering the `ToolFailure` the rest of this template
+      // prefers: there is no live call on this path to recover.
+      const unreachable: never = action;
+      throw new Error(`No apply for staged action ${JSON.stringify(unreachable)}`);
+    }
+  }
+}