@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order-refund.json

@@ -1,164 +0,0 @@
-{
-  "schemaVersion": 1,
-  "domain": "ecom",
-  "entity": "order-refund",
-  "displayName": "eCommerce Order Refund",
-  "capability": "commerce.order-refunds",
-  "target": {
-    "classification": "native-plus-cms",
-    "nativeEntity": "eCommerce Order Refund",
-    "verifiedFqdn": null,
-    "idPolicy": "server-assigned",
-    "crosswalkRequired": true
-  },
-  "dependsOn": [
-    "ecom/order",
-    "ecom/order-payment"
-  ],
-  "sourceAliases": [
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "order_refund",
-      "routes": [
-        "/wc/v3/orders/{id}/refunds"
-      ],
-      "confidence": "high"
-    },
-    {
-      "sourceSystem": "wix",
-      "sourceEntity": "ecomOrderRefund",
-      "routes": [
-        "eCommerce Orders API"
-      ],
-      "confidence": "medium"
-    }
-  ],
-  "preferredWrite": {
-    "surface": "eCom Order Transactions + Order Billing",
-    "endpoint": "POST /ecom/v1/payments/orders/{orderId}/add-payment then POST /ecom/v1/order-billing/refund-payments",
-    "writerId": "ensureOrderPaymentAndRefund",
-    "verification": "verified-live",
-    "importSafe": true,
-    "bulk": false
-  },
-  "fallbacks": [
-    {
-      "classification": "cms",
-      "when": "Use for refund history when the order writer cannot preserve refund details."
-    }
-  ],
-  "reliability": {
-    "status": "reliable",
-    "flags": []
-  },
-  "pitfalls": [
-    {
-      "code": "refund-schema-unverified",
-      "severity": "warning",
-      "summary": "Verify whether the selected order write shape preserves refund amounts, reasons, dates, and line references."
-    },
-    {
-      "code": "import-payload-refund-unproven",
-      "severity": "info",
-      "summary": "The Import Order payload has no import-safe refund representation. Refunds use separate eCom Order Transactions and Order Billing APIs, documented below. This pitfall records that the negative finding applies only to the Import Order payload, not to refund migration overall."
-    },
-    {
-      "code": "createorder-was-the-wrong-tool-not-a-dead-end",
-      "severity": "info",
-      "summary": "The prior assumption was that the only refund write path ran through live-commerce `createOrder` (importSafe:false — real inventory/email side effects, correctly rejected as unsafe for historical data). VERIFIED live 2026-08-12: this was solving the wrong endpoint, not a genuine dead end. The eCom domain models payments/refunds as pure record-keeping, separate from the checkout flow: 'Add Payments' and 'Refund Payments' (with `externalRefund: true`) both explicitly do NOT move real money or call a payment provider — see dev.wix.com's own notes on each ('This does NOT perform the actual charging' / 'Marks the payment as refunded without calling the provider's API'). Always check for a domain-specific record-keeping endpoint before accepting a live-commerce writer's importSafe:false as final."
-    },
-    {
-      "code": "import-order-creates-no-payment-record",
-      "severity": "warning",
-      "summary": "Verified live: an order created via Import Order reads back `GET /ecom/v1/payments/orders/{id}` with `payments: []` -- Import Order creates no payment transaction, so Refund Payments has nothing to reference (`paymentId` is required) without first calling Add Payments. `ensureOrderPaymentAndRefund` does not invent that payment. It never adds one sized to the order total with `offlinePayment: true, status: APPROVED`, because that would assert an approved offline payment dated migration day for an order that may never have been paid. It takes a MAPPED payment that has passed the existence gate (a positive amount AND a source paid date), reconciles it against the order's existing payments by identity, and creates one only when no matching record exists. A qualified refund whose order evidences no payment is reported as `refund-without-payment` rather than given a fabricated counterpart."
-    },
-    {
-      "code": "external-refund-is-the-load-bearing-field",
-      "severity": "blocker",
-      "summary": "`paymentRefunds[].externalRefund` defaults to `false` (automatic refund — calls the payment provider's API for real). For historical/imported data this MUST be `true`, or the call attempts a genuine provider-side refund against a payment that provider never processed. VERIFIED IN CODE 2026-09-02: `wix-writers.js::buildRefundOrderPaymentRequest()` hardcodes it as a literal — not a parameter, not a defaulted option — and this is now locked by `tests/target-wix/refund-external-only-contract-test.js`, which fails on the parameter form, on the `externalRefund = true` default form (a form that would pass every behavioral test whose callers pass nothing), and on the introduction of any second refund endpoint. Keep it a literal. Do not add an override, however well-intentioned the caller."
-    },
-    {
-      "code": "refund-existence-must-be-corroborated",
-      "severity": "blocker",
-      "summary": "NEVER infer that a refund exists from a payment-gateway meta field whose semantics have not been verified against that gateway's own documentation -- gateway field names lie. VERIFIED LIVE on a production store using a card gateway: the field `payplus_refunded` reads as \"amount refunded\" and actually means \"amount still available to refund\" -- its value equals the FULL ORDER TOTAL on essentially every order carrying it, while the store has no WooCommerce refund objects and no orders in `refunded` status. A mapper trusting the name would mark essentially that gateway's whole revenue as refunded. Its sibling `payplus_status` is a constant `approved` and so discriminates nothing. THE RULE (corrected 2026-09-03): a canonical WooCommerce refund entity with a stable source id and a parseable positive amount IS the refund record and is sufficient to import on its own -- it needs no second witness. Corroboration is required only where existence is INFERRED: an order-level `refunded` status can corroborate an entity but cannot supply a missing amount, and gateway flags, statuses, responses and refundable-balance fields never create a refund however many of them agree, because fields written by one gateway callback are one signal. An earlier version of this rule demanded two independently produced signals even for real entities; since both core signals share a producer, that would have refused every canonical refund entity. Where signals disagree, REFUSE and report; never pick the signal that produces data. The registry is rp-source-wordpress/lib/refund-corroboration.json and the qualifier is its sibling .js. Full evidence recorded internally, not part of this public bundle."
-    },
-    {
-      "code": "refund-date-is-read-only-and-immutable",
-      "severity": "warning",
-      "summary": "SCHEMA-CONFIRMED 2026-09-03 by re-checking the live Refund Payments schema: the refund's `createdDate` is BOTH read-only and immutable, and defaults to the current time. So an imported refund cannot carry its original date, while a PAYMENT's `createdDate` is settable. Refunds still import where qualified -- omitting them leaves a refunded order reading as fully paid, which overstates revenue and is the worse error -- but every written refund is counted in `refund-date-not-preserved` and disclosed. The true date must NOT be smuggled into a customer-visible field. A settable refund date needs a Wix-side change."
-    },
-    {
-      "code": "customer-reason-is-a-top-level-request-field",
-      "severity": "info",
-      "summary": "NAMING DRIFT, recorded 2026-09-03. The request field is top-level `customerReason` (maxLength 200); `details.reason` is where it comes back in the RESPONSE. Writing `details.reason` means this field. `buildRefundOrderPaymentRequest` already sends `customerReason` correctly. It is customer-visible, so it carries no date and no source identifier."
-    },
-    {
-      "code": "side-effects-omitted-means-no-restock-no-email",
-      "severity": "warning",
-      "summary": "SCHEMA-CONFIRMED: `sideEffects` is optional and `sideEffects.notifications.sendCustomerEmail` defaults to false, so OMITTING the whole `sideEffects` object is what keeps a historical refund from restocking inventory and emailing the customer. Never populate it for imported data. Pinned by tests/target-wix/refund-corroboration-test.js."
-    },
-    {
-      "code": "refund-disabled-probably-blocks-our-own-refund",
-      "severity": "warning",
-      "summary": "OPEN QUESTION, now better informed. Setting `refundDisabled: true` on imported payments was proposed as a second guard against a merchant issuing a provider-side refund against a migrated payment. The re-checked Refund Payments schema documents a `428 PAYMENT_NOT_REFUNDABLE` error and defines `refundDisabled: true` as \"this payment is not refundable\", which strongly suggests it would also block our own `externalRefund: true` write -- and `refundDisabled` is only settable when the payment is created, so it cannot be applied after refunds are written. It therefore stays UNSET in phase 1. Adopting it needs a live test proving an external refund still succeeds."
-    },
-    {
-      "code": "external-refund-expected-is-a-real-error-code",
-      "severity": "info",
-      "summary": "SCHEMA-CONFIRMED: the API defines `428 EXTERNAL_REFUND_EXPECTED` -- \"Payment requires an external refund. Set externalRefund to true\". Some payments accept nothing else, which independently confirms that `externalRefund: true` is the correct and expected mode for historical records rather than a workaround."
-    },
-    {
-      "code": "a-refund-does-not-settle-instantly",
-      "severity": "blocker",
-      "summary": "LIVE-VERIFIED 2026-09-05 on a disposable site: writing a second refund against the same payment while the first is still processing is refused with `428 PAYMENT_NOT_REFUNDABLE` and `nonRefundableReason: PENDING_REFUND`. It is intermittent -- sometimes the first settles fast enough that the second succeeds -- which makes it worse, not better, because a run can pass in testing and drop refunds in production. This is exactly the shape occurrence-aware identity exists for (two equal refunds on one payment), so treating the refusal as a failure would lose the second refund of every such pair. Wait and retry: PENDING_REFUND is a wait, distinct from every other non-refundable reason, which are genuine refusals. If it never settles the order is reported as `refund-still-settling` rather than written or dropped."
-    }
-  ],
-  "mappingGuidance": [
-    "Qualify the refund before mapping it: a canonical WooCommerce refund entity with a stable id and a positive amount is sufficient on its own; nothing weaker creates a refund. Use rp-source-wordpress/lib/refund-corroboration.js.",
-    "Map refunds with their parent order (via the order crosswalk) and preserve source refund IDs.",
-    "Resolve the target payment by identity, never by position. `ensureOrderPaymentAndRefund` reads the order's payments first and matches by provider transaction reference, else by an exact fingerprint of the payment facts; more than one match is ambiguous and prohibits writing.",
-    "A source with multiple refunds per order needs the writer to select or split across payments rather than assuming one. Phase 1 imports an authoritative total at order level and reports `refund-line-detail-not-preserved`; it invents no line ids.",
-    "`sideEffects` (inventory restock, customer notification email) is intentionally omitted for historical data -- set only if a specific migration explicitly wants either effect.",
-    "Refund COUNT is a first-class number to report at the approval gate, not an implementation detail: \"0 refunds\" is reviewable at a glance and an implausible count is the cheapest place to catch a mis-mapped source field. A store with weak gateway signals and no entities must report \"0 refunds found; N orders carry an uncorroborated gateway refund field\" rather than reporting nothing.",
-    "Do not read refund amounts from gateway-specific order meta (`payplus_*`, `_stripe_*`, and equivalents) unless that specific key's meaning is confirmed in the gateway's own docs AND it has a stable id and amount -- see the `refund-existence-must-be-corroborated` pitfall."
-  ],
-  "setupRequirements": [],
-  "evidence": [
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-object",
-      "note": "object page (docs-survey sweep 2026-08-11)"
-    },
-    {
-      "type": "live-run",
-      "path": "anonymized-live-verification",
-      "note": "Verified live: action=skip, no import-safe writer found on the Import Order payload — accurate for that payload; see the separate Order Transactions/Order Billing path found the same day"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-billing/refund-payments"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-transactions/add-payments"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-transactions/list-transactions-for-single-order"
-    },
-    {
-      "type": "live-verification",
-      "path": "anonymized-live-verification"
-    },
-    {
-      "type": "live-run",
-      "path": "anonymized-live-verification",
-      "note": "Live survey of a production WooCommerce store on a card gateway: `payplus_refunded` equalled the order total on essentially every order carrying it, with no Woo refund objects and no refunded orders. Source of the refund-existence-must-be-corroborated pitfall."
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/order-billing/refund-payments",
-      "note": "Full method schema re-checked 2026-09-03. Established: refund createdDate is read-only AND immutable; externalRefund is immutable once written; customerReason is a top-level request field capped at 200; paymentRefunds accepts 1-50 entries and paymentId is required; sideEffects is optional with sendCustomerEmail defaulting to false; the API defines 428 EXTERNAL_REFUND_EXPECTED and 428 PAYMENT_NOT_REFUNDABLE."
-    }
-  ]
-}

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order.json

