@alexkroman1/aai-cli 5.3.0 → 5.5.0

package/dist/templates/retail/store.ts

@@ -0,0 +1,243 @@
+import type { ToolContext } from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import type { z } from "zod";
+import seedJson from "./seed.json";
+import type {
+  GiftCard,
+  Order,
+  PaymentMethod,
+  Product,
+  RetailState,
+  StateSlot,
+  Store,
+  User,
+  Variant,
+} from "./shared.ts";
+import { MAX_ACTIVITY } from "./shared.ts";
+
+/**
+ * The JSON import's inferred type has `status: string` where `Order` wants a
+ * union, so a direct assignment can't type-check. The cast is validated once,
+ * for real, by `seed.test.ts` — which parses this same file through a zod
+ * schema — rather than by paying a 107 KB validation on every session start.
+ */
+const SEED = seedJson as unknown as Store;
+
+export type ErrorResult = { error: string };
+
+export function isError(value: unknown): value is ErrorResult {
+  return typeof value === "object" && value !== null && "error" in value;
+}
+
+/** Round to cents. Gift-card balances and price differences are compared for
+ *  equality, and raw float arithmetic makes that a coin toss. */
+export function money(n: number): number {
+  return Math.round(n * 100) / 100;
+}
+
+export function isGiftCard(method: PaymentMethod): method is GiftCard {
+  return method.source === "gift_card";
+}
+
+// ─── Session state ───────────────────────────────────────────────────────────
+
+/** A pristine store per session. The deep clone is load-bearing: `SEED` is one
+ *  module-level object shared by every session in the process, so a mutation
+ *  without it would let one caller's cancellation show up in another's. */
+export function createDefaultState(): RetailState {
+  return {
+    store: structuredClone(SEED),
+    authenticatedUserId: null,
+    callSeq: 0,
+    activity: [],
+    focus: {},
+  };
+}
+
+/** The session's live store. Mutations to the returned object stick — it is
+ *  the object held in `ctx.state`. */
+export function getState(ctx: ToolContext): RetailState {
+  const slot = ctx.state as StateSlot;
+  slot.retail ??= createDefaultState();
+  return slot.retail;
+}
+
+export function setFocus(
+  state: RetailState,
+  focus: { orderId?: string; productId?: string },
+): void {
+  state.focus = { ...state.focus, ...focus };
+}
+
+// ─── Lookups ─────────────────────────────────────────────────────────────────
+
+export function findUser(state: RetailState, userId: string): User | ErrorResult {
+  return state.store.users[userId] ?? { error: `User ${userId} not found.` };
+}
+
+export function findOrder(state: RetailState, orderId: string): Order | ErrorResult {
+  return state.store.orders[orderId] ?? { error: `Order ${orderId} not found.` };
+}
+
+export function findProduct(state: RetailState, productId: string): Product | ErrorResult {
+  return (
+    state.store.products[productId] ?? {
+      error: `Product ${productId} not found. Note a product id is not an item id.`,
+    }
+  );
+}
+
+export function findVariant(product: Product, itemId: string): Variant | ErrorResult {
+  return (
+    product.variants[itemId] ?? {
+      error: `Item ${itemId} is not a variant of ${product.name} (${product.product_id}).`,
+    }
+  );
+}
+
+/** Item ids carry no product reference, so finding one means scanning. */
+export function findItem(
+  state: RetailState,
+  itemId: string,
+): { product: Product; variant: Variant } | ErrorResult {
+  for (const product of Object.values(state.store.products)) {
+    const variant = product.variants[itemId];
+    if (variant) return { product, variant };
+  }
+  return { error: `Item ${itemId} not found. Note an item id is not a product id.` };
+}
+
+export function findPaymentMethod(user: User, methodId: string): PaymentMethod | ErrorResult {
+  return (
+    user.payment_methods[methodId] ?? {
+      error: `Payment method ${methodId} is not on this customer's profile. Available: ${Object.keys(
+        user.payment_methods,
+      ).join(", ")}.`,
+    }
+  );
+}
+
+// ─── Guards ──────────────────────────────────────────────────────────────────
+
+const NOT_AUTHENTICATED =
+  "Not authenticated. Identify the customer first with find_user_id_by_email, " +
+  "or find_user_id_by_name_zip if they cannot remember their email.";
+
+export function authenticatedUser(state: RetailState): User | ErrorResult {
+  if (!state.authenticatedUserId) return { error: NOT_AUTHENTICATED };
+  return findUser(state, state.authenticatedUserId);
+}
+
+/**
+ * Resolve an order that belongs to the authenticated customer.
+ *
+ * An order belonging to someone else and an order that does not exist share
+ * one template on purpose: no "belongs to another customer" vs. "does not
+ * exist" wording, no owner name, no product name — nothing that lets a
+ * caller learn something they did not already know. The echoed `orderId` is
+ * the caller's own input, not information about the store, so keeping it
+ * matches every sibling lookup (`findUser`, `findOrder`, `findProduct`, …),
+ * which all echo the id precisely so an LLM can target a repair retry.
+ */
+export function requireOwnOrder(state: RetailState, orderId: string): Order | ErrorResult {
+  const user = authenticatedUser(state);
+  if (isError(user)) return user;
+  const order = state.store.orders[orderId];
+  if (!order || order.user_id !== user.user_id) {
+    return { error: `Order ${orderId} was not found on this customer's account.` };
+  }
+  return order;
+}
+
+// ─── Serialized state updates ────────────────────────────────────────────────
+
+const sessionLocks = new Map<string, Promise<unknown>>();
+
+/**
+ * Serialized update of the session's store.
+ *
+ * The LLM loop can execute parallel tool calls, and a mutator may be async —
+ * two interleaving async mutators can each observe the other's half-applied
+ * changes. This per-session promise chain runs each update against the previous
+ * one's finished result.
+ *
+ * NOT exported, unlike dispatch-center's equivalent. `retailTool` is the only
+ * caller, so a tool body cannot re-enter it — which would chain the inner call
+ * on a tail that only resolves once the inner call finishes, i.e. deadlock. A
+ * hazard you can't reach beats a hazard you documented.
+ */
+async function updateState<R>(
+  ctx: ToolContext,
+  mutator: (state: RetailState) => R | Promise<R>,
+): Promise<R> {
+  const previous = sessionLocks.get(ctx.sessionId) ?? Promise.resolve();
+  const run = previous.then(() => mutator(getState(ctx)));
+  // Keep the chain alive across failures, and drop it once idle.
+  const tail = run.catch(() => {});
+  sessionLocks.set(ctx.sessionId, tail);
+  tail.then(() => {
+    if (sessionLocks.get(ctx.sessionId) === tail) sessionLocks.delete(ctx.sessionId);
+  });
+  return run;
+}
+
+// ─── The tool wrapper ────────────────────────────────────────────────────────
+
+interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {
+  /** Must equal this tool's key in `agent.ts`. `agent.test.ts` asserts it. */
+  name: string;
+  description: string;
+  /** Required even for no-arg tools — pass `z.object({})`. One code path in the
+   *  wrapper is worth more than saving a line at one call site. */
+  inputSchema: S;
+  /** Default true. Only the two finder tools and the three catalog tools opt
+   *  out; everything else touches customer data. */
+  requiresAuth?: boolean;
+  summary: (args: z.output<S>, result: R) => string;
+  execute: (args: z.output<S>, ctx: ToolContext) => R | Promise<R>;
+}
+
+function record(state: RetailState, name: string, summary: string): void {
+  state.callSeq += 1;
+  state.activity.push({ seq: state.callSeq, tool: name, summary, at: Date.now() });
+  if (state.activity.length > MAX_ACTIVITY) {
+    state.activity = state.activity.slice(-MAX_ACTIVITY);
+  }
+}
+
+/**
+ * Every retail tool is built through this. It owns three things no tool body
+ * may re-implement:
+ *
+ * 1. the authentication gate,
+ * 2. serialization of the state mutation,
+ * 3. the `callSeq` increment + activity entry — the reason the UI moves on
+ *    EVERY tool call rather than only when a projected value happens to differ.
+ *
+ * `focus` is deliberately left to tool bodies (`setFocus`): it is a UI nicety,
+ * not an invariant, and only the body knows what the call was about.
+ */
+export function retailTool<S extends z.ZodType<Record<string, unknown>>, R>(
+  spec: RetailToolSpec<S, R>,
+) {
+  const requiresAuth = spec.requiresAuth ?? true;
+  return tool({
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    execute: (args, ctx) =>
+      updateState(ctx, async (state) => {
+        const typedArgs = args as z.output<S>;
+        if (requiresAuth && !state.authenticatedUserId) {
+          record(state, spec.name, "blocked: not authenticated");
+          return { error: NOT_AUTHENTICATED };
+        }
+        const result = await spec.execute(typedArgs, ctx);
+        record(
+          state,
+          spec.name,
+          isError(result) ? `error: ${result.error}` : spec.summary(typedArgs, result),
+        );
+        return result;
+      }),
+  });
+}

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

