@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/commerce-return-order-summary-create/SKILL.md

@@ -0,0 +1,513 @@
+---
+name: commerce-return-order-summary-create
+description: "Use this skill when users want to use when a customer needs to return one or more items on an order that has already been fulfilled or delivered, via a preview-then-submit flow that submits only after explicit customer confirmation. Also use when a customer needs to return one or more items on an order that has already been fulfilled or delivered, via a preview-then-submit flow that submits only after explicit customer confirmation. Trigger when users mention return, order, summary."
+metadata:
+  version: "1.0"
+  accessCheck: "(OrderItemSummary.QuantityAvailableToReturn) || (OrderManagement.orgHasOrderManagementConnectAPIEnabled) || (UserPermissions.ORDER_ITEM_SUMMARY_RETURN_API_ACCESS)"
+---
+
+# Managing Return Order Summary
+
+## When to Use This Skill
+
+Use when a customer needs to return one or more items on an order that has already been fulfilled or delivered, via a preview-then-submit flow that submits only after explicit customer confirmation. Returns are always per-item — there is no full-order-return path (the core API exposes only preview-return / submit-return, not a *ReturnAll variant).
+
+## Workflow
+
+╔══════════════════════════════════════════════════════════════════════════╗
+║ HARD STOP between preview-return-items and submit-return-items.          ║
+║                                                                          ║
+║ The agent MUST NOT invoke submit-return-items without ALL of:            ║
+║   1. preview-return-items invoked in THIS conversation, success: true.   ║
+║   2. preview's changeBalances surfaced to the customer in plain language ║
+║      (lines, quantities, credit amount).                                 ║
+║   3. Customer's verbatim affirmative reply received in this conversation.║
+║   4. That verbatim reply passed into submit-return-items's required      ║
+║      `customer_confirmation` input (NOT a value the agent supplies).     ║
+║                                                                          ║
+║ A `success: true` from preview is NOT consent. Ambiguous customer        ║
+║ replies ("ok", "sure", "I think so", a question back) are NOT consent —  ║
+║ ask again plainly. Re-read submit-return-items's REFUSAL PROTOCOL        ║
+║ before calling it.                                                       ║
+╚══════════════════════════════════════════════════════════════════════════╝
+
+return-order-summary has a single linear execution path (preview → submit) —
+Return has NO full-order variant (only OrderSummaryPreviewReturnResource +
+OrderSummarySubmitReturnResource exist in core-264, no *ReturnAllResource).
+Per-step agent_guidance is authoritative for each step's contract; this is
+the orchestration map + entry decision tree + contract index.
+
+1. `reason` is REQUIRED on every changeItems[] entry, and its allowed values come from
+     the org-tenant's OrderItemSummaryChange.Reason picklist (the SAME picklist cancel uses
+     — the controller validates Return and Cancel reasons against one enum). Send a value
+     not in that picklist → 400 INVALID_API_INPUT "No matching reason found." Resolve the
+     live picklist via the resolve-return-reasons step before previewing; do NOT hard-code
+     the enum across orgs.
+
+2. The target line item must have `OrderItemSummary.QuantityAvailableToReturn > 0`. An
+     item that hasn't shipped yet (or has already been returned) returns 400
+     INVALID_API_INPUT before the financial preview runs. Run the verify-returnable-quantity
+     step (or an equivalent SOQL) before previewing so the agent fails fast with a clear
+     customer-facing message instead of cascading into a 400.
+
+3. `shippingReductionFlag` is REQUIRED on every changeItems[] entry. Wire-verified against
+     pbtest-ws on 2026-06-29: omitting the flag on preview-return returns HTTP 500 with
+     errorCode UNKNOWN_EXCEPTION (response envelope: enhancedErrorType=RecordError,
+     output.errors[0] carries the UNKNOWN_EXCEPTION + a "contact Salesforce Support" string
+     with an error ID). Sending the flag (true or false) is accepted and the request
+     progresses to business-rule validation. Always send the flag explicitly (false unless
+     the customer asks to also credit shipping). This parity-with-cancel finding holds for
+     return as well.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Org must have Order Management Connect API enabled (check: `Order Management API enabled`)
+- User must have access to Order Management Return features. Service-level access is gated by the ORDER_ITEM_SUMMARY_RETURN_API_ACCESS permission (verified in core-264 OrderSummaryPreviewReturnResource + OrderSummarySubmitReturnResource impl). Users without it get a 403 INSUFFICIENT_ACCESS on both preview and submit. (check: `UserPermissions.ORDER_ITEM_SUMMARY_RETURN_API_ACCESS`)
+- Each line item being returned must have OrderItemSummary.QuantityAvailableToReturn > 0.
+Items not yet shipped or already returned have QuantityAvailableToReturn == 0 and will
+fail preview with 400 INVALID_API_INPUT. Verify via SOQL before invoking preview-return-items. (check: `OrderItemSummary.QuantityAvailableToReturn`)
+- Each `reason` value sent in changeItems[] must match the org's
+OrderItemSummaryChange.Reason picklist (org-tenant-specific). The OAS
+types `reason` as a free-form string; the controller validates it as
+an enum. Resolve the picklist via resolve-return-reasons before previewing.
+Cancel and Return share this same picklist. (check: `OrderItemSummaryChange.Reason picklist`)
+- OrderSummary must be a MANAGED order (i.e. an order the OMS workflow can
+modify). The old flow stops UNMANAGED orders up-front with a friendly
+message; this SOR should do the same rather than let submit-return fail
+late with an opaque 400/500. TODO(W-23144076-followup): source the exact
+field name (candidates: `OrderSummary.IsManaged`, an OrderLifeCycleType
+check, or a service-level `OrderManagement.isManaged(orderSummary)` call)
+from the OMS legacy Aura flow that today gates the "Return Order" button.
+Cancel has the SAME gap — track under the same followup and land in both
+SORs together. No `check:` here until the real field name is sourced; the
+gate is prose-only for now (evaluated by the agent per step 0's
+ELIGIBILITY GATE), not machine-checkable.
+- OrderSummary must not be LOCKED by an in-progress cancellation. The old
+flow refuses to open the return workflow if a cancel is already running
+against the same OrderSummary — otherwise the two ChangeOrders race and
+the outcome is inconsistent. This SOR should surface the same friendly
+"there's an active cancellation on this order — please try again in a
+moment" message rather than let the API decide. TODO(W-23144076-followup):
+source the exact discriminator from the old flow (candidates: an
+OrderSummary status field, an OrderChangeLog / AsyncOperationLog probe on
+the parent, or a service-level lock check). Cancel has the SAME gap —
+track and land in both together. No `check:` here until the real
+discriminator is sourced; the gate is prose-only for now (evaluated by
+the agent per step 0's ELIGIBILITY GATE), not machine-checkable.
+
+**Operational rules:**
+
+- ENTRY DECISION TREE (drive the conversation in this order):
+  0. resolve-order-summary-by-number → OrderNumber → 1Os... Id. NOT unique;
+       disambiguate when totalSize > 1. Skip if the caller already has the Id.
+       AFTER confirming the specific order, run the ELIGIBILITY GATE from
+       step 0's agent_guidance:
+         - unmanaged order → friendly stop, END
+         - cancellation already in progress → friendly stop, END
+       (TODO: field names pending — see step 0's ELIGIBILITY GATE.)
+  1. resolve-return-reasons → fetch the org's Reason picklist (map the
+       customer's reason internally; never show raw tokens). Same picklist as cancel.
+  2. verify-returnable-quantity → read the returnable lines. If none are
+       returnable, short-circuit with the friendly already-returned / not-shipped
+       wording (do NOT proceed). Otherwise SHOW the customer the returnable
+       line items and let them pick which to return.
+  3. For EACH line the customer chose, collect two things before previewing:
+       a. QUANTITY — if that line's QuantityAvailableToReturn > 1, ASK how
+          many units (1..available, whole units). If == 1, use 1 without asking.
+       b. SHIPPING — ask whether to also credit that line's delivery/shipping
+          charge → shippingReductionFlag (false = keep, true = credit).
+       Build one changeItems[] entry per chosen line from these answers, then
+       go to preview-return-items → (confirm) → submit-return-items → verify.
+- CORE FLOW:
+  4. preview-return-items   → financial impact. HARD STOP for confirmation.
+  5. submit-return-items    → execute with the SAME payload. SYNC — returns
+                              changeOrderId in the response (no async polling).
+  6. fetch-change-order-record → internal verification of the ChangeOrder row.
+  7. verify-return-items    → two reads; don't trust OrderSummary.Status.
+- CUSTOMER-FACING WORDING (mandatory — this is a user-facing workflow):
+  - NO MONEY / CREDIT / REFUND MESSAGING. When a return submit completes,
+    confirm it in one short sentence and END (e.g. "Done — that return is
+    processed." / "Done — those returns are processed."). Do NOT tell the
+    customer about a credit, a change order, a refund, a billing follow-up,
+    an order total, or any dollar/amount figure — not even to say a refund
+    is "handled separately." The customer asked to return items; confirm
+    the return and stop. (Financial records like the ChangeOrder still
+    exist server-side and may be read for internal verification, but they
+    are NOT surfaced to the customer.) NOTE: actual refund issuance DOES run
+    inside this SOR — the refund-return-credit step delegates to
+    ensure-order-refund (credit memo + ensure-refunds-async) after submit.
+    That refund is SERVER-SIDE and SILENT: its existence does NOT license a
+    credit/refund sentence in the customer reply. The success wording above is
+    the complete customer response regardless of the refund delegation.
+  - CURRENCY: never hard-code a currency symbol (no "$"); amounts are in the
+    OrderSummary's own currency, which is NOT always USD. The OrderSummary
+    reads use SELECT FIELDS(STANDARD), so the currency is handled without a
+    hard-coded column or a per-org query variant:
+      • Multicurrency org: CurrencyIsoCode is a standard field, so it comes
+        back in the record (e.g. "USD", "EUR") — use it.
+      • Single-currency org: CurrencyIsoCode does not exist, so it simply
+        won't be in the record. Fall back to the org/user default currency
+        (Apex UserInfo.getDefaultCurrency(); the CurrencyType sObject does not
+        exist on single-currency orgs).
+    Present money as the amount followed by its ISO code (e.g. "129.00 USD",
+    "129.00 EUR") or the locale-formatted value — never assume dollars.
+    "zero" is currency-agnostic and fine for a fully-credited total.
+  - NO INTERNAL JARGON OR TELEMETRY. The friendly templates are the COMPLETE
+    customer response. Never surface step names, Connect API operation names,
+    field / response-shape names, sObject type names, raw 18-char Ids, or
+    the words "SOR"/"workflow". Do NOT append a verification recap / audit
+    trail after the success message — that belongs in logs.
+- CONTRACT INDEX (full detail in each step's agent_guidance):
+  - reason REQUIRED + enum-validated against OrderItemSummaryChange.Reason
+    (same picklist as cancel) → resolve-return-reasons
+  - shippingReductionFlag REQUIRED on every entry (wire-verified against
+    pbtest-ws: omit → 500 UNKNOWN_EXCEPTION) → preview-return-items
+  - QuantityAvailableToReturn > 0 precondition → verify-returnable-quantity
+  - HARD STOP between preview and submit (no auto-chain)
+  - submit reuses the exact preview payload → submit-return-items
+  - submit is SYNC — returns changeOrderId directly (no async polling,
+    unlike full-cancel) → submit-return-items
+  - ChangeOrder lives in the Order sObject (RelatedOrderType='ChangeOrder',
+    negative TotalAmount) → fetch-change-order-record
+  - OrderSummary.Status does not change on return (expected, mirrors cancel)
+    → verify-return-items
+  - Refund issuance (credit memo + ensure-refunds-async) IS reproduced here
+    by delegating to ensure-order-refund → refund-return-credit; it runs
+    server-side and is NOT surfaced to the customer
+  - SOQL INPUT SAFETY (consumer contract — no runtime gate). Steps
+    resolve-order-summary-by-number ({orderNumber}), verify-returnable-quantity
+    ({orderSummaryId}), resolve-bundle-structure ({orderSummaryId}),
+    fetch-change-order-on-timeout ({orderSummaryId} + {originalOrderId}),
+    and verify-return-items ({orderSummaryId} + the IN-list) each splice
+    an untrusted value into a SOQL WHERE clause. The per-input `pattern:`
+    / `validation:` fields are NOT enforced by any runtime in this repo:
+    MCP `dispatch` takes an already-rendered query string, and the
+    Salesforce REST `/query` endpoint has no bind-variable form (bind vars
+    exist only in Apex `Database.query`, not at REST). The caller building
+    the tool call is the only enforcement point. Validate every
+    interpolated value against its declared pattern before splicing and
+    reject on mismatch — do NOT escape-and-retry. The declared patterns
+    already exclude every SOQL metacharacter, so a matching value cannot
+    inject; the injection risk is entirely in skipping the check.
+- EMPIRICAL CONTRACTS (OAS-uncaptured; relocated from the discover-surfaced summary;
+inherited from the cancel-order-summary workflow's wire-validated findings against the
+shared ChangeInputRepresentation + OrderItemSummaryChange.Reason picklist):
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `submit-return-items`, `verify-returnable-quantity`: call `verify-return-items`
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `resolve-order-summary-by-number` | read | implemented | `querySoql` | — |
+| `resolve-return-reasons` | read | implemented | `describeOrderItemSummaryChange` | — |
+| `verify-returnable-quantity` | read | implemented | `querySoql` | — |
+| `resolve-bundle-structure` | read | implemented | `querySoql` | `verify-returnable-quantity` |
+| `ask-to-apply-fee` | read | implemented | `interactive_prompt` | `verify-returnable-quantity` |
+| `collect-per-item-return-fees` | read | implemented | `interactive_prompt` | `verify-returnable-quantity` |
+| `preview-return-items` | read | implemented | `postOrderSummaryPreviewReturn` | `resolve-return-reasons`, `verify-returnable-quantity`, `ask-to-apply-fee`, `collect-per-item-return-fees` |
+| `submit-return-items` | write | implemented | `postOrderSummarySubmitReturn` | `preview-return-items` |
+| `fetch-change-order-record` | read | implemented | `getOrder` | `submit-return-items` |
+| `fetch-change-order-on-timeout` | read | implemented | `querySoql` | `submit-return-items` |
+| `verify-return-items` | verify | implemented | `querySoql` | `submit-return-items`, `verify-returnable-quantity` |
+| `refund-return-credit` | write | — | → `cc-om-fast-and-furious/ensure-order-refund` | `submit-return-items` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  resolve_order_summary_by_number["resolve-order-summary-by-number (read)"]
+  resolve_return_reasons["resolve-return-reasons (read)"]
+  verify_returnable_quantity["verify-returnable-quantity (read)"]
+  resolve_bundle_structure["resolve-bundle-structure (read)"]
+  ask_to_apply_fee["ask-to-apply-fee (read)"]
+  collect_per_item_return_fees["collect-per-item-return-fees (read)"]
+  preview_return_items["preview-return-items (read)"]
+  submit_return_items["submit-return-items (write)"]
+  fetch_change_order_record["fetch-change-order-record (read)"]
+  fetch_change_order_on_timeout["fetch-change-order-on-timeout (read)"]
+  verify_return_items["verify-return-items (verify)"]
+  refund_return_credit["refund-return-credit (write)"]
+  verify_returnable_quantity --> resolve_bundle_structure
+  verify_returnable_quantity --> ask_to_apply_fee
+  verify_returnable_quantity --> collect_per_item_return_fees
+  resolve_return_reasons --> preview_return_items
+  verify_returnable_quantity --> preview_return_items
+  ask_to_apply_fee --> preview_return_items
+  collect_per_item_return_fees --> preview_return_items
+  preview_return_items --> submit_return_items
+  submit_return_items --> fetch_change_order_record
+  submit_return_items --> fetch_change_order_on_timeout
+  submit_return_items --> verify_return_items
+  verify_returnable_quantity --> verify_return_items
+  submit_return_items --> refund_return_credit
+```
+
+### Read operations
+
+#### `resolve-order-summary-by-number`
+
+Resolve a customer-provided OrderNumber to its OrderSummary Id.
+Customers and CSRs work with OrderNumber (the printed order number on
+receipts/email); the return APIs require the internal Id (1Os...).
+
+IMPORTANT: OrderNumber is NOT unique on this sObject — a single
+OrderNumber can resolve to multiple OrderSummaries (orgs reuse it across
+storefronts/locales). When this step returns more than one row, the agent
+MUST surface the candidates (date, total, line count) and ask the customer
+which one they meant before proceeding. Do NOT auto-pick by OrderedDate or
+any heuristic — the wrong order is the worst outcome in a return workflow.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderNumber` *(`String`)* — Customer-facing OrderNumber (the printed order number from the
+receipt/confirmation email). Skip this step entirely if the caller
+already has the OrderSummary Id (starts with '1Os') — pass that
+directly into downstream steps.
+
+#### `resolve-return-reasons`
+
+Resolve the org's allowed return reasons from the live
+OrderItemSummaryChange.Reason picklist. Required because the
+controller validates `reason` against this picklist on both preview
+and submit; sending an unrecognized value returns 400
+INVALID_API_INPUT "No matching reason found." Cancel and Return share
+the same Reason picklist (one enum on OrderItemSummaryChange).
+
+**Call:** `describeOrderItemSummaryChange`   — status: `implemented`
+
+#### `verify-returnable-quantity`
+
+Confirm each target OrderItemSummary has QuantityAvailableToReturn > 0
+before invoking preview-return. Items that haven't shipped (or have
+already been returned) will fail preview with 400 INVALID_API_INPUT.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — ID of the order summary (starts with 1Os)
+
+#### `resolve-bundle-structure`
+
+Fetch and present the bundle structure for an order that contains a bundle
+(detected in verify-returnable-quantity via a non-null MainOrderItemSummaryId
+on any line). Bundle structure lives in OrderItemSummaryRelationship, which
+links a MainOrderItemSummary (the bundle parent) to each
+AssociatedOrderItemSummary (a component / add-on), with roles and a
+ProductRelationshipType. Run this only when a bundle was detected; skip for
+orders with no bundle. Return uses the same OrderItemSummaryRelationship
+schema as cancel — bundle structure is a property of the order, not of the
+action being performed on it.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — OrderSummary Id (1Os...). Source: output of verify-returnable-quantity.
+
+**Depends on:** `verify-returnable-quantity`
+
+#### `ask-to-apply-fee`
+
+Ask whether the customer wants to add a return fee (restocking fee, processing fee, etc.).
+If they choose YES, delegate to fees-support to collect fee product, description, amount,
+and fee-input representation. If NO, proceed directly to preview-return-items with zero fees.
+
+**Call:** `interactive_prompt`   — status: `implemented`
+
+**Depends on:** `verify-returnable-quantity`
+
+#### `collect-per-item-return-fees`
+
+Collect separate fee for each returned item
+
+**Call:** `interactive_prompt`   — status: `implemented`
+
+**Depends on:** `verify-returnable-quantity`
+
+#### `preview-return-items`
+
+Preview the expected financial impact of returning specific order items
+
+**Call:** `postOrderSummaryPreviewReturn`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — ID of the order summary (1Os...).
+Source: `order_summary_id` output of resolve-order-summary-by-number
+(only valid when `match_count == 1`; on multi-match cases, source it
+from the customer's disambiguation reply per step 0's agent_guidance).
+A caller that already holds the 1Os Id can pass it in directly and skip
+step 0.
+- `changeItems` *(`Array`)* — List of order items to return with quantities. Each entry pairs an
+OrderItemSummary Id (from verify-returnable-quantity's returnable_items)
+with a customer-confirmed quantity, a resolved picklist reason (from
+resolve-return-reasons.allowed_reasons), and shippingReductionFlag.
+Source: verify-returnable-quantity (line Ids + QuantityAvailableToReturn)
++ resolve-return-reasons (allowed picklist values) + the customer's
+quantity / shipping-credit answers per the entry decision tree.
+  - schema: `{'items': {'type': 'object', 'required': ['orderItemSummaryId', 'quantity', 'reason', 'shippingReductionFlag'], 'properties': {'orderItemSummaryId': {'type': 'string', 'description': 'ID of the OrderItemSummary to return (must have QuantityAvailableToReturn > 0)'}, 'quantity': {'type': 'number', 'description': "Number of units to return for this line. Must be a whole number with 1 <= quantity <= OrderItemSummary.QuantityAvailableToReturn. When that line's QuantityAvailableToReturn > 1, this value MUST come from an explicit customer choice (see verify-returnable-quantity QUANTITY CONFIRMATION) — do not default to 1 or to all-available."}, 'reason': {'type': 'string', 'description': 'Return reason. REQUIRED. Must be a value from the org\'s\nOrderItemSummaryChange.Reason picklist (see resolve-return-reasons).\nSending a string that isn\'t in the picklist returns 400\nINVALID_API_INPUT "No matching reason found." Cancel and Return\nshare the same picklist.', 'x-codey-enum-source': 'OrderItemSummaryChange.Reason', 'x-codey-enum-resolver-step': 'resolve-return-reasons'}, 'reasonForChangeText': {'type': 'string', 'description': 'Free-form description of the reason for change'}, 'shippingReductionFlag': {'type': 'boolean', 'description': 'REQUIRED — wire-verified against pbtest-ws on 2026-06-29: omitting it returns HTTP 500 UNKNOWN_EXCEPTION on preview-return (parity with cancel via the same ChangeInputRepresentation). Always send it explicitly: false keeps the delivery/shipping charge, true also credits shipping (affects totalAdjustedDeliveryAmount). Send false unless the customer asks to also credit shipping.'}, 'changeItemFees': {'type': 'array', 'description': 'Optional fee adjustments accompanying the return'}}}}`
+  - **Source:** output of `verify-returnable-quantity`
+
+**Depends on:** `resolve-return-reasons`, `verify-returnable-quantity`, `ask-to-apply-fee`, `collect-per-item-return-fees`
+
+#### `fetch-change-order-record`
+
+Optional: read the ChangeOrder record produced by submit-return-items.
+ChangeOrders live in the standard `Order` sObject (NOT a separate
+`ChangeOrder` sObject — that does not exist). Discriminate via
+`RelatedOrderType = 'ChangeOrder'` and `RelatedOrderId` pointing at
+the parent Order. `TotalAmount` is NEGATIVE on returns (it represents
+the reduction). `IsReductionOrder` is unreliable (false on cancels —
+expected same on returns); the reduction signal is the
+`RelatedOrderType` + negative-amount combination, not that flag.
+
+**Call:** `getOrder`   — status: `implemented`
+
+**Inputs:**
+
+- `changeOrderId` *(`String`)* — changeOrderId returned by submit-return-items
+
+**Depends on:** `submit-return-items`
+
+#### `fetch-change-order-on-timeout`
+
+Optional recovery step. Run ONLY when submit-return-items returned an
+ambiguous failure (timeout / 5xx after sending) and the per-line
+QuantityReturned re-read was inconclusive. Locates a freshly-created
+ChangeOrder for this OrderSummary so the agent can distinguish "landed
+but response lost" from "never applied" before deciding to retry.
+Return's submit is SYNCHRONOUS — on the happy path submit's response
+already carries changeOrderId, so fetch-change-order-record (path lookup)
+is the normal read; this step exists only for the response-lost case.
+
+Two-step query mirroring cancel's async recovery: first fetch
+OriginalOrderId from OrderSummary; then query Order filtered by
+RelatedOrderId = OriginalOrderId AND RelatedOrderType='ChangeOrder',
+newest first. Do NOT rely on IsReductionOrder (stays false on returns).
+A no-match result means the return did NOT land — safe to retry.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — OrderSummary Id; used to look up OriginalOrderId.
+Source: input of submit-return-items.
+
+**Depends on:** `submit-return-items`
+
+### Write operations
+
+#### `submit-return-items`
+
+Irreversibly process the customer's return on the order. Must run AFTER preview-return-items
+AND after the customer has been shown the preview's changeBalances output AND has explicitly
+confirmed (a verbatim yes-equivalent reply). The agent MUST NOT call this step from its own
+inference of consent — if no preview output has been surfaced to the customer in this
+conversation, or if no explicit affirmative reply has been received in response, REFUSE this
+call and route back to preview-return-items instead. A `success: true` from preview is NOT
+consent.
+
+**Call:** `postOrderSummarySubmitReturn`   — status: `implemented`
+
+**Inputs:**
+
+- `customer_confirmation` *(`String`)* — The customer's VERBATIM affirmative reply, captured AFTER preview-return-items has been
+invoked AND its changeBalances output has been read back to the customer in plain language
+(line names, quantities, credit amount). Must be the unmodified customer-typed/spoken
+response (e.g. "yes", "yes please go ahead", "confirm", "do it"). The agent MUST NOT
+synthesize, paraphrase, or supply this value from its own reasoning; that is the bug class
+this field exists to block. If you (the agent) do not have such a reply in the conversation
+transcript, STOP — route back to preview-return-items, surface the preview to the customer,
+and ask. A `success: true` from preview is NOT a substitute for the customer's reply. An
+agent-supplied value here is a guardrail violation reportable as W-23144076 followup.
+- `orderSummaryId` *(`String`)* — Same order summary ID from preview step
+- `changeItems` *(`Array`)* — Same changeItems array used in preview (MUST match exactly,
+including BOTH the resolved reason values AND shippingReductionFlag
+(true|false) on every entry). Submit shares cancel's contract: HTTP
+500 UNKNOWN_EXCEPTION if shippingReductionFlag is omitted (verified
+against pbtest-ws 2026-06-29) — do NOT strip it when reusing the
+preview payload.
+Source: output of preview-return-items.
+
+**Depends on:** `preview-return-items`
+
+#### `refund-return-credit`
+
+Move money back to the customer after the return's ChangeOrder is created.
+submit-return-items only records the financial reduction (the ChangeOrder);
+it does NOT itself return any money. This step delegates to the
+ensure-order-refund SOR for the credit-memo + refund money movement.
+
+It mirrors the shipped Core OMS Return flow — Return_Item-1.flow (in
+core/ui-commerce-ordermanagement-components/flows/runtime_commerce_oms/) — which
+runs ONE refund pipeline after Return_Order_Item_Summaries_Submit: the
+CREDIT-MEMO path (return has no excess-funds branch like cancel/adjust have),
+in this exact element order:
+  • Fee_Change_Order_Id_Exists — [if submitReturnOutput.feeChangeOrderId not null]
+    Create_An_Invoice → createInvoiceFromChangeOrders(feeChangeOrderId) → invoicesToPay
+  • createCreditMemoId → createCreditMemoOrderSummary(changeOrderIds = [return
+    changeOrderId])   [UNCONDITIONAL — runs on every return]
+  • Is_Refund_Needed — submitReturnOutput.changeBalances.totalRefundableAmount > 0
+  • Ensure_Payment_Credit_Required — [if paymentCredit.amount > 0 AND
+    paymentCreditSequence non-empty] Ensure_Payment_Credit → ensurePaymentCredit
+  • Credit_Memo_Balance — Credit_Memo.Balance == 0 → done (nothing to refund);
+    else → ensureRefund
+  • ensureRefund → ensureRefundsOrderSummaryAsync(creditMemoId, invoicesToPay, sequences)
+ensure-order-refund performs every one of these; return-order-summary only
+produces the ChangeOrder — the identical division of labor as
+cancel-order-summary / adjust-order-summary → ensure-order-refund.
+
+**Delegates to:** `cc-om-fast-and-furious/ensure-order-refund`
+
+**Depends on:** `submit-return-items`
+
+### Verify operations
+
+#### `verify-return-items`
+
+Verify the return landed by reading back BOTH the OrderSummary
+(for the GrandTotalAmount delta) and each returned OrderItemSummary
+(for QuantityReturned and QuantityAvailableToReturn transitions).
+One read is not enough — see assertions and agent_guidance below.
+
+**Call:** `querySoql`   — status: `implemented`
+
+**Inputs:**
+
+- `orderSummaryId` *(`String`)* — Source: output of submit-return-items.
+- `orderItemSummaryIds` *(`Array`)* — IDs of the returned lines, sourced from submit-return-items.output
+.order_item_summary_ids (which projects $.changeItems[*]
+.orderItemSummaryId). Used to scope the line-item read-back so the
+assertion checks the exact set the agent returned. The follow_up_query
+references these via the {orderItemSummaryIdsInClause} placeholder —
+see agent_guidance for the rendering rule. Every element MUST match
+the per-item pattern below before it's rendered into the IN-list; the
+IN-list join is a raw string splice into SOQL.
+  - schema: `{'minItems': 1, 'items': {'type': 'string', 'pattern': '^10u[a-zA-Z0-9]{12,15}$'}}`
+  - **Source:** output of `submit-return-items`
+- `preReturnSnapshot` *(`Array`)* — Per-line pre-submit snapshot captured from verify-returnable-quantity's
+`pre_return_snapshot` output, filtered to just the lines being returned
+AND paired with the returned quantity for each. Each entry is an object:
+  {orderItemSummaryId, quantityReturnedBefore, quantityAvailableToReturnBefore, returnedQty}
+The assertion uses these pre-values to compute the exact delta — without
+them the verify cannot distinguish "return landed" from "no-op". Build
+this by joining verify-returnable-quantity's records to the changeItems[]
+the agent sent to submit-return-items (matching on Id, quantity → returnedQty).
+  - schema: `{'minItems': 1, 'items': {'type': 'object', 'required': ['orderItemSummaryId', 'quantityReturnedBefore', 'quantityAvailableToReturnBefore', 'returnedQty'], 'properties': {'orderItemSummaryId': {'type': 'string', 'pattern': '^10u[a-zA-Z0-9]{12,15}$'}, 'quantityReturnedBefore': {'type': 'number'}, 'quantityAvailableToReturnBefore': {'type': 'number'}, 'returnedQty': {'type': 'number'}}}}`
+  - **Source:** output of `verify-returnable-quantity`
+
+**Depends on:** `submit-return-items`, `verify-returnable-quantity`