@@ -1,462 +0,0 @@
-{
-  "schemaVersion": 1,
-  "domain": "ecom",
-  "entity": "order",
-  "displayName": "eCommerce Order",
-  "capability": "commerce.orders",
-  "target": {
-    "classification": "native-plus-cms",
-    "nativeEntity": "eCommerce Order",
-    "verifiedFqdn": null,
-    "idPolicy": "server-assigned",
-    "crosswalkRequired": true
-  },
-  "dependsOn": [
-    "crm/contact",
-    "stores/product",
-    "gift-cards/gift-card-product",
-    "stores/coupon",
-    "gift-cards/gift-card",
-    "tax/tax-group",
-    "ecom/shipping-option",
-    "ecom/delivery-profile"
-  ],
-  "blockedSourceDependencies": [
-    {
-      "sourceEntityRef": "plugin.woo-checkout-field-editor-pro.checkout-field-definition",
-      "degradedField": "extendedFields",
-      "pitfallCode": "checkout-custom-field-values-need-definitions",
-      "degradation": "deferred"
-    }
-  ],
-  "sourceAliases": [
-    {
-      "sourceSystem": "woocommerce",
-      "sourceEntity": "order",
-      "routes": [
-        "/wc/v3/orders"
-      ],
-      "confidence": "high"
-    },
-    {
-      "sourceSystem": "wix",
-      "sourceEntity": "ecomOrder",
-      "routes": [
-        "eCommerce Orders API"
-      ],
-      "confidence": "high"
-    }
-  ],
-  "preferredWrite": {
-    "surface": "eCom Orders",
-    "endpoint": "POST /ecom/v1/orders/import",
-    "writerId": "importOrder",
-    "verification": "verified-live",
-    "importSafe": true,
-    "bulk": false,
-    "releaseStatus": "beta",
-    "decision": "Import Order is the dedicated migration path: settable purchasedDate/number (createdDate is NOT settable -- see pitfalls), values stored as-is, no side effects (no buyer notifications, no inventory adjustment, no contact/invoice/receipt/subscription creation; only the OrderImported event fires). Beta, single-order only (no bulk endpoint), no SHOPIFY/WOOCOMMERCE channel enums (use OTHER_PLATFORM), analytics inclusion not suppressible. Rollback via Bulk Delete Imported Orders (VERIFIED LIVE 2026-09-05: async jobId, orders gone within seconds, a deleted id can be re-imported). Caller-supplied `id` VERIFIED LIVE 2026-09-05 (disposable site): a never-seen GUID is ACCEPTED and kept, so the order write can be made idempotent by deriving the id from the source -- `lib/order-history.js` does this; a re-send with an existing id fully REPLACES the body (omitted fields are cleared, createdDate kept, updatedDate moves, the number can change) while attached payments and extendedFields SURVIVE; a non-GUID id is a 400. See the silent-replace pitfall."
-  },
-  "alternateWrites": [
-    {
-      "surface": "eCom Orders",
-      "endpoint": "POST /ecom/v1/orders",
-      "writerId": "createOrder",
-      "verification": "unverified",
-      "importSafe": false,
-      "bulk": false,
-      "when": "Live-commerce order creation only \u2014 NEVER for historical import: decrements inventory, sends buyer confirmation email, auto-creates a contact."
-    }
-  ],
-  "extendedFields": {
-    "schemaKind": "data-extension-schema",
-    "definitionSurface": "Data Extension Schema API",
-    "definitionOperation": "Create/Update Data Extension Schema (FQDN wix.ecom.*.order)",
-    "valuePath": "extendedFields.namespaces._user_fields",
-    "namespaceForCreatedFields": "_user_fields",
-    "dataExtensionSchemaBacked": true,
-    "keyConvention": "wpCheckout_<metaKey> for values sourced from a checkout-field-editor-style plugin \u2014 avoids collision with merchant-created or other-plugin _user_fields entries.",
-    "fieldTypeMapping": [
-      {
-        "csvType": "text",
-        "fieldType": "string",
-        "notes": "maxLength 255 default"
-      },
-      {
-        "csvType": "textarea",
-        "fieldType": "string",
-        "notes": "maxLength 2000 default"
-      },
-      {
-        "csvType": "select",
-        "fieldType": "string",
-        "notes": "options documented in description, not enforced \u2014 DES has no enum"
-      },
-      {
-        "csvType": "radio",
-        "fieldType": "string",
-        "notes": "same as select"
-      },
-      {
-        "csvType": "multiselect",
-        "fieldType": "array",
-        "notes": "items: string"
-      },
-      {
-        "csvType": "checkbox",
-        "fieldType": "boolean",
-        "notes": "single yes/no field"
-      },
-      {
-        "csvType": "date",
-        "fieldType": "string",
-        "notes": "format: date"
-      }
-    ],
-    "docs": [
-      "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/import-order",
-      "https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction"
-    ],
-    "fqdn": "wix.ecom.*.order",
-    "supportsFiltering": false,
-    "nestedSubrecordExtendedFields": "unknown \u2014 which order subrecords expose nested extendedFields is open and out of scope; never provision nested fields",
-    "liveVerification": "Schema create/update/re-read and value writes verified live 2026-09-04 (string fields only)."
-  },
-  "safeModeContactFields": [
-    {
-      "kind": "email",
-      "targetPath": "billingInfo.email",
-      "source": "target-schema",
-      "notes": "Historical order billing email on the order object; codegen must resolve request wrappers."
-    },
-    {
-      "kind": "phone",
-      "targetPath": "billingInfo.phone",
-      "source": "target-schema",
-      "notes": "Historical order billing phone on the order object; codegen must resolve request wrappers."
-    },
-    {
-      "kind": "email",
-      "targetPath": "shippingInfo.email",
-      "source": "target-schema",
-      "notes": "Historical order shipping email on the order object when present."
-    },
-    {
-      "kind": "phone",
-      "targetPath": "shippingInfo.phone",
-      "source": "target-schema",
-      "notes": "Historical order shipping phone on the order object when present."
-    },
-    {
-      "kind": "email",
-      "targetPath": "buyerInfo.email",
-      "source": "target-schema",
-      "notes": "Historical order buyer email on the order object when present."
-    },
-    {
-      "kind": "phone",
-      "targetPath": "buyerInfo.phone",
-      "source": "target-schema",
-      "notes": "Historical order buyer phone on the order object when present."
-    }
-  ],
-  "fallbacks": [
-    {
-      "classification": "cms",
-      "when": "Use for separate audit/history records or unsupported nested source details."
-    }
-  ],
-  "reliability": {
-    "status": "partially-reliable",
-    "flags": []
-  },
-  "pitfalls": [
-    {
-      "code": "create-order-not-import-safe",
-      "severity": "blocker",
-      "summary": "Never route historical orders through createOrder \u2014 it decrements inventory, emails the buyer, and auto-creates contacts; importOrder is the only import-safe writer."
-    },
-    {
-      "code": "order-number-must-be-numeric",
-      "severity": "blocker",
-      "summary": "VERIFIED LIVE 2026-08-16: `order.number` must be a numeric string. A non-numeric value (e.g. the 'WT-1042' shape produced by WooCommerce sequential-order-number plugins) fails the entire Import Order call with a bare 400 {\"message\":\"Not a numeric value\"} carrying no field path \u2014 the error does not say which field, so it reads as a malformed payload. Strip prefixes to the numeric core and ledger the original as a fidelity note; do not pass the source order number through unvalidated."
-    },
-    {
-      "code": "merchant-note-author-is-token-holder",
-      "severity": "warning",
-      "summary": "VERIFIED LIVE 2026-08-16: Add Activities stamps `authorEmail` with the login email of whoever holds the token, not the source note's author, and the timestamp is call time (not backdatable). In a partner-run migration this writes the partner's address across the merchant's whole order history \u2014 prefix the source author/date into the message body when that provenance matters. See ecom/order-merchant-note."
-    },
-    {
-      "code": "contact-crosswalk-sequencing",
-      "severity": "blocker",
-      "summary": "Import creates no contact; contacts (including guest buyers from order billing emails) must be imported first so buyerInfo.contactId can be passed."
-    },
-    {
-      "code": "beta-single-order",
-      "severity": "warning",
-      "summary": "Import Order is Beta and single-order only (no bulk endpoint); undocumented rate limits apply at scale."
-    },
-    {
-      "code": "analytics-not-suppressible",
-      "severity": "warning",
-      "summary": "Imported orders appear in sales analytics/reports with no documented exclusion flag."
-    },
-    {
-      "code": "imported-orders-invisible-to-events",
-      "severity": "warning",
-      "summary": "Only the OrderImported event fires and only eCom's own indexer consumes it \u2014 imported orders never materialize in contacts/loyalty/event-driven views."
-    },
-    {
-      "code": "checkout-custom-field-values-need-definitions",
-      "severity": "warning",
-      "summary": "A checkout-field-editor-style plugin's custom field VALUES ride as unregistered order postmeta with no fixed key or envelope (see woo-checkout-field-editor-pro.json's values-have-no-fallback-envelope-key pitfall) \u2014 they cannot be identified, let alone written as extendedFields.namespaces._user_fields entries, until the field list (label/type/meta-key) is known. Without it, these values are not degraded, they are entirely unattempted."
-    },
-    "buyerInfo.memberId is what member-facing reads authorize on. A member-identity Get Order returns an order only if that member placed it, and the invoice download backend checks the same field again itself -- so an imported order carrying only buyerInfo.contactId is invisible to its own buyer, and one attributed to the WRONG member hands that member someone else's invoice. Both checks read the same stored value, so neither catches a bad crosswalk. Setting and validating buyerInfo.memberId is a prerequisite of any member-facing order feature, not something those features can verify.",
-    "VERIFIED LIVE 2026-09-05: `createdDate` sent to Import Order is IGNORED. The order reads back with createdDate = the moment of the import, while `purchasedDate` and the payment record's own createdDate both hold the real source dates. Earlier notes here claimed createdDate was settable; the live sentinel printed it but only ever asserted purchasedDate, so the claim was never actually tested. Do not report createdDate as preserved history, and do not use it to reconcile against a source date -- purchasedDate is the field that carries when the order happened.",
-    "LIVE-FOUND 2026-09-05: Import Order rejects an order with no `status` and no `billingInfo.contactDetails` -- 400 \"status value is required\" and \"contactDetails must not be empty\". A billing ADDRESS alone does not satisfy it. Neither field is obvious from the response shape, and the 400 names them only once you have already omitted them.",
-    {
-      "code": "existing-id-replaces-silently",
-      "severity": "blocker",
-      "summary": "VERIFIED LIVE 2026-09-05: Import Order with the `id` of an EXISTING imported order replaces its whole body with no conflict response -- nothing distinguishes \"replace my own earlier import\" from \"overwrite the merchant's edits since\", and an omitted field is cleared rather than kept. So never re-send an order that already exists: `lib/order-history.js` reads by derived id on a crosswalk miss and reconciles an existing order instead of importing. Payments and extendedFields do survive a replace, so an accidental one loses order-body edits, not payment history or preserved documents."
-    },
-    {
-      "code": "buyerinfo-memberid-stored-unvalidated",
-      "severity": "blocker",
-      "summary": "VERIFIED LIVE 2026-09-05 (fresh site): Import Order accepts `buyerInfo.memberId` with or without `contactId` and reads it back; it ALSO accepts a memberId that is not a member on the site and stores it as-is -- no validation, no error. Since member-facing reads and the invoice download authorize on this field, a wrong value hands one member another's order. The field is set only from `lib/order-buyer.js` resolveOrderBuyer -- member crosswalk row whose loginEmail equals the order's billing email -- stamped; the composite refuses a caller-set memberId on the body and requires the body's buyerInfo.email to be the email the member was corroborated against. That corroborated-email requirement applies to the SOURCE-DERIVED body, checked once before the first send; a contact-field retry may send the verified memberId without the email Import Order's rejection named, keeping memberId and contactId unchanged. A memberId alone reads back without a contactId (no derivation)."
-    },
-    {
-      "code": "malformed-contact-value-fails-the-whole-order",
-      "severity": "blocker",
-      "summary": "OBSERVED LIVE: a single email or phone Import Order refuses -- on billingInfo, shippingInfo or buyerInfo -- fails the ENTIRE order, not just that field. The source's validation is weaker than Wix's, so real historical orders carry values the source stored happily (see crm/contact's source-email-can-fail-the-target-validator for the observed email shape), and they surface on live orders rather than in testing. The rule is order-contact-field-refused-fails-whole-order above; this entry does not widen it. Remove only the email or phone field the rejection itself names and send the order once more; if that single retry is also refused, the order is `order-import-failed` -- reported as failed, its source record and rejection kept, and listed for a person to act on. Never remove, rewrite or invent a value on a local check alone (a local check only warns), and never add a second retry or a runner-side drop around the composite. Three consequences to plan and report for: (1) the removed value is not on the imported order and must not be assumed to exist on the linked contact -- it stays recoverable only from the run's on-disk source extraction, and no result, journal row, report or repo file carries the value itself; (2) an order imported without a field is a fidelity loss, not a clean import: it reads back complete, so only its order-contact-email-dropped / order-contact-phone-dropped finding separates it from a fully preserved order, and a reconciliation that compares counts or re-reads orders cannot see it; (3) Import Order still requires `billingInfo.contactDetails` to be non-empty, so removing the named field can leave the order invalid -- the retry is then refused and the order fails; do not remove further fields to get it through."
-    },
-    {
-      "code": "member-area-order-history-list-matches-by-contactid-not-memberid",
-      "severity": "info",
-      "summary": "LIVE-VERIFIED 2026-09-16: a customer promoted from a safe-mode contact to a real-email Member AFTER their orders were already imported with only `buyerInfo.contactId` (no `memberId` -- the promotion flow never resends Import Order) could immediately see their full order history in the site's Member Area, with no order-backfill write at all. This does NOT contradict `buyerinfo-memberid-stored-unvalidated` above: the Member Area's order-history list is reading by the order's `buyerInfo.contactId` matching the member's OWN contactId, which is guaranteed here because promotion reuses the pre-existing contact rather than creating a new one (see crm/contact's mappingGuidance and the ensureMember composite). This is a narrower claim than 'memberId is unnecessary' -- it confirms the customer-facing order-LIST view specifically, for exactly this contactId-preserving promotion order (contacts/orders imported first, member created afterward on the same contact). It does NOT retest member-scoped API reads (a member-identity Get Order call) or invoice-download authorization, which the still-standing blocker above says authorize on `memberId` specifically and were not re-verified against a contactId-only order in this pass. Do not generalize this to 'memberId can be skipped' for any workflow that authorizes programmatically rather than through the Member Area UI."
-    },
-    {
-      "code": "order-contact-field-refused-fails-whole-order",
-      "severity": "blocker",
-      "summary": "A source email or phone Import Order refuses fails the ENTIRE order, not just the field, so the financial record is lost to a descriptive detail. Resolution: remove only a contact field the rejection itself NAMES -- a 400 whose `details.validationError.fieldViolations[].field`, after an optional leading `order.`, exactly equals a `safeModeContactFields[]` path, with no other violation -- and send the order once more under the same derived id; a second refusal is `order-import-failed`. Never remove or rewrite a field on a local or customer-path check alone (the E.164 rule in members/member `phone-must-be-e164-and-dedupes-across-contacts` is verified for Contacts/Members, not Import Order), and never invent a stand-in value. On a member-linked order the retry keeps `buyerInfo.memberId`/`contactId`. `order-history.js` `importOrderHistory` does this and emits `order-contact-email-dropped`/`order-contact-phone-dropped` (field and reason, never the value); `checkOrderContactFields` only warns (`-suspect`). NOT VERIFIED LIVE for Import Order: no contact-field rejection body has been captured. The first live rejection must record its error shape (without the value)."
-    },
-    {
-      "code": "import-order-currency-default-not-applied",
-      "severity": "blocker",
-      "summary": "Verified on a disposable site: omitting currency from Import Order stored an empty currency despite the documented site default. The dashboard order page then failed with an invalid-currency rendering error. Always provide explicit source currency; the corrected reference canary separately verified shipping/tax fidelity."
-    }
-  ],
-  "mappingGuidance": [
-    "Resolve product, variation, contact, and coupon crosswalks before writing orders.",
-    "Contacts import first, orders second: Import Order accepts buyerInfo.contactId (schema-checked 2026-08-04) but creates no contact itself \u2014 always pass the crosswalked contact ID, including for guest buyers derived from order billing emails (see crm/contact). The field doc's 'automatically created if one doesn't exist' text is shared with live Create Order and is unverified for the import path \u2014 do not rely on it.",
-    "Use order and line-item extended fields for source-only metadata when configured.",
-    "A per-order merchant note or comment from the source (e.g. a WooCommerce order note, or a payment-gateway plugin's note field) has no import-time field \u2014 `activities[]` is read-only on Create/Import Order (dev.wix.com verified 2026-08-11). Add it as a SEPARATE follow-up call after the order is imported: POST /ecom/v1/orders/{orderId}/activities/add with activityType MERCHANT_COMMENT and merchantComment.message (max 5000 chars). This stamps authorEmail and createdDate at migration time \u2014 the original note's author and timestamp cannot be preserved; prefix the message with the original date/author if that provenance matters.",
-    "Source order notes map to merchant comment activities (POST /ecom/v1/orders/{id}/activities) after the order import, preserving original author/date inside the message text \u2014 verified live 2026-08-12.",
-    "Always set channelInfo = { type: \"OTHER_PLATFORM\", externalOrderId: <source order id>, externalOrderUrl: <source order edit link, if constructible> }. This documented field makes the source identity visible on the Wix order as well as in the local crosswalk. lib/order-channel-build.js's buildChannelInfo() constructs it; the caller constructs or omits externalOrderUrl because legacy post-based order storage and WooCommerce HPOS use different admin URL shapes.",
-    "If the order bought a gift card, import that line item normally and use the gift-card crosswalk for later redemption linking. If the order redeemed a gift card as payment, do not reconstruct that from WooCommerce order data because the required source signal is absent from /wc/v3/orders. Record an explicit blocked capability until verified source gift-card activity data is available; lib/gift-card-redemption-build.js's buildGiftCardRedemption() builds the redemption call from that activity row.",
-    "ADDED 2026-08-17 \u2014 full sub-object review against the live Import Order request schema (dev.wix.com, fetched 2026-08-17), reconciled with the already-live-verified sibling entities (order-line-item, order-line-item-options, order-applied-discount, order-merchant-note, order-refund):",
-    "lineItems[].catalogReference is optional overall (a custom, non-catalog line has none) but catalogItemId+appId are required together when it is present, as verified by gift-card orders imported without catalogReference. appId picks the dependency: Wix Stores' fixed app id -> stores/product; the Wix Gift Cards app id (d80111c5-a0f4-47a8-b63a-65b54d774a27, see domains/gift-cards/domain.json) -> gift-cards/gift-card-product. Resolve the crosswalk for whichever catalog the line actually belongs to \u2014 never assume Stores.",
-    "Verified on a disposable site with explicit source currency: omit shippingInfo.carrierId and shippingInfo.code for historical order import while preserving the single source shipping line title, price and available logistics. Both isolated and combined omission preserved the shipping method and cost in Get Order and the dashboard. Included target references must still resolve through current, fully passed setup evidence; never use source or invented IDs.",
-    "Verified on a disposable site: omit lineItems[].taxInfo.taxGroupId while preserving explicit source tax amounts and the order-level breakdown. Isolated and combined omission preserved tax display. The order-level taxInfo.taxBreakdown entries have tax name/type/rate/aggregated amount, not a taxGroupId field. Required setup edges remain task-complete.",
-    "Reviewed and found to need NO crosswalk dependency (plain data, no other-entity reference): recipientInfo (final-recipient address/contact, distinct from shippingInfo.logistics.shippingDestination \u2014 both are just address+contact data), businessLocation.id (a Wix Locations id; no domain entity models Locations in this repo yet \u2014 treat as informational/omit if the source has no location concept), customFields/extendedFields (free-form key:value, extendedFields additionally requires the namespace to be pre-configured in the app dashboard \u2014 a setup step, not an entity crosswalk), lineItems[].subscriptionInfo (subscription cycle metadata carried as-is, no subscription-entity crosswalk found on the Import Order path), additionalFees (free-form fee records, no crosswalk), buyerNote/tags/weightUnit/currency/taxIncludedInPrices/attributionSource/buyerLanguage (scalar/enum fields, no dependency).",
-    "purchasedDate/number are settable on import and immutable after (order.number must additionally be numeric \u2014 see the order-number-must-be-numeric pitfall); createdDate/updatedDate/fulfillmentStatus/createdBy/currencyConversionDetails (once set) are read-only or import-then-immutable \u2014 do not attempt to set the ones docs mark read-only, and do not rely on an LLM-summarized docs read for this distinction without cross-checking wix-writers.js's own live-verified required-field comment on buildImportOrderRequest, which already caught fields a generic docs summary got wrong (e.g. incorrectly claiming catalogReference is unconditionally required).",
-    "Never resend an existing derived order ID to backfill shipping. Preserve existing-order adoption. Use the verified bundled omission mapping for the tested scope; a changed or unverified mapping remains blocked until a disposable-site canary proves source title/cost/tax and dashboard fidelity; API acceptance alone proves no meaning. Zero source shipping lines omit shippingInfo; one maps source title/cost; multiple defer with order-multiple-shipping-lines and a blocker gap. Setup-produced edges always require every bound step to pass. Use only gate-owned setup-reference resolutions for any required target IDs."
-  ],
-  "setupRequirements": [
-    "Order data extension schema if extended fields are used.",
-    "Side-effect verification before execution."
-  ],
-  "evidence": [
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-object",
-      "note": "object page (docs-survey sweep 2026-08-11)"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/add-activities",
-      "note": "Add Activities with activityType MERCHANT_COMMENT is the verified post-import path for a source order note or comment."
-    },
-    {
-      "type": "live-run",
-      "path": "anonymized-live-verification",
-      "note": "Verified live: create + query-back readback, safe mode on \u2014 orders via the import-safe Import Order flow, read back; no notification/inventory side effects observed"
-    },
-    {
-      "type": "wix-docs",
-      "url": "https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/import-order",
-      "note": "A full Import Order request-schema review cross-checked every field against live-verified sibling entities and wix-writers.js. Live gift-card order imports without catalogReference confirmed that the field is optional overall."
-    },
-    {
-      "type": "live-verification",
-      "path": "anonymized-live-verification",
-      "note": "Order <anonymized-id> imported via POST /ecom/v1/orders/import with lineItems carrying only quantity/itemType/productName/price \u2014 no catalogReference \u2014 and succeeded, confirming catalogReference is genuinely optional on this endpoint."
-    },
-    {
-      "type": "live-verification",
-      "path": "anonymized-live-verification",
-      "note": "Import Order id semantics, confirmed by probes on a disposable site: never-seen v4 and derived v5-style GUIDs accepted and returned unchanged; same-id re-send is a full replace (createdDate kept, updatedDate moved, omitted purchasedDate cleared, one order per number); payments and extendedFields survive the replace; extendedFields settable through Import Order; non-GUID id -> 400; Bulk Delete Imported Orders returns a jobId and a deleted id re-imports. One refuted: Search Orders by the OLD number still matched ~1s after a renumber (eventually consistent) -- search is not an existence check."
-    },
-    {
-      "type": "live-verification",
-      "path": "anonymized-live-verification",
-      "note": "Nine synthetic historical Import Order cases with explicit currency were each accepted, read back and inspected in the dashboard, after requiring the all-valid baseline to pass first. Shipping and line-item tax references were independently omitted, jointly omitted, individually invalidated, or partially omitted. Source shipping title/cost and explicit tax amounts/breakdown displayed faithfully in all nine. The selected combined omission is the tested joint-omission case. Invalid IDs were stored verbatim and confer no permission to invent references; setup dependencies remain task-complete."
-    }
-  ],
-  "intendedFields": [
-    {
-      "targetPath": "order.number",
-      "sourcePaths": [
-        "number"
-      ]
-    },
-    {
-      "targetPath": "order.lineItems[]",
-      "sourcePaths": [
-        "lineItems[]"
-      ]
-    },
-    {
-      "targetPath": "order.billingInfo",
-      "sourcePaths": [
-        "billingInfo"
-      ]
-    },
-    {
-      "targetPath": "order.shippingInfo",
-      "sourcePaths": [
-        "shippingInfo"
-      ]
-    }
-  ],
-  "readBackProjection": {
-    "identity": "derived-id-and-sent-number",
-    "serverOwned": [
-      {
-        "path": "order.createdDate",
-        "reason": "import ignores creation timestamp"
-      },
-      {
-        "path": "order.updatedDate",
-        "reason": "server timestamp"
-      },
-      {
-        "path": "order.activities",
-        "reason": "server history"
-      }
-    ],
-    "read": "GET /ecom/v1/orders/{id}",
-    "arrays": {
-      "lineItems": "id",
-      "appliedDiscounts": "content"
-    }
-  },
-  "dependencyModes": {
-    "crm/contact": "per-record",
-    "stores/product": "per-record",
-    "stores/coupon": "per-record",
-    "gift-cards/gift-card": "per-record"
-  },
-  "dependencyReferenceFields": {
-    "crm/contact": [
-      "buyerInfo.contactId"
-    ],
-    "stores/product": [
-      "lineItems[].catalogReference.catalogItemId"
-    ],
-    "stores/coupon": [
-      "appliedDiscounts[].coupon.id"
-    ],
-    "gift-cards/gift-card": [
-      "appliedDiscounts[].giftCard.id"
-    ],
-    "ecom/shipping-option": [
-      "shippingInfo.code"
-    ],
-    "ecom/delivery-profile": [
-      "shippingInfo.carrierId"
-    ],
-    "tax/tax-group": [
-      "lineItems[].taxInfo.taxGroupId"
-    ]
-  },
-  "importReferenceCanary": {
-    "verifiedAt": "2026-10-19",
-    "scope": "historical Import Order with a synthetic custom item, explicit currency, one shipping line and preserved explicit tax breakdown",
-    "taxGroupPath": "lineItems[].taxInfo.taxGroupId",
-    "selectedCell": 4,
-    "cells": [
-      {
-        "cell": 1,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 2,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 3,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 4,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 5,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 6,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 7,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 8,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      },
-      {
-        "cell": 9,
-        "accepted": true,
-        "readBackVerified": true,
-        "dashboardVerified": true,
-        "shippingFidelity": true,
-        "taxFidelity": true
-      }
-    ]
-  }
-}