@porulle/core 0.7.0 → 0.9.0

package/src/modules/orders/service.ts

@@ -2,6 +2,7 @@ import { resolveOrgId } from "../../auth/org.js";
 import { assertOwnership, assertPermission } from "../../auth/permissions.js";
 import type { Actor } from "../../auth/types.js";
 import {
+  CommerceForbiddenError,
   CommerceInvalidTransitionError,
   CommerceNotFoundError,
   CommerceValidationError,
@@ -24,18 +25,25 @@ import {
 import { Err, Ok, type Result } from "../../kernel/result.js";
 import { createLogger } from "../../utils/logger.js";
 import { paginate, type Pagination } from "../../utils/pagination.js";
-import type { TxContext } from "../../kernel/database/tx-context.js";
+import {
+  withTransaction,
+  type TxContext,
+} from "../../kernel/database/tx-context.js";
 import type { DatabaseAdapter } from "../../kernel/database/adapter.js";
 import type { PluginDb } from "../../kernel/database/plugin-types.js";
 import {
   OrdersRepository,
   type Order,
   type OrderLineItem,
+  type OrderNote,
+  type OrderRefund,
   type OrderStatusHistory,
 } from "./repository/index.js";
 
 export interface CreateOrderInput {
   customerId?: string;
+  /** Client-supplied retry key — a repeat create with the same key returns the original order. */
+  idempotencyKey?: string | undefined;
   currency: string;
   subtotal: number;
   taxTotal: number;
@@ -144,11 +152,128 @@ export class OrderService {
     return { ...order, lineItems };
   }
 
+  /**
+   * Resolve every line item's price with org-integrity + price provenance,
+   * mirroring how our forefathers handle this (Vendure: order lines are always
+   * server-priced from the variant; Medusa: an admin override is honored but
+   * flagged `is_custom_price`). Three modes:
+   *   - trusted caller (checkout / POS exchange, already server-priced) → prices honored as-is.
+   *   - actor with `orders:manage` → explicit price honored as a manual override, flagged isCustomPrice.
+   *   - otherwise → price re-derived server-side from the catalog; client prices ignored.
+   * The referenced entity MUST belong to the order's org in every mode.
+   */
+  private async resolveLines(
+    input: CreateOrderInput,
+    actor: Actor | null,
+    trusted: boolean,
+    ctx: TxContext | undefined,
+  ): Promise<Result<Array<CreateOrderInput["lineItems"][number] & { isCustomPrice: boolean }>>> {
+    let canOverride = trusted;
+    if (!canOverride) {
+      try {
+        assertPermission(actor, "orders:manage");
+        canOverride = true;
+      } catch {
+        canOverride = false;
+      }
+    }
+    const catalog = this.deps.services.catalog as {
+      getById(
+        id: string,
+        options: Record<string, unknown>,
+        actor?: Actor | null,
+        ctx?: TxContext,
+      ): Promise<{
+        ok: boolean;
+        value?: { variants?: Array<{ id: string }> };
+      }>;
+    };
+    const pricing = this.deps.services.pricing as {
+      resolve(
+        input: {
+          entityId: string;
+          variantId?: string;
+          currency: string;
+          quantity: number;
+          customerId?: string;
+        },
+        actor?: Actor | null,
+        ctx?: TxContext,
+      ): Promise<{ ok: boolean; value?: { finalAmount: number } }>;
+    };
+    const resolved: Array<
+      CreateOrderInput["lineItems"][number] & { isCustomPrice: boolean }
+    > = [];
+    for (const item of input.lineItems) {
+      // Org-integrity — the referenced entity must belong to this order's org.
+      const owned = await catalog.getById(
+        item.entityId,
+        { includeVariants: item.variantId !== undefined },
+        actor,
+        ctx,
+      );
+      if (!owned.ok) {
+        return Err(
+          new CommerceValidationError(
+            `Line item entity ${item.entityId} does not belong to this organization.`,
+          ),
+        );
+      }
+      if (
+        item.variantId !== undefined &&
+        !owned.value?.variants?.some((variant) => variant.id === item.variantId)
+      ) {
+        return Err(
+          new CommerceValidationError(
+            `Line item variant ${item.variantId} does not belong to entity ${item.entityId}.`,
+          ),
+        );
+      }
+      if (trusted || canOverride) {
+        // Trusted pipeline totals, or a staff manual/negotiated override.
+        resolved.push({ ...item, isCustomPrice: !trusted && canOverride });
+        continue;
+      }
+      // Server-derive the price; the client-supplied unitPrice/totalPrice is ignored.
+      const priced = await pricing.resolve(
+        {
+          entityId: item.entityId,
+          currency: input.currency,
+          quantity: item.quantity,
+          ...(item.variantId ? { variantId: item.variantId } : {}),
+          ...(input.customerId ? { customerId: input.customerId } : {}),
+        },
+        actor,
+        ctx,
+      );
+      if (!priced.ok || !priced.value) {
+        return Err(
+          new CommerceValidationError(`Cannot resolve price for ${item.entityId}.`),
+        );
+      }
+      const unitPrice = priced.value.finalAmount;
+      resolved.push({
+        ...item,
+        unitPrice,
+        totalPrice: unitPrice * item.quantity,
+        isCustomPrice: false,
+      });
+    }
+    return Ok(resolved);
+  }
+
   async create(
     input: CreateOrderInput,
     actor: Actor | null,
     ctx?: TxContext,
+    opts?: { trustedPricing?: boolean; stockPolicy?: "reserve" | "backorder" },
   ): Promise<Result<HydratedOrder>> {
+    if (opts?.stockPolicy === "reserve" && !ctx) {
+      return withTransaction(this.deps.database, { actor }, (txCtx) =>
+        this.create(input, actor, txCtx, opts),
+      );
+    }
+
     try {
       assertPermission(actor, "orders:create");
     } catch (error) {
@@ -176,39 +301,124 @@ export class OrderService {
       hookCtx,
     );
 
-    const orderNumber = await this.repo.getNextOrderNumber(ctx);
     const orgId = resolveOrgId(actor);
 
-    const order = await this.repo.create(
-      {
-        organizationId: orgId,
-        orderNumber,
-        status: "pending",
-        currency: processed.currency,
-        subtotal: processed.subtotal,
-        taxTotal: processed.taxTotal,
-        shippingTotal: processed.shippingTotal,
-        discountTotal: processed.discountTotal ?? 0,
-        grandTotal: processed.grandTotal,
-        ...(processed.paymentIntentId != null ? { paymentIntentId: processed.paymentIntentId } : {}),
-        ...(processed.paymentMethodId != null ? { paymentMethodId: processed.paymentMethodId } : {}),
-        metadata: processed.metadata ?? {},
-        placedAt: new Date(),
-        ...(processed.customerId !== undefined
-          ? { customerId: processed.customerId }
-          : {}),
-      },
-      ctx,
-    );
+    // Idempotent replay: offline POS queues and network retries re-submit the
+    // same create — return the original order instead of double-creating.
+    if (processed.idempotencyKey) {
+      const existing = await this.repo.findByIdempotencyKey(
+        orgId,
+        processed.idempotencyKey,
+        ctx,
+      );
+      if (existing) {
+        return Ok(await this.hydrateOrder(existing, ctx));
+      }
+    }
+
+    // Resolve line prices with org-integrity + provenance (see resolveLines).
+    const trusted = opts?.trustedPricing === true;
+    const resolvedResult = await this.resolveLines(processed, actor, trusted, ctx);
+    if (!resolvedResult.ok) return Err(resolvedResult.error);
+    const resolvedLines = resolvedResult.value;
+
+    // Order totals: trusted callers (checkout / exchange) supply rich totals
+    // (promotions, tax, shipping); otherwise derive from the server-priced lines.
+    const computedSubtotal = trusted
+      ? processed.subtotal
+      : resolvedLines.reduce(
+          (sum, l) => sum + (l.totalPrice ?? l.unitPrice * l.quantity),
+          0,
+        );
+    const computedGrandTotal = trusted
+      ? processed.grandTotal
+      : computedSubtotal +
+        processed.taxTotal +
+        processed.shippingTotal -
+        (processed.discountTotal ?? 0);
+
+    // Stock: order creation does NOT reserve by default. Stock is allocated at
+    // the lifecycle transition to a committed state — checkout reserves in its
+    // own pipeline, mirroring Vendure's StockAllocationStrategy (allocate on
+    // PaymentAuthorized, not on creation). A caller that represents an immediate
+    // committed sale (e.g. a POS exchange) opts in with stockPolicy: "reserve".
+    const stockPolicy = opts?.stockPolicy;
+    if (stockPolicy === "reserve") {
+      const inventory = this.deps.services.inventory as {
+        getAvailable(
+          entityId: string,
+          variantId: string | undefined,
+          ctx?: TxContext,
+          actor?: Actor | null,
+        ): Promise<{ ok: boolean; value?: number }>;
+      };
+      for (const line of resolvedLines) {
+        const avail = await inventory.getAvailable(
+          line.entityId,
+          line.variantId,
+          ctx,
+          actor,
+        );
+        if (!avail.ok || (avail.value ?? 0) < line.quantity) {
+          return Err(
+            new CommerceValidationError(
+              `Insufficient stock for ${line.title ?? line.entityId}. Available: ${
+                avail.ok ? (avail.value ?? 0) : 0
+              }, requested: ${line.quantity}.`,
+            ),
+          );
+        }
+      }
+    }
+
+    const orderNumber = await this.repo.getNextOrderNumber(ctx);
+
+    let order: Order;
+    try {
+      order = await this.repo.create(
+        {
+          organizationId: orgId,
+          orderNumber,
+          status: "pending",
+          currency: processed.currency,
+          subtotal: computedSubtotal,
+          taxTotal: processed.taxTotal,
+          shippingTotal: processed.shippingTotal,
+          discountTotal: processed.discountTotal ?? 0,
+          grandTotal: computedGrandTotal,
+          ...(processed.paymentIntentId != null ? { paymentIntentId: processed.paymentIntentId } : {}),
+          ...(processed.paymentMethodId != null ? { paymentMethodId: processed.paymentMethodId } : {}),
+          ...(processed.idempotencyKey != null ? { idempotencyKey: processed.idempotencyKey } : {}),
+          metadata: processed.metadata ?? {},
+          placedAt: new Date(),
+          ...(processed.customerId !== undefined
+            ? { customerId: processed.customerId }
+            : {}),
+        },
+        ctx,
+      );
+    } catch (error) {
+      // Concurrent replay lost the unique-index race — return the winner.
+      if (processed.idempotencyKey) {
+        const winner = await this.repo.findByIdempotencyKey(
+          orgId,
+          processed.idempotencyKey,
+          ctx,
+        );
+        if (winner) return Ok(await this.hydrateOrder(winner, ctx));
+      }
+      throw error;
+    }
 
-    const lineItemsData = processed.lineItems.map((item) => ({
+    const lineItemsData = resolvedLines.map((item) => ({
       orderId: order.id,
       entityId: item.entityId,
       entityType: item.entityType,
       title: item.title,
       quantity: item.quantity,
       unitPrice: item.unitPrice,
-      totalPrice: item.totalPrice,
+      totalPrice: item.totalPrice ?? item.unitPrice * item.quantity,
+      isCustomPrice: item.isCustomPrice,
       taxAmount: item.taxAmount ?? 0,
       discountAmount: item.discountAmount ?? 0,
       fulfillmentStatus: "unfulfilled" as const,
@@ -219,6 +429,45 @@ export class OrderService {
 
     await this.repo.createLineItems(lineItemsData, ctx);
 
+    // Reserve stock for the resolved lines when the reserve policy is active
+    // (availability was verified above). Trusted callers reserve themselves.
+    if (stockPolicy === "reserve") {
+      const inventory = this.deps.services.inventory as {
+        reserve(
+          input: {
+            entityId: string;
+            quantity: number;
+            orderId: string;
+            variantId?: string;
+          },
+          actor?: Actor | null,
+          ctx?: TxContext,
+        ): Promise<{ ok: boolean; error?: unknown }>;
+      };
+      for (const line of resolvedLines) {
+        const reserved = await inventory.reserve(
+          {
+            entityId: line.entityId,
+            quantity: line.quantity,
+            orderId: order.id,
+            ...(line.variantId ? { variantId: line.variantId } : {}),
+          },
+          actor,
+          ctx,
+        );
+        if (!reserved.ok) {
+          return Err(
+            toCommerceError(
+              reserved.error ??
+                new CommerceValidationError(
+                  `Unable to reserve stock for ${line.title ?? line.entityId}.`,
+                ),
+            ),
+          );
+        }
+      }
+    }
+
     await this.repo.createStatusHistory(
       {
         orderId: order.id,
@@ -294,6 +543,18 @@ export class OrderService {
     return this.getById(order.id, actor, ctx);
   }
 
+  /** Returns the order previously created with this idempotency key, or null. */
+  async getByIdempotencyKey(
+    idempotencyKey: string,
+    actor?: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder | null>> {
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findByIdempotencyKey(orgId, idempotencyKey, ctx);
+    if (!order) return Ok(null);
+    return Ok(await this.hydrateOrder(order, ctx));
+  }
+
   async list(
     params: ListOrdersParams,
     actor: Actor | null,
@@ -472,6 +733,19 @@ export class OrderService {
     const previous = order.status;
     const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
 
+    // R-04: goods must not ship against refunded lines. Reject the fulfilled
+    // transition if any line has been (partially) refunded.
+    if (
+      input.newStatus === "fulfilled" &&
+      lineItems.some((li) => li.refundedQuantity > 0)
+    ) {
+      return Err(
+        new CommerceValidationError(
+          "Cannot fulfill an order that has refunded line items.",
+        ),
+      );
+    }
+
     // VAPT r2 (codex) finding: side effects (inventory release, payment
     // refund, tax void) used to run BEFORE the atomic compare-and-swap on
     // updateStatus. Two parallel cancel/refund requests on the same order
@@ -499,13 +773,17 @@ export class OrderService {
       // 1. Release inventory reservations
       const inventory = this.deps.services.inventory as
         | {
-            release(input: {
-              entityId: string;
-              variantId?: string;
-              quantity: number;
-              orderId: string;
-              performedBy?: string;
-            }): Promise<unknown>;
+            release(
+              input: {
+                entityId: string;
+                variantId?: string;
+                quantity: number;
+                orderId: string;
+                performedBy?: string;
+              },
+              actor?: Actor | null,
+              ctx?: TxContext,
+            ): Promise<Result<void>>;
           }
         | undefined;
 
@@ -515,15 +793,30 @@ export class OrderService {
           // Fulfilled items had their reservation released during the
           // fulfilled transition — releasing again would double-release.
           if (lineItem.fulfillmentStatus === "unfulfilled") {
-            await inventory.release({
-              entityId: lineItem.entityId,
-              quantity: lineItem.quantity,
-              orderId: order.id,
-              performedBy: actor?.userId ?? "system",
-              ...(lineItem.variantId != null
-                ? { variantId: lineItem.variantId }
-                : {}),
-            });
+            const releaseResult = await inventory.release(
+              {
+                entityId: lineItem.entityId,
+                quantity: lineItem.quantity,
+                orderId: order.id,
+                performedBy: actor?.userId ?? "system",
+                ...(lineItem.variantId != null
+                  ? { variantId: lineItem.variantId }
+                  : {}),
+              },
+              actor,
+              ctx,
+            );
+            if (!releaseResult.ok) {
+              const err = toCommerceError(releaseResult.error);
+              if (
+                !(
+                  err instanceof CommerceValidationError &&
+                  err.message === "No inventory record found for this entity."
+                )
+              ) {
+                return Err(err);
+              }
+            }
           }
         }
       }
@@ -545,19 +838,27 @@ export class OrderService {
           | undefined;
 
         if (payments?.refund) {
-          const maxRefund = Math.min(
-            order.grandTotal,
-            order.amountCaptured ?? order.grandTotal,
+          // R-01: subtract prior gateway refunds (line-level refundLines, and
+          // undone refunds — the gateway was never reversed) so this order-level
+          // refund can't double-pay on top of what has already been refunded.
+          const priorRefunds = await this.repo.findRefundsByOrderId(order.id, ctx);
+          const alreadyRefunded = priorRefunds.reduce((sum, r) => sum + r.amount, 0);
+          const maxRefund = Math.max(
+            0,
+            Math.min(order.grandTotal, order.amountCaptured ?? order.grandTotal) -
+              alreadyRefunded,
           );
           const refundAmount =
             input.refundAmount != null
               ? Math.min(input.refundAmount, maxRefund)
               : maxRefund;
-          await payments.refund(
-            paymentIntentId,
-            refundAmount,
-            input.reason ?? `order_${input.newStatus}`,
-          );
+          if (refundAmount > 0) {
+            await payments.refund(
+              paymentIntentId,
+              refundAmount,
+              input.reason ?? `order_${input.newStatus}`,
+            );
+          }
         }
       }
 
@@ -590,13 +891,17 @@ export class OrderService {
               orderId: string;
               orgId?: string;
             }): Promise<unknown>;
-            release(input: {
-              entityId: string;
-              variantId?: string;
-              quantity: number;
-              orderId: string;
-              performedBy?: string;
-            }): Promise<unknown>;
+            release(
+              input: {
+                entityId: string;
+                variantId?: string;
+                quantity: number;
+                orderId: string;
+                performedBy?: string;
+              },
+              actor?: Actor | null,
+              ctx?: TxContext,
+            ): Promise<Result<void>>;
           }
         | undefined;
 
@@ -615,15 +920,30 @@ export class OrderService {
             });
 
             // Release reservation (no longer needed)
-            await inventory.release({
-              entityId: lineItem.entityId,
-              quantity: lineItem.quantity,
-              orderId: order.id,
-              performedBy: actor?.userId ?? "system",
-              ...(lineItem.variantId != null
-                ? { variantId: lineItem.variantId }
-                : {}),
-            });
+            const releaseResult = await inventory.release(
+              {
+                entityId: lineItem.entityId,
+                quantity: lineItem.quantity,
+                orderId: order.id,
+                performedBy: actor?.userId ?? "system",
+                ...(lineItem.variantId != null
+                  ? { variantId: lineItem.variantId }
+                  : {}),
+              },
+              actor,
+              ctx,
+            );
+            if (!releaseResult.ok) {
+              const err = toCommerceError(releaseResult.error);
+              if (
+                !(
+                  err instanceof CommerceValidationError &&
+                  err.message === "No inventory record found for this entity."
+                )
+              ) {
+                return Err(err);
+              }
+            }
 
             // Mark line item as fulfilled
             await this.repo.updateLineItem(
@@ -698,6 +1018,424 @@ export class OrderService {
     );
   }
 
+  // ── Line-level refund policy primitives (issue #52) ─────────────────────
+
+  private async refundPolicies(orgId: string, ctx?: TxContext): Promise<{
+    cap: number | null;
+    undoWindowMinutes: number;
+    timezone: string;
+  }> {
+    const settings = this.deps.services.settings as
+      | { read(orgId: string, group: string, ctx?: TxContext): Promise<Record<string, unknown>> }
+      | undefined;
+    const policies = (await settings?.read(orgId, "policies", ctx)) ?? {};
+    const general = (await settings?.read(orgId, "general", ctx)) ?? {};
+    return {
+      cap: typeof policies.refundDailyCap === "number" ? policies.refundDailyCap : null,
+      undoWindowMinutes:
+        typeof policies.refundUndoWindowMinutes === "number"
+          ? policies.refundUndoWindowMinutes
+          : 15,
+      timezone: typeof general.timezone === "string" ? general.timezone : "UTC",
+    };
+  }
+
+  /**
+   * Refunds specific line-item quantities (issue #52). Enforces per-line
+   * refundable quantity (`quantity - refundedQuantity`), the operator's daily
+   * refund cap (`policies.refundDailyCap`, 403 with the cap surfaced), moves
+   * money through the payment adapter when the order has a captured payment,
+   * and records an auditable `order_refunds` ledger row.
+   */
+  async refundLines(
+    orderId: string,
+    input: { lines: Array<{ lineItemId: string; quantity: number }>; reason?: string | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ order: HydratedOrder; refund: OrderRefund }>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const found = await this.repo.findWithLineItems(orgId, orderId, ctx);
+    if (!found) return Err(new CommerceNotFoundError("Order not found."));
+    if (input.lines.length === 0) {
+      return Err(new CommerceValidationError("At least one line is required."));
+    }
+    // R-02: a terminal order (cancelled / fully refunded) cannot be line-refunded.
+    if (this.machine.terminal.includes(found.order.status)) {
+      return Err(
+        new CommerceValidationError(
+          `Cannot refund an order in terminal status "${found.order.status}".`,
+        ),
+      );
+    }
+    // R-03: a refund moves collected money — reject an unpaid order (otherwise a
+    // "refund" is recorded against funds never taken). "Paid" is either a core
+    // captured payment (checkout: amountCaptured > 0) or the order having left
+    // the initial pending state (e.g. a completed POS/in-store sale). Only a
+    // still-pending, uncaptured order is treated as unpaid.
+    if ((found.order.amountCaptured ?? 0) <= 0 && found.order.status === "pending") {
+      return Err(
+        new CommerceValidationError(
+          "Cannot refund an unpaid order (no captured payment and still pending).",
+        ),
+      );
+    }
+
+    const byId = new Map(found.lineItems.map((li) => [li.id, li]));
+    const refundLines: Array<{ lineItemId: string; quantity: number; amount: number }> = [];
+    for (const line of input.lines) {
+      const lineItem = byId.get(line.lineItemId);
+      if (!lineItem) {
+        return Err(new CommerceNotFoundError(`Line item ${line.lineItemId} not found on this order.`));
+      }
+      if (!Number.isInteger(line.quantity) || line.quantity < 1) {
+        return Err(new CommerceValidationError("Refund quantity must be a positive integer."));
+      }
+      const refundable = lineItem.quantity - lineItem.refundedQuantity;
+      if (line.quantity > refundable) {
+        return Err(
+          new CommerceValidationError(
+            `Line "${lineItem.title}" has ${refundable} refundable unit(s); requested ${line.quantity}.`,
+          ),
+        );
+      }
+      // Effective paid per unit: line total + tax − discount, split evenly.
+      const lineValue = lineItem.totalPrice + lineItem.taxAmount - lineItem.discountAmount;
+      const amount = Math.round((lineValue * line.quantity) / lineItem.quantity);
+      refundLines.push({ lineItemId: lineItem.id, quantity: line.quantity, amount });
+    }
+    const totalAmount = refundLines.reduce((sum, l) => sum + l.amount, 0);
+
+    const performedBy = actor?.userId ?? "system";
+    const policies = await this.refundPolicies(orgId, ctx);
+    if (policies.cap != null) {
+      const usedToday = await this.repo.sumRefundsByOperatorToday(
+        orgId,
+        performedBy,
+        policies.timezone,
+        ctx,
+      );
+      if (usedToday + totalAmount > policies.cap) {
+        return Err(
+          new CommerceForbiddenError(
+            `Daily refund cap exceeded: cap ${policies.cap}, used ${usedToday} today, requested ${totalAmount}.`,
+          ),
+        );
+      }
+    }
+
+    // Move money if a captured payment exists — clamped to what remains.
+    if (found.order.paymentIntentId && (found.order.amountCaptured ?? 0) > 0) {
+      const payments = this.deps.services.payments as
+        | { refund(paymentId: string, amount: number, reason?: string): Promise<unknown> }
+        | undefined;
+      if (payments?.refund) {
+        const priorRefunds = await this.repo.findRefundsByOrderId(orderId, ctx);
+        // Gross total incl. UNDONE refunds: undoRefund reverses the local ledger
+        // but not the payment gateway, so that money already left. Counting only
+        // "completed" would let refund → undo → refund re-issue a gateway refund
+        // (F-04 / R-05 / R-07). Capping on gross keeps total payout ≤ captured.
+        const alreadyRefunded = priorRefunds.reduce((sum, r) => sum + r.amount, 0);
+        const refundable = Math.max(0, (found.order.amountCaptured ?? 0) - alreadyRefunded);
+        const payAmount = Math.min(totalAmount, refundable);
+        if (payAmount > 0) {
+          await payments.refund(
+            found.order.paymentIntentId,
+            payAmount,
+            input.reason ?? "line_refund",
+          );
+        }
+      }
+    }
+
+    for (const line of refundLines) {
+      const lineItem = byId.get(line.lineItemId)!;
+      await this.repo.updateLineItem(
+        line.lineItemId,
+        { refundedQuantity: lineItem.refundedQuantity + line.quantity },
+        ctx,
+      );
+    }
+    const refund = await this.repo.createRefund(
+      {
+        organizationId: orgId,
+        orderId,
+        amount: totalAmount,
+        reason: input.reason ?? null,
+        lines: refundLines,
+        performedBy,
+      },
+      ctx,
+    );
+    await this.repo.createStatusHistory(
+      {
+        orderId,
+        fromStatus: found.order.status,
+        toStatus: found.order.status,
+        reason: `refund ${refund.id}: ${totalAmount} (${input.reason ?? "line refund"})`,
+        changedBy: performedBy,
+      },
+      ctx,
+    );
+
+    const hydrated = await this.hydrateOrder(
+      (await this.repo.findById(orgId, orderId, ctx))!,
+      ctx,
+    );
+    return Ok({ order: hydrated, refund });
+  }
+
+  /**
+   * Undoes a refund within the configured window
+   * (`policies.refundUndoWindowMinutes`, default 15). Restores line
+   * refundedQuantity and marks the ledger row `undone` — an audited,
+   * compensating ledger operation; re-collecting the money (cash back into
+   * the drawer) is the operator's side of the exchange.
+   */
+  async undoRefund(
+    orderId: string,
+    refundId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ order: HydratedOrder; refund: OrderRefund }>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const refund = await this.repo.findRefundById(orgId, refundId, ctx);
+    if (!refund || refund.orderId !== orderId) {
+      return Err(new CommerceNotFoundError("Refund not found."));
+    }
+    if (refund.status !== "completed") {
+      return Err(new CommerceValidationError("Refund has already been undone."));
+    }
+    const policies = await this.refundPolicies(orgId, ctx);
+    const ageMs = Date.now() - refund.createdAt.getTime();
+    if (ageMs > policies.undoWindowMinutes * 60_000) {
+      return Err(
+        new CommerceValidationError(
+          `Refund undo window (${policies.undoWindowMinutes} minutes) has passed.`,
+        ),
+      );
+    }
+
+    const performedBy = actor?.userId ?? "system";
+    const undone = await this.repo.markRefundUndone(refundId, performedBy, ctx);
+    if (!undone) {
+      return Err(new CommerceValidationError("Refund has already been undone."));
+    }
+    for (const line of refund.lines) {
+      const lineItem = await this.repo.findLineItemById(line.lineItemId, ctx);
+      if (lineItem) {
+        await this.repo.updateLineItem(
+          line.lineItemId,
+          { refundedQuantity: Math.max(0, lineItem.refundedQuantity - line.quantity) },
+          ctx,
+        );
+      }
+    }
+    await this.repo.createStatusHistory(
+      {
+        orderId,
+        fromStatus: "refund_completed",
+        toStatus: "refund_undone",
+        reason: `refund ${refundId} undone (${refund.amount})`,
+        changedBy: performedBy,
+      },
+      ctx,
+    );
+
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    const hydrated = await this.hydrateOrder(order!, ctx);
+    return Ok({ order: hydrated, refund: undone });
+  }
+
+  async listRefunds(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderRefund[]>> {
+    try {
+      assertPermission(actor, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    return Ok(await this.repo.findRefundsByOrderId(orderId, ctx));
+  }
+
+  /** The acting operator's daily refund-cap status (issue #52). */
+  async refundCapStatus(
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ cap: number | null; usedToday: number; remaining: number | null }>> {
+    try {
+      assertPermission(actor, "orders:read");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const policies = await this.refundPolicies(orgId, ctx);
+    const usedToday = await this.repo.sumRefundsByOperatorToday(
+      orgId,
+      actor?.userId ?? "system",
+      policies.timezone,
+      ctx,
+    );
+    return Ok({
+      cap: policies.cap,
+      usedToday,
+      remaining: policies.cap != null ? Math.max(0, policies.cap - usedToday) : null,
+    });
+  }
+
+  // ── Order notes + activity timeline (issue #56) ─────────────────────────
+
+  private async requireOrderAccess(
+    orderId: string,
+    actor: Actor | null,
+    perm: "orders:read" | "orders:update",
+    ctx?: TxContext,
+  ): Promise<Result<Order>> {
+    try {
+      assertPermission(actor, perm);
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    return Ok(order);
+  }
+
+  async addNote(
+    orderId: string,
+    input: { body: string; pinned?: boolean | undefined },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderNote>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:update", ctx);
+    if (!order.ok) return order;
+    if (!input.body.trim()) {
+      return Err(new CommerceValidationError("Note body must not be empty."));
+    }
+    const note = await this.repo.createNote(
+      {
+        organizationId: order.value.organizationId,
+        orderId,
+        author: actor?.userId ?? "system",
+        body: input.body,
+        pinned: input.pinned ?? false,
+      },
+      ctx,
+    );
+    return Ok(note);
+  }
+
+  async listNotes(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<OrderNote[]>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:read", ctx);
+    if (!order.ok) return order;
+    return Ok(await this.repo.findNotesByOrderId(orderId, ctx));
+  }
+
+  async deleteNote(
+    orderId: string,
+    noteId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<{ deleted: true }>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:update", ctx);
+    if (!order.ok) return order;
+    const deleted = await this.repo.deleteNote(order.value.organizationId, orderId, noteId, ctx);
+    if (!deleted) return Err(new CommerceNotFoundError("Note not found."));
+    return Ok({ deleted: true });
+  }
+
+  /**
+   * One merged per-order activity view (issue #56): status history + operator
+   * notes + refund ledger events (both directions), newest first.
+   */
+  async timeline(
+    orderId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<Array<{
+    type: "status" | "note" | "refund";
+    at: Date;
+    actor: string;
+    summary: string;
+    data: Record<string, unknown>;
+  }>>> {
+    const order = await this.requireOrderAccess(orderId, actor, "orders:read", ctx);
+    if (!order.ok) return order;
+
+    const [history, notes, refunds] = await Promise.all([
+      this.repo.findStatusHistoryByOrderId(orderId, ctx),
+      this.repo.findNotesByOrderId(orderId, ctx),
+      this.repo.findRefundsByOrderId(orderId, ctx),
+    ]);
+
+    const events: Array<{
+      type: "status" | "note" | "refund";
+      at: Date;
+      actor: string;
+      summary: string;
+      data: Record<string, unknown>;
+    }> = [];
+
+    for (const entry of history) {
+      events.push({
+        type: "status",
+        at: entry.changedAt,
+        actor: entry.changedBy,
+        summary: `Status ${entry.fromStatus} → ${entry.toStatus}${entry.reason ? ` (${entry.reason})` : ""}`,
+        data: { fromStatus: entry.fromStatus, toStatus: entry.toStatus, reason: entry.reason },
+      });
+    }
+    for (const note of notes) {
+      events.push({
+        type: "note",
+        at: note.createdAt,
+        actor: note.author,
+        summary: note.body,
+        data: { noteId: note.id, pinned: note.pinned },
+      });
+    }
+    for (const refund of refunds) {
+      events.push({
+        type: "refund",
+        at: refund.createdAt,
+        actor: refund.performedBy,
+        summary: `Refund of ${refund.amount}${refund.reason ? ` (${refund.reason})` : ""}`,
+        data: { refundId: refund.id, amount: refund.amount, lines: refund.lines, status: refund.status },
+      });
+      if (refund.status === "undone" && refund.undoneAt) {
+        events.push({
+          type: "refund",
+          at: refund.undoneAt,
+          actor: refund.undoneBy ?? "system",
+          summary: `Refund of ${refund.amount} undone`,
+          data: { refundId: refund.id, amount: refund.amount, undone: true },
+        });
+      }
+    }
+
+    events.sort((a, b) => b.at.getTime() - a.at.getTime());
+    return Ok(events);
+  }
+
   /**
    * Capture an authorized payment for an order via the payment adapter and
    * record the captured amount. Does not transition order status — capture is a
@@ -784,6 +1522,244 @@ export class OrderService {
     return Ok(items);
   }
 
+  /** Line items may not be edited on terminal or fully-captured orders. */
+  private lineItemEditGuard(order: Order): CommerceValidationError | null {
+    if (this.machine.terminal.includes(order.status)) {
+      return new CommerceValidationError(
+        `Order in terminal status "${order.status}" cannot be edited.`,
+      );
+    }
+    if (
+      order.amountCaptured != null &&
+      order.amountCaptured >= order.grandTotal
+    ) {
+      return new CommerceValidationError(
+        "Order payment is fully captured; line items cannot be edited.",
+      );
+    }
+    // R-06: a checkout order carries a paymentIntentId. If amountCaptured is null
+    // (auth-only capture, or a mock adapter reporting 0), treat it as authorized —
+    // an order with a live payment must not have its lines silently edited/inflated.
+    if (order.paymentIntentId != null && order.amountCaptured == null) {
+      return new CommerceValidationError(
+        "Order has an authorized payment; line items cannot be edited.",
+      );
+    }
+    return null;
+  }
+
+  /**
+   * Recomputes subtotal/taxTotal/grandTotal from the order's line items
+   * (shippingTotal and order-level discountTotal are preserved), persists
+   * them, and records an audit entry in the status history.
+   */
+  private async recalcOrderTotals(
+    order: Order,
+    actor: Actor | null,
+    reason: string,
+    ctx?: TxContext,
+  ): Promise<HydratedOrder> {
+    const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
+    const subtotal = lineItems.reduce((sum, li) => sum + li.totalPrice, 0);
+    const taxTotal = lineItems.reduce((sum, li) => sum + li.taxAmount, 0);
+    const grandTotal =
+      subtotal + taxTotal + order.shippingTotal - order.discountTotal;
+    const updated = await this.repo.update(
+      order.id,
+      { subtotal, taxTotal, grandTotal },
+      ctx,
+    );
+    await this.repo.createStatusHistory(
+      {
+        orderId: order.id,
+        fromStatus: order.status,
+        toStatus: order.status,
+        reason,
+        changedBy: actor?.userId ?? "system",
+      },
+      ctx,
+    );
+    return { ...(updated ?? order), lineItems };
+  }
+
+  async addLineItem(
+    orderId: string,
+    input: {
+      entityId: string;
+      entityType: string;
+      variantId?: string | undefined;
+      sku?: string | undefined;
+      title: string;
+      quantity: number;
+      unitPrice: number;
+      totalPrice?: number | undefined;
+      taxAmount?: number | undefined;
+      discountAmount?: number | undefined;
+      metadata?: Record<string, unknown> | undefined;
+    },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    const guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    // Org-integrity + price provenance for the added line (same rules as create):
+    // the entity must belong to the order's org, and the price is server-derived
+    // unless the actor holds `orders:manage` (then honored + flagged isCustomPrice).
+    const resolvedResult = await this.resolveLines(
+      {
+        currency: order.currency,
+        subtotal: 0,
+        taxTotal: 0,
+        shippingTotal: 0,
+        grandTotal: 0,
+        lineItems: [
+          {
+            entityId: input.entityId,
+            entityType: input.entityType,
+            title: input.title,
+            quantity: input.quantity,
+            unitPrice: input.unitPrice,
+            totalPrice: input.totalPrice ?? input.unitPrice * input.quantity,
+            ...(input.variantId !== undefined ? { variantId: input.variantId } : {}),
+            ...(input.sku !== undefined ? { sku: input.sku } : {}),
+            ...(input.taxAmount !== undefined ? { taxAmount: input.taxAmount } : {}),
+            ...(input.discountAmount !== undefined
+              ? { discountAmount: input.discountAmount }
+              : {}),
+            ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+          },
+        ],
+        ...(order.customerId ? { customerId: order.customerId } : {}),
+      },
+      actor,
+      false,
+      ctx,
+    );
+    if (!resolvedResult.ok) return Err(resolvedResult.error);
+    const line = resolvedResult.value[0]!;
+
+    await this.repo.createLineItems(
+      [
+        {
+          orderId: order.id,
+          entityId: line.entityId,
+          entityType: line.entityType,
+          title: line.title,
+          quantity: line.quantity,
+          unitPrice: line.unitPrice,
+          totalPrice: line.totalPrice ?? line.unitPrice * line.quantity,
+          isCustomPrice: line.isCustomPrice,
+          taxAmount: line.taxAmount ?? 0,
+          discountAmount: line.discountAmount ?? 0,
+          fulfillmentStatus: "unfulfilled",
+          metadata: line.metadata ?? {},
+          ...(line.variantId !== undefined ? { variantId: line.variantId } : {}),
+          ...(line.sku !== undefined ? { sku: line.sku } : {}),
+        },
+      ],
+      ctx,
+    );
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_added", ctx));
+  }
+
+  async updateOrderLineItem(
+    orderId: string,
+    lineItemId: string,
+    patch: { quantity: number },
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    const guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    const line = await this.repo.findLineItemById(lineItemId, ctx);
+    if (!line || line.orderId !== order.id) {
+      return Err(new CommerceNotFoundError("Line item not found on this order."));
+    }
+    if (line.fulfillmentStatus !== "unfulfilled") {
+      return Err(
+        new CommerceValidationError(
+          "Line items with fulfillment progress cannot be adjusted.",
+        ),
+      );
+    }
+    if (patch.quantity < 1) {
+      return Err(new CommerceValidationError("Quantity must be at least 1."));
+    }
+
+    // Scale line totals with the quantity change (tax scales per-unit).
+    const perUnitTax = line.quantity > 0 ? line.taxAmount / line.quantity : 0;
+    await this.repo.updateLineItem(
+      lineItemId,
+      {
+        quantity: patch.quantity,
+        totalPrice: line.unitPrice * patch.quantity,
+        taxAmount: Math.round(perUnitTax * patch.quantity),
+      },
+      ctx,
+    );
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_updated", ctx));
+  }
+
+  async removeLineItem(
+    orderId: string,
+    lineItemId: string,
+    actor: Actor | null,
+    ctx?: TxContext,
+  ): Promise<Result<HydratedOrder>> {
+    try {
+      assertPermission(actor, "orders:update");
+    } catch (error) {
+      return Err(toCommerceError(error));
+    }
+    const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
+    const order = await this.repo.findById(orgId, orderId, ctx);
+    if (!order) return Err(new CommerceNotFoundError("Order not found."));
+    const guard = this.lineItemEditGuard(order);
+    if (guard) return Err(guard);
+
+    const line = await this.repo.findLineItemById(lineItemId, ctx);
+    if (!line || line.orderId !== order.id) {
+      return Err(new CommerceNotFoundError("Line item not found on this order."));
+    }
+    if (line.fulfillmentStatus !== "unfulfilled") {
+      return Err(
+        new CommerceValidationError(
+          "Line items with fulfillment progress cannot be removed.",
+        ),
+      );
+    }
+    const existing = await this.repo.findLineItemsByOrderId(order.id, ctx);
+    if (existing.length <= 1) {
+      return Err(
+        new CommerceValidationError("An order must keep at least one line item."),
+      );
+    }
+
+    await this.repo.deleteLineItem(lineItemId, ctx);
+
+    return Ok(await this.recalcOrderTotals(order, actor, "line_item_removed", ctx));
+  }
+
   async updateOrder(
     orderId: string,
     data: {