@@ -0,0 +1,186 @@
+import { describe, expect, test } from "vitest";
+import { createDefaultState, findUser, isError } from "./store.ts";
+import { applySwap, assertCanCoverDiff, planItemSwap } from "./swap.ts";
+
+function fixture(orderId: string) {
+  const state = createDefaultState();
+  const order = state.store.orders[orderId];
+  if (!order) throw new Error(`fixture missing ${orderId}`);
+  return { state, order };
+}
+
+describe("planItemSwap", () => {
+  test("computes a positive price difference", () => {
+    const { state, order } = fixture("#W9311069");
+    const plan = planItemSwap(state, order, ["1304426904"], ["4725166838"], {
+      requireDifferent: true,
+    });
+    if (isError(plan)) throw new Error(plan.error);
+    expect(plan.diff).toBe(36.32);
+    expect(plan.pairs).toHaveLength(1);
+    expect(plan.pairs[0]?.newVariant.item_id).toBe("4725166838");
+  });
+
+  test("computes a negative price difference", () => {
+    const { state, order } = fixture("#W5866402");
+    const plan = planItemSwap(state, order, ["6242772310"], ["6200867091"], {
+      requireDifferent: true,
+    });
+    expect(isError(plan) ? null : plan.diff).toBe(-40.86);
+  });
+
+  test("handles a duplicate item id swapped twice", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(
+      state,
+      order,
+      ["7292993796", "7292993796"],
+      ["3909406921", "3909406921"],
+      { requireDifferent: true },
+    );
+    if (isError(plan)) throw new Error(plan.error);
+    expect(plan.diff).toBe(6.9);
+    expect(plan.pairs.map((p) => p.index)).toEqual([0, 1]);
+  });
+
+  test("swapping one of two duplicates touches only one line", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["7292993796"], ["3909406921"], {
+      requireDifferent: true,
+    });
+    if (isError(plan)) throw new Error(plan.error);
+    expect(plan.pairs).toHaveLength(1);
+    expect(plan.diff).toBe(3.45);
+  });
+
+  test("refuses asking for more copies than the order holds", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(
+      state,
+      order,
+      ["7292993796", "7292993796", "7292993796"],
+      ["3909406921", "3909406921", "3909406921"],
+      { requireDifferent: true },
+    );
+    expect(isError(plan) && plan.error).toContain("7292993796");
+  });
+
+  test("refuses mismatched list lengths", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["7292993796"], ["3909406921", "3738831434"], {
+      requireDifferent: true,
+    });
+    expect(isError(plan) && plan.error.toLowerCase()).toContain("same number");
+  });
+
+  test("refuses an empty swap", () => {
+    const { state, order } = fixture("#W4316152");
+    expect(isError(planItemSwap(state, order, [], [], { requireDifferent: true }))).toBe(true);
+  });
+
+  test("refuses an item the order does not contain", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["1304426904"], ["4725166838"], {
+      requireDifferent: true,
+    });
+    expect(isError(plan)).toBe(true);
+  });
+
+  test("refuses a target of a different product", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["7292993796"], ["4725166838"], {
+      requireDifferent: true,
+    });
+    expect(isError(plan) && plan.error).toContain("Tea Kettle");
+  });
+
+  test("refuses an unavailable target", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["7292993796"], ["6454334990"], {
+      requireDifferent: true,
+    });
+    expect(isError(plan) && plan.error.toLowerCase()).toContain("not available");
+  });
+
+  test("requireDifferent refuses a no-op swap; exchange allows it", () => {
+    const { state, order } = fixture("#W4316152");
+    const strict = planItemSwap(state, order, ["7292993796"], ["7292993796"], {
+      requireDifferent: true,
+    });
+    expect(isError(strict)).toBe(true);
+    const loose = planItemSwap(state, order, ["7292993796"], ["7292993796"], {
+      requireDifferent: false,
+    });
+    expect(isError(loose) ? null : loose.diff).toBe(0);
+  });
+});
+
+describe("assertCanCoverDiff", () => {
+  function aarav() {
+    const state = createDefaultState();
+    const user = findUser(state, "aarav_anderson_8794");
+    if (isError(user)) throw new Error(user.error);
+    return user;
+  }
+
+  test("refuses a gift card that cannot cover the difference", () => {
+    const result = assertCanCoverDiff(aarav(), "gift_card_7245904", 36.32);
+    expect(result?.error.toLowerCase()).toContain("balance");
+    expect(result?.error).toContain("17");
+  });
+
+  test("allows a difference the gift card covers", () => {
+    expect(assertCanCoverDiff(aarav(), "gift_card_7245904", 3.45)).toBeNull();
+  });
+
+  test("allows a refund direction regardless of balance", () => {
+    expect(assertCanCoverDiff(aarav(), "gift_card_7245904", -382.03)).toBeNull();
+  });
+
+  test("does not gate a non-gift-card method on any balance", () => {
+    const state = createDefaultState();
+    const olivia = findUser(state, "olivia_ito_3591");
+    if (isError(olivia)) throw new Error(olivia.error);
+    expect(assertCanCoverDiff(olivia, "credit_card_9753331", 100_000)).toBeNull();
+  });
+
+  test("refuses a method not on the profile", () => {
+    expect(assertCanCoverDiff(aarav(), "gift_card_7794233", 1)?.error).toContain("profile");
+  });
+});
+
+describe("applySwap", () => {
+  test("each swapped line takes its OWN new price and options", () => {
+    const { state, order } = fixture("#W9311069");
+    // Two different products in one call — this is what catches the leaked
+    // loop variable tau2's implementation writes prices with.
+    const plan = planItemSwap(
+      state,
+      order,
+      ["1304426904", "4238115171"],
+      ["4725166838", "3909406921"],
+      { requireDifferent: true },
+    );
+    if (isError(plan)) throw new Error(plan.error);
+    applySwap(order, plan);
+
+    const vacuum = order.items.find((i) => i.item_id === "4725166838");
+    const kettle = order.items.find((i) => i.item_id === "3909406921");
+    expect(vacuum?.price).toBe(602.11);
+    expect(kettle?.price).toBe(98.25);
+    expect(vacuum?.name).toBe("Vacuum Cleaner");
+    expect(kettle?.options).toEqual(
+      state.store.products["9832717871"]?.variants["3909406921"]?.options,
+    );
+  });
+
+  test("leaves untouched lines alone", () => {
+    const { state, order } = fixture("#W4316152");
+    const plan = planItemSwap(state, order, ["7292993796"], ["3909406921"], {
+      requireDifferent: true,
+    });
+    if (isError(plan)) throw new Error(plan.error);
+    applySwap(order, plan);
+    expect(order.items.map((i) => i.item_id)).toEqual(["3909406921", "7292993796"]);
+  });
+});

