@porulle/core 0.7.0 → 0.9.0

package/dist/modules/orders/service.js

@@ -1,12 +1,13 @@
 import { resolveOrgId } from "../../auth/org.js";
 import { assertOwnership, assertPermission } from "../../auth/permissions.js";
-import { CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
+import { CommerceForbiddenError, CommerceInvalidTransitionError, CommerceNotFoundError, CommerceValidationError, toCommerceError, } from "../../kernel/errors.js";
 import { runAfterHooks, runBeforeHooks } from "../../kernel/hooks/executor.js";
 import { createHookContext } from "../../kernel/hooks/create-context.js";
 import { canTransition, orderStateMachine, } from "../../kernel/state-machine/machine.js";
 import { Err, Ok } from "../../kernel/result.js";
 import { createLogger } from "../../utils/logger.js";
 import { paginate } from "../../utils/pagination.js";
+import { withTransaction, } from "../../kernel/database/tx-context.js";
 function context(actor, services, database, tx = null) {
     return createHookContext({
         actor,
@@ -30,7 +31,70 @@ export class OrderService {
         const lineItems = await this.repo.findLineItemsByOrderId(order.id, ctx);
         return { ...order, lineItems };
     }
-    async create(input, actor, ctx) {
+    /**
+     * 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.
+     */
+    async resolveLines(input, actor, trusted, ctx) {
+        let canOverride = trusted;
+        if (!canOverride) {
+            try {
+                assertPermission(actor, "orders:manage");
+                canOverride = true;
+            }
+            catch {
+                canOverride = false;
+            }
+        }
+        const catalog = this.deps.services.catalog;
+        const pricing = this.deps.services.pricing;
+        const resolved = [];
+        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, actor, ctx, opts) {
+        if (opts?.stockPolicy === "reserve" && !ctx) {
+            return withTransaction(this.deps.database, { actor }, (txCtx) => this.create(input, actor, txCtx, opts));
+        }
         try {
             assertPermission(actor, "orders:create");
         }
@@ -44,34 +108,88 @@ export class OrderService {
         const afterHooks = this.deps.hooks.resolve("orders.afterCreate");
         const hookCtx = context(actor, this.deps.services, this.deps.database, ctx?.tx);
         const processed = await runBeforeHooks(beforeHooks, input, "create", 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);
-        const lineItemsData = processed.lineItems.map((item) => ({
+        // 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;
+            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;
+        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 = 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",
@@ -80,6 +198,23 @@ export class OrderService {
             ...(item.sku !== undefined ? { sku: item.sku } : {}),
         }));
         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;
+            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,
             fromStatus: "pending",
@@ -127,6 +262,14 @@ export class OrderService {
             return Err(new CommerceNotFoundError("Order not found."));
         return this.getById(order.id, actor, ctx);
     }
+    /** Returns the order previously created with this idempotency key, or null. */
+    async getByIdempotencyKey(idempotencyKey, actor, ctx) {
+        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, actor, ctx) {
         try {
             assertPermission(actor, "orders:read");
@@ -241,6 +384,12 @@ export class OrderService {
         await runBeforeHooks(beforeHooks, statusHookInput, "statusChange", hookCtx);
         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
@@ -265,7 +414,7 @@ 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({
+                        const releaseResult = await inventory.release({
                             entityId: lineItem.entityId,
                             quantity: lineItem.quantity,
                             orderId: order.id,
@@ -273,7 +422,14 @@ export class OrderService {
                             ...(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);
+                            }
+                        }
                     }
                 }
             }
@@ -283,11 +439,19 @@ export class OrderService {
             if (paymentIntentId) {
                 const payments = this.deps.services.payments;
                 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}`);
+                    }
                 }
             }
             // 3. Void tax transaction
@@ -320,7 +484,7 @@ export class OrderService {
                                 : {}),
                         });
                         // Release reservation (no longer needed)
-                        await inventory.release({
+                        const releaseResult = await inventory.release({
                             entityId: lineItem.entityId,
                             quantity: lineItem.quantity,
                             orderId: order.id,
@@ -328,7 +492,14 @@ export class OrderService {
                             ...(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(lineItem.id, { fulfillmentStatus: "fulfilled" }, ctx);
                     }
@@ -360,6 +531,296 @@ export class OrderService {
             ...(opts?.amount != null ? { refundAmount: opts.amount } : {}),
         }, actor, ctx);
     }
+    // ── Line-level refund policy primitives (issue #52) ─────────────────────
+    async refundPolicies(orgId, ctx) {
+        const settings = this.deps.services.settings;
+        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, input, actor, ctx) {
+        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 = [];
+        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;
+            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, refundId, actor, ctx) {
+        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, actor, ctx) {
+        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, ctx) {
+        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) ─────────────────────────
+    async requireOrderAccess(orderId, actor, perm, ctx) {
+        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, input, actor, ctx) {
+        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, actor, ctx) {
+        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, noteId, actor, ctx) {
+        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, actor, ctx) {
+        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 = [];
+        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
@@ -407,6 +868,169 @@ export class OrderService {
         items.sort((a, b) => a.changedAt.getTime() - b.changedAt.getTime());
         return Ok(items);
     }
+    /** Line items may not be edited on terminal or fully-captured orders. */
+    lineItemEditGuard(order) {
+        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.
+     */
+    async recalcOrderTotals(order, actor, reason, ctx) {
+        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, input, actor, ctx) {
+        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, lineItemId, patch, actor, ctx) {
+        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, lineItemId, actor, ctx) {
+        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, data, actor, ctx) {
         const orgId = resolveOrgId(actor ?? ctx?.actor ?? null);
         const order = await this.repo.findById(orgId, orderId, ctx);