package/dist/templates/retail/swap.ts

@@ -0,0 +1,138 @@
+import type { Order, OrderItem, RetailState, User, Variant } from "./shared.ts";
+import {
+  type ErrorResult,
+  findPaymentMethod,
+  findProduct,
+  findVariant,
+  isError,
+  isGiftCard,
+  money,
+} from "./store.ts";
+
+export interface SwapPair {
+  /** Index into `order.items`. Matching by index rather than by "first item
+   *  with this id" is what makes duplicates independent of mutation order. */
+  index: number;
+  item: OrderItem;
+  newVariant: Variant;
+}
+
+export interface SwapPlan {
+  pairs: SwapPair[];
+  /** Positive = the customer owes; negative = they are owed. Cents-rounded. */
+  diff: number;
+}
+
+/**
+ * Validate a proposed item swap and compute its price difference, without
+ * mutating anything. Shared by `modify_pending_order_items` (pending, which
+ * additionally forbids a no-op swap) and `exchange_delivered_order_items`
+ * (delivered, which does not).
+ *
+ * Validation order matches tau2's so a bad call fails on the same check.
+ */
+export function planItemSwap(
+  state: RetailState,
+  order: Order,
+  itemIds: string[],
+  newItemIds: string[],
+  opts: { requireDifferent: boolean },
+): SwapPlan | ErrorResult {
+  if (itemIds.length === 0) {
+    return { error: "No items were listed to change." };
+  }
+  if (itemIds.length !== newItemIds.length) {
+    return {
+      error: `Got ${itemIds.length} item(s) to change but ${newItemIds.length} replacement(s) — the lists must hold the same number, each replacement matching the item in the same position.`,
+    };
+  }
+
+  // Duplicate-aware availability: an order holding one of an item cannot have
+  // two of them changed.
+  const heldCounts = new Map<string, number>();
+  for (const item of order.items) {
+    heldCounts.set(item.item_id, (heldCounts.get(item.item_id) ?? 0) + 1);
+  }
+  const askedCounts = new Map<string, number>();
+  for (const itemId of itemIds) {
+    askedCounts.set(itemId, (askedCounts.get(itemId) ?? 0) + 1);
+  }
+  for (const [itemId, asked] of askedCounts) {
+    const held = heldCounts.get(itemId) ?? 0;
+    if (asked > held) {
+      return {
+        error: `Order ${order.order_id} holds ${held} of item ${itemId}, but ${asked} were listed to change.`,
+      };
+    }
+  }
+
+  const consumed = new Set<number>();
+  const pairs: SwapPair[] = [];
+  let diff = 0;
+
+  for (const [position, itemId] of itemIds.entries()) {
+    const newItemId = newItemIds[position];
+    if (!newItemId) {
+      return { error: `No replacement was given for item ${itemId}.` };
+    }
+    if (opts.requireDifferent && newItemId === itemId) {
+      return {
+        error: `Item ${itemId} was listed as its own replacement. Pick a different option of the same product, or leave it out.`,
+      };
+    }
+
+    const index = order.items.findIndex((item, i) => item.item_id === itemId && !consumed.has(i));
+    const item = order.items[index];
+    if (index === -1 || !item) {
+      return { error: `Item ${itemId} is not in order ${order.order_id}.` };
+    }
+    consumed.add(index);
+
+    const product = findProduct(state, item.product_id);
+    if (isError(product)) return product;
+
+    const newVariant = findVariant(product, newItemId);
+    if (isError(newVariant)) {
+      return {
+        error: `${newItemId} is not an option of ${product.name} (${product.product_id}). An item can only be changed to a different option of the same product — you cannot change a ${product.name} into something else.`,
+      };
+    }
+    if (!newVariant.available) {
+      return {
+        error: `${product.name} option ${newItemId} (${Object.values(newVariant.options).join(", ")}) is not available.`,
+      };
+    }
+
+    diff += newVariant.price - item.price;
+    pairs.push({ index, item, newVariant });
+  }
+
+  return { pairs, diff: money(diff) };
+}
+
+/**
+ * Gate the price difference on the chosen payment method. Only a gift card has
+ * a balance to run out of; a negative difference is a refund and never gated.
+ */
+export function assertCanCoverDiff(user: User, methodId: string, diff: number): ErrorResult | null {
+  const method = findPaymentMethod(user, methodId);
+  if (isError(method)) return method;
+  if (isGiftCard(method) && method.balance < diff) {
+    return {
+      error: `Gift card ${methodId}'s balance ($${method.balance.toFixed(2)}) does not cover the $${diff.toFixed(2)} difference. Ask for another payment method.`,
+    };
+  }
+  return null;
+}
+
+/** Apply a validated plan. Each line takes its OWN new variant's price, options
+ *  and name — see the module note on tau2's leaked loop variable. */
+export function applySwap(order: Order, plan: SwapPlan): void {
+  for (const pair of plan.pairs) {
+    const line = order.items[pair.index];
+    if (!line) continue;
+    line.item_id = pair.newVariant.item_id;
+    line.price = pair.newVariant.price;
+    line.options = pair.newVariant.options;
+  }
+}

package/dist/templates/retail/system-prompt.md

@@ -0,0 +1,111 @@
+You are a retail customer-service agent for an online store, talking to a
+customer on the phone. You can help them cancel or modify pending orders,
+return or exchange delivered orders, update their default address, and answer
+questions about their own profile, orders and our products.
+
+# Authenticate first
+
+Before anything else, identify who you are talking to by finding their user id
+— by email (`find_user_id_by_email`), or by first name, last name and zip code
+(`find_user_id_by_name_zip`) if they cannot remember the email. Do this **even
+if the caller volunteers their user id**.
+
+Prefer email. Fall back to name + zip only when they cannot recall the address
+on the account.
+
+# One customer per call
+
+You help exactly one customer per conversation. You may handle any number of
+requests from that person, but you must refuse anything to do with anybody
+else's account, and you cannot switch to a different customer mid-call — ask
+them to call back.
+
+# Confirm every change out loud
+
+Before any action that changes something — cancel, modify, return, exchange —
+say what you are about to do, including the order, the items, the amounts and
+where money is going, and wait for an explicit "yes". Never act on an implied
+yes.
+
+# Never invent anything
+
+Only tell the customer what the tools and the customer themselves have told
+you. Do not guess at policy, stock, delivery dates, or prices, and do not offer
+opinions or recommendations about products. If you do not know, say so.
+
+Refuse requests that fall outside this policy.
+
+# One thing at a time
+
+Make at most one tool call at a time. When you make a tool call, do not also
+speak; when you speak, do not also make a tool call.
+
+# Handing off to a human
+
+Transfer only if the caller explicitly asks for a human, or their request
+cannot be handled with your tools and this policy. Call
+`transfer_to_human_agents` first, then say exactly: "You are being transferred
+to a human agent. Please hold on." Say nothing else after that.
+
+# Speaking on the phone
+
+- The customer can see their orders on screen. Say "your pending order" or "the
+  espresso machine order" rather than reciting an order number.
+- When you do have to say an order number, read it in groups: "W, seven six
+  seven, eight zero seven two" — never as one long run of digits.
+- **Never read a ten-digit item number out loud** unless the customer asks for
+  it. Name the item and its options instead: "the glass two-litre kettle".
+- When a customer gives you a number, read it back before you use it.
+- Prices: "three hundred and twenty dollars and fifty cents", not "320.50".
+- Keep replies to one or two sentences. This is a phone call, not an email.
+- Do not spell out tool names, statuses in snake_case, or user ids.
+
+# What the tools accept
+
+Order references can be spoken: "my pending order", "the delivered one", "the
+second pending order". If a reference is ambiguous the tool will tell you which
+orders matched — ask the customer which one, never pick for them.
+
+Item references can be spoken too: "the blue medium" resolves against a
+product's options.
+
+# The rules that bite
+
+**All times in the store's records are EST, 24-hour.** "02:30:00" is 2:30 in
+the morning.
+
+**Cancelling a pending order.** Only an order whose status is exactly
+"pending". Check the status first. The reason must be either "no longer needed"
+or "ordered by mistake" — if the customer gives another reason, tell them those
+are the only two we can record and ask which fits. A gift-card refund lands
+immediately; everything else takes 5 to 7 business days.
+
+**Changing the items in a pending order is once-only and irreversible.** After
+it, the order cannot be cancelled or modified again — not by you, not by
+anyone. So before you call it: get the customer to confirm they have named
+**every** item they want changed, then read the complete list and the price
+difference back. Ask "is that everything you want to change?" explicitly. An
+item can only become a different option of the same product — a shirt cannot
+become shoes.
+
+**Changing a pending order's payment method.** One method only, and it must be
+different from the current one. A gift card must cover the whole order total.
+The old method is refunded.
+
+**Returning a delivered order.** Only "delivered", only once. The refund goes
+to the original payment method or to one of their gift cards — nothing else.
+Confirm the exact item list. The customer gets an email about sending things
+back.
+
+**Exchanging a delivered order.** Only "delivered", only once. Same-product
+options only. Remind them to name every item first, exactly as with modifying a
+pending order. The price difference is charged to or refunded from a payment
+method they choose; a gift card must cover a positive difference. No new order
+is needed.
+
+**Processed orders.** Once an order is "processed" it has left us — it cannot be
+cancelled or modified. It can be returned or exchanged once it is delivered.
+
+**Product ids and item ids are different things** and are never
+interchangeable. A product is "Tea Kettle"; an item is one specific kettle with
+its own material, capacity and stovetop compatibility.