@thorprovider/adapters 5.0.9 → 5.0.11

package/src/providers/medusa/index.ts

@@ -38,9 +38,20 @@ import type {
   StorefrontConfig,
   DesignerConfig,
   DesignerHistoryEntry,
+  CatalogQuery,
+  CatalogAppliedFilters,
+  CatalogQueryOutcome,
+  CatalogFacetId,
+  CatalogFacetDemonstrationSource,
+  FacetSupport,
 } from '@thorprovider/types';
-import { StorefrontConfigError } from '@thorprovider/types';
+import { StorefrontConfigError } from '../../core/errors';
 import type { CommerceProvider, ProviderConfig } from '../../types/provider';
+import type {
+  CartCompletionCapable,
+  CartCompletionError,
+  CartCompletionResult,
+} from '../../types/completion';
 import { MEDUSA_CAPABILITIES } from '../../types/capabilities.types';
 import { createLogger } from '../../core/logger';
 import { fetchWithRetry, type RetryConfig } from '../../core/fetch-utils';
@@ -56,7 +67,344 @@ import {
 } from '../../metadata';
 
 const MEDUSA_CART_RETRIEVE_FIELDS =
-  '+items,+items.variant,+items.variant.product,+items.variant.product.thumbnail,+items.variant.options,+items.variant.options.option';
+  '+items,+items.variant,+items.variant.product,+items.variant.product.thumbnail,+items.variant.options,+items.variant.options.option,+items.total,+items.unit_price,+items.item_subtotal,+items.item_total,+shipping_methods,+shipping_methods.id,+shipping_methods.shipping_option_id';
+
+/**
+ * Fields requested when completing a cart into an order.
+ *
+ * The native `complete` default projection is minimal, so the returned order's
+ * `items` are empty. `*items` selects all fields of the `items` relation
+ * (Medusa field syntax: `*` retrieves all fields of a relation), which yields
+ * each line's `id`, `title`, `product_title`, `variant_title`, `quantity`,
+ * `unit_price` and `total` (all major units, backend-authoritative). The same
+ * query is applied when completion returns a cart-with-error, and `*items` is
+ * valid for both entities.
+ */
+const MEDUSA_ORDER_COMPLETION_FIELDS = '*items';
+
+/**
+ * Per-request catalog listing bound (change B, decision 5).
+ *
+ * Listing is paginated with a configured per-request bound instead of an
+ * unbounded scan. Live probes against the acceptance backend accepted
+ * `limit` 1/50/100/200/1000, so 50 is a deliberately conservative *configured*
+ * bound — NOT a claimed backend maximum. Override with
+ * `MEDUSA_CATALOG_PAGE_SIZE` or `MedusaProviderConfig.catalogPageSize`.
+ */
+const DEFAULT_CATALOG_PAGE_SIZE = 50;
+
+function resolveCatalogPageSize(configured?: number): number {
+  const fromEnv =
+    process.env.MEDUSA_CATALOG_PAGE_SIZE !== undefined
+      ? Number(process.env.MEDUSA_CATALOG_PAGE_SIZE)
+      : undefined;
+  const raw = configured ?? fromEnv;
+  if (raw === undefined || !Number.isFinite(raw) || raw < 1) {
+    return DEFAULT_CATALOG_PAGE_SIZE;
+  }
+  return Math.floor(raw);
+}
+
+/**
+ * Resolve the configured sales channel for cart scoping.
+ *
+ * Prefers the server-only `MEDUSA_SALES_CHANNEL_ID`, then the legacy public
+ * `NEXT_PUBLIC_SALES_CHANNEL_ID`. Returns `undefined` when neither is set, so
+ * the caller can fall back to the backend's publishable-key channel.
+ */
+function resolveConfiguredSalesChannelId(): string | undefined {
+  return (
+    process.env.MEDUSA_SALES_CHANNEL_ID ??
+    process.env.NEXT_PUBLIC_SALES_CHANNEL_ID
+  );
+}
+
+/**
+ * Canonical Thor sort keys → Medusa Store `/store/products` `order` field names.
+ *
+ * Medusa's Store API only accepts fields on the route's allowed list (for
+ * products: `title`, `created_at`, …) and fails a request with a 400 when the
+ * field is not allowed (Store API pagination/sort contract). Thor's canonical
+ * keys therefore cannot be passed through raw:
+ *
+ * - `featured` → no `order` (server default ordering)
+ * - `name`     → `title`
+ * - `newest`   → `-created_at`
+ *
+ * Legacy `SortOption` keys (`price-asc`, `price-desc`, `rating`) are not
+ * supported at the query level and map to `null` (server default), preserving
+ * the existing client-side behavior instead of sending an invalid order field.
+ * `null` means "omit `order` entirely".
+ */
+const MEDUSA_SORT_KEY_MAP: Record<string, string | null> = {
+  featured: null,
+  name: 'title',
+  newest: '-created_at',
+  'price-asc': null,
+  'price-desc': null,
+  rating: null,
+};
+
+/**
+ * Effective category scope for a canonical query (E2 task 2.2).
+ *
+ * The route category scope (`categoryScope`) is always retained; the
+ * `categories` filter narrows within it. Returns `undefined` when no category
+ * filter is requested, `[]` for an explicit empty intersection (a valid
+ * zero-result query), or the handles to resolve to backend IDs.
+ */
+function resolveEffectiveCategoryHandles(
+  query: CatalogQuery,
+): string[] | undefined {
+  const { categoryScope, categories } = query;
+  if (categoryScope === undefined) return categories;
+  if (categories === undefined) return [categoryScope];
+  return categories.filter((handle) => handle === categoryScope);
+}
+
+/**
+ * Filters a successful (or explicitly-empty) canonical result reports as
+ * applied. Every requested filter that the adapter actually applied appears
+ * here; unappliable filters never reach this path (they return a typed error).
+ *
+ * `includeAdvanced` is set only on a path that genuinely applied the requested
+ * price/stock/attribute filters (the advanced endpoint execution, or a
+ * zero-result scope short-circuit where the requested filters are moot because
+ * the scope already matches nothing). The basic `/store/products` path never
+ * includes them — it does not accept those parameters.
+ */
+function buildAppliedCatalogFilters(
+  query: CatalogQuery,
+  effectiveCategoryHandles: string[] | undefined,
+  includeAdvanced = false,
+): CatalogAppliedFilters {
+  return {
+    ...(query.text ? { text: query.text } : {}),
+    ...(effectiveCategoryHandles !== undefined
+      ? { categories: effectiveCategoryHandles }
+      : {}),
+    ...(query.collections !== undefined
+      ? { collections: query.collections }
+      : {}),
+    ...(includeAdvanced && query.priceMin !== undefined
+      ? { priceMin: query.priceMin }
+      : {}),
+    ...(includeAdvanced && query.priceMax !== undefined
+      ? { priceMax: query.priceMax }
+      : {}),
+    ...(includeAdvanced && query.inStock !== undefined
+      ? { inStock: query.inStock }
+      : {}),
+    ...(includeAdvanced && query.attributes !== undefined
+      ? { attributes: query.attributes }
+      : {}),
+  };
+}
+
+/**
+ * Basic fields the canonical `/store/products` endpoint actually accepts. A
+ * basic demonstration's `appliedQuery` is limited to these; price/stock/
+ * attribute filters are never recorded as applied by the basic endpoint because
+ * it does not accept them.
+ */
+function buildBasicDemonstratedQuery(query: CatalogQuery): CatalogQuery {
+  return {
+    ...(query.text !== undefined ? { text: query.text } : {}),
+    ...(query.categoryScope !== undefined
+      ? { categoryScope: query.categoryScope }
+      : {}),
+    ...(query.categories !== undefined ? { categories: query.categories } : {}),
+    ...(query.collections !== undefined
+      ? { collections: query.collections }
+      : {}),
+  };
+}
+
+/**
+ * The optional advanced listing endpoint. Medusa's Store `/store/products`
+ * endpoint (the equivalent basic endpoint) applies category/collection/text/
+ * sort/pagination only; price, stock, and attribute filters require this
+ * separate search plugin (E2 Decision 5). Its presence is proven by a real
+ * request, never by a capability boolean or returned facet metadata.
+ */
+const ADVANCED_SEARCH_ENDPOINT = '/store/search';
+
+/** The canonical basic listing endpoint that serves a basic-only request. */
+const BASIC_LISTING_ENDPOINT = '/store/products';
+
+/**
+ * Canonical query fields that require the optional advanced endpoint. Empty
+ * means the request is basic-only and can be served by `/store/products`.
+ */
+function collectRequestedAdvancedFields(query: CatalogQuery): string[] {
+  const fields: string[] = [];
+  if (query.priceMin !== undefined) fields.push('priceMin');
+  if (query.priceMax !== undefined) fields.push('priceMax');
+  if (query.inStock !== undefined) fields.push('inStock');
+  for (const name of Object.keys(query.attributes ?? {})) {
+    fields.push(`attr.${name}`);
+  }
+  return fields;
+}
+
+/** Map a requested advanced field name to the canonical facet id it needs. */
+function advancedFieldToFacet(field: string): CatalogFacetId {
+  if (field === 'priceMin' || field === 'priceMax') return 'price';
+  return field as CatalogFacetId;
+}
+
+/**
+ * Advanced fields requested through the legacy `searchProductsAdvanced` options.
+ * Empty means the caller asked for a basic-only search that `getProducts` can
+ * faithfully serve as a fallback.
+ */
+function collectAdvancedSearchRequestFields(
+  options?: AdvancedSearchProductsOptions,
+): string[] {
+  const fields: string[] = [];
+  if (options?.priceMin !== undefined) fields.push('priceMin');
+  if (options?.priceMax !== undefined) fields.push('priceMax');
+  if (options?.inStockOnly === true) fields.push('inStock');
+  if (options?.attributes && options.attributes.length > 0) {
+    fields.push('attributes');
+  }
+  return fields;
+}
+
+/**
+ * Parse a value the backend may serialize as a number or a numeric string into
+ * a finite number, or `undefined`. Shared by the applied-filter readers so a
+ * non-finite or missing bound is never treated as an applied filter.
+ */
+function toFiniteNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Read the real backend's `applied_filters.price_range` object (`{ min, max }`,
+ * or `null` when no price filter was applied) into finite bounds. A missing,
+ * non-object, or non-finite bound yields `undefined` so the price facet is never
+ * fabricated (E2 Decision 2: price requires a finite, ordered range).
+ */
+function readAppliedPriceRange(
+  applied: Record<string, unknown>,
+): { min?: number; max?: number } {
+  const range = applied.price_range;
+  if (!range || typeof range !== 'object' || Array.isArray(range)) return {};
+  const record = range as Record<string, unknown>;
+  return { min: toFiniteNumber(record.min), max: toFiniteNumber(record.max) };
+}
+
+/**
+ * Read the filters a real advanced-endpoint response echoes as applied. Only
+ * explicit `applied_filters`/`appliedFilters` keys count as proof; a response
+ * that omits them demonstrates nothing and the facet stays held (E2 Decision 5:
+ * returned facet metadata is not proof).
+ *
+ * The real backend emits `price_range` (object) and `is_available` (boolean);
+ * the documented legacy aliases (`price`/`price_min`/`price_max`,
+ * `inStock`/`isAvailable`/`available`) stay recognized (E2 Decision 1).
+ */
+function mapAppliedFiltersToFacets(
+  applied: Record<string, unknown>,
+): Set<CatalogFacetId> {
+  const facets = new Set<CatalogFacetId>();
+  const priceRange = readAppliedPriceRange(applied);
+  const hasAppliedPriceRange =
+    priceRange.min !== undefined && priceRange.max !== undefined;
+  if (
+    hasAppliedPriceRange ||
+    'price' in applied ||
+    'price_min' in applied ||
+    'price_max' in applied
+  ) {
+    facets.add('price');
+  }
+  if (
+    typeof applied.is_available === 'boolean' ||
+    'inStock' in applied ||
+    'isAvailable' in applied ||
+    'available' in applied
+  ) {
+    facets.add('inStock');
+  }
+  const attributes = applied.attributes;
+  if (attributes && typeof attributes === 'object' && !Array.isArray(attributes)) {
+    for (const name of Object.keys(attributes)) {
+      facets.add(`attr.${name}` as CatalogFacetId);
+    }
+  }
+  return facets;
+}
+
+/**
+ * Requested advanced fields the actual advanced-endpoint response did not
+ * confirm as applied. A probe echo alone cannot guarantee the listing request
+ * applied the filter, so the executed response is re-validated against every
+ * requested field (value equality where the backend echoes a scalar) before a
+ * result is reported as success (E2 task 2.4).
+ */
+function collectUnappliedAdvancedFields(
+  applied: Record<string, unknown>,
+  query: CatalogQuery,
+): string[] {
+  const unapplied: string[] = [];
+
+  const priceRange = readAppliedPriceRange(applied);
+
+  if (query.priceMin !== undefined) {
+    const echoed = toFiniteNumber(
+      priceRange.min ?? applied.price_min ?? applied.priceMin,
+    );
+    if (echoed !== query.priceMin) unapplied.push('priceMin');
+  }
+  if (query.priceMax !== undefined) {
+    const echoed = toFiniteNumber(
+      priceRange.max ?? applied.price_max ?? applied.priceMax,
+    );
+    if (echoed !== query.priceMax) unapplied.push('priceMax');
+  }
+  if (query.inStock === true) {
+    const echoed =
+      applied.is_available ??
+      applied.isAvailable ??
+      applied.inStock ??
+      applied.available;
+    if (echoed !== true && echoed !== 'true') unapplied.push('inStock');
+  }
+
+  const requestedAttributes = query.attributes ?? {};
+  const appliedAttributes = applied.attributes;
+  for (const name of Object.keys(requestedAttributes)) {
+    const hasName =
+      !!appliedAttributes &&
+      typeof appliedAttributes === 'object' &&
+      !Array.isArray(appliedAttributes) &&
+      name in (appliedAttributes as Record<string, unknown>);
+    if (!hasName) unapplied.push(`attr.${name}`);
+  }
+
+  return unapplied;
+}
+
+/**
+ * Read a backend-supplied numeric facet value (range bound or option count).
+ *
+ * Returns `undefined` when the backend did not supply a finite number, so
+ * callers can omit the value entirely instead of inventing a default. This is
+ * the guard that keeps `getAvailableFilters` from fabricating ranges or counts
+ * (E2 Decision 4; spec "Facet counts and ranges are never fabricated").
+ */
+function readFiniteFacetNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? value
+    : undefined;
+}
 
 /**
  * Medusa provider configuration
@@ -85,6 +433,13 @@ export interface MedusaProviderConfig extends ProviderConfig {
    */
   regionId?: string;
 
+  /**
+   * Per-request catalog listing bound. Listing is paginated with this bound
+   * instead of an unbounded scan; it is a configured safety bound, not a
+   * backend maximum. Defaults to `MEDUSA_CATALOG_PAGE_SIZE` or 50.
+   */
+  catalogPageSize?: number;
+
   /**
    * Authentication configuration (optional)
    * If not provided, auth methods will not be available
@@ -126,10 +481,23 @@ export interface MedusaProviderConfig extends ProviderConfig {
  *
  * Implements CommerceProvider interface for Medusa.js v2
  */
-export class MedusaProvider implements CommerceProvider {
+export class MedusaProvider implements CommerceProvider, CartCompletionCapable {
   readonly name = 'medusa';
   readonly version = '2.0.0';
 
+  /**
+   * Canonical catalog sort keys this provider applies at the query level.
+   *
+   * Advertises only the backend-verified orderings (E2 Decision 6). `price-asc`,
+   * `price-desc`, and `rating` are intentionally absent: they are not applied at
+   * the query level, so the listing never offers them as global sorts.
+   *
+   * The literal tuple is assignable to `CommerceProvider['supportedCatalogSortKeys']`
+   * (`readonly CatalogSortKey[]`); it is written structurally here so the adapter
+   * compiles against the published `@thorprovider/types` declaration.
+   */
+  readonly supportedCatalogSortKeys = ['featured', 'name', 'newest'] as const;
+
   /**
    * Medusa backend capabilities.
    * Starts with static defaults, replaced by dynamic values from
@@ -154,6 +522,15 @@ export class MedusaProvider implements CommerceProvider {
   private baseUrl: string;
   private publishableKey: string;
   private regionId?: string;
+  /** Configured per-request catalog listing bound (never an unbounded scan). */
+  private catalogPageSize: number;
+
+  /**
+   * Per-scope cache of the truthful facet-support descriptor. The optional
+   * advanced endpoint is probed once per demonstrated scope/query rather than on
+   * every listing request (E2 task 2.4).
+   */
+  private facetSupportCache = new Map<string, Promise<FacetSupport>>();
 
   /** Secret API key for admin operations (if configured). */
   private adminApiKey?: string;
@@ -212,6 +589,7 @@ export class MedusaProvider implements CommerceProvider {
     this.baseUrl = config.baseUrl;
     this.publishableKey = config.publishableKey;
     this.regionId = config.regionId;
+    this.catalogPageSize = resolveCatalogPageSize(config.catalogPageSize);
 
     // Store retry configuration
     this.retryConfig = {
@@ -238,11 +616,22 @@ export class MedusaProvider implements CommerceProvider {
       // Always use JWT mode for auth - SDK needs to send Bearer tokens
       // Configure storage method for JWT tokens (browser only)
       auth: config.auth
-        ? {
-            type: 'jwt',
-            // Use localStorage in browser, memory storage on server
-            jwtTokenStorageMethod: typeof window !== 'undefined' ? 'local' : 'memory',
-          }
+        ? config.auth.customStorage
+          ? {
+              type: 'jwt',
+              // Request-scoped custom storage: the caller supplies a per-request
+              // token holder (for example a server request's customer JWT). The
+              // SDK reads the token on every request and writes the login /
+              // registration token back into the same holder, so a fresh
+              // provider per request is authenticated without shared state.
+              jwtTokenStorageMethod: 'custom',
+              storage: config.auth.customStorage,
+            }
+          : {
+              type: 'jwt',
+              // Use localStorage in browser, memory storage on server
+              jwtTokenStorageMethod: typeof window !== 'undefined' ? 'local' : 'memory',
+            }
         : undefined,
     });
 
@@ -385,45 +774,65 @@ export class MedusaProvider implements CommerceProvider {
     throw lastError;
   }
 
-  async getProduct(handle: string, options?: { regionId?: string }): Promise<Product | undefined> {
-    this.logger.debug('getProduct', { handle, regionId: options?.regionId });
+  /** Fields needed to price a product variant for the current region. */
+  private buildProductFields(regionId?: string): string {
+    // calculated_price requires region_id in Medusa v2 — only request it when available
+    const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags';
+    const pricingFields = ',+variants.calculated_price,+variants.prices';
+    return regionId ? baseFields + pricingFields : baseFields;
+  }
 
-    try {
-      return await this.withRetry(
-        async () => {
-          const regionId = options?.regionId ?? this.regionId;
-          // calculated_price requires region_id in Medusa v2 — only request it when available
-          const baseFields = '+variants,+variants.inventory_quantity,+options,+images,+tags';
-          const pricingFields = ',+variants.calculated_price,+variants.prices';
-          const fields = regionId ? baseFields + pricingFields : baseFields;
+  /** Scope a store query to the configured storefront sales channel, if any. */
+  private applySalesChannelScope(queryParams: Record<string, unknown>): void {
+    const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+    if (salesChannelId) {
+      queryParams.sales_channel_id = [salesChannelId];
+    }
+  }
 
-          const queryParams: any = {
-            handle,
-            limit: 1,
-            fields,
-          };
-          // Add region_id for region-based pricing
-          if (regionId) {
-            queryParams.region_id = regionId;
-          }
+  /**
+   * Directed single-product lookup by a supported native filter (`handle` or
+   * `id`). This is independent of catalog listing pagination, so a known
+   * product beyond the first listing page still resolves without scanning.
+   *
+   * Medusa's store API supports `handle` and `id` on `/store/products`; it
+   * does not expose a variant filter there, so a variant is resolved from the
+   * product once the product is known (see `getProductDetailByHandle` in the
+   * runtime). No `limit` beyond 1 is issued.
+   */
+  private async fetchSingleProduct(
+    filter: { handle?: string; id?: string },
+    options?: { regionId?: string },
+  ): Promise<Product | undefined> {
+    const regionId = options?.regionId ?? this.regionId;
+
+    const queryParams: Record<string, unknown> = {
+      ...filter,
+      limit: 1,
+      fields: this.buildProductFields(regionId),
+    };
+    // Add region_id for region-based pricing
+    if (regionId) {
+      queryParams.region_id = regionId;
+    }
+    this.applySalesChannelScope(queryParams);
 
-          // Scope to storefront sales channel when configured.
-          const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
-          if (salesChannelId) {
-            queryParams.sales_channel_id = [salesChannelId];
-          }
+    const { products } = await this.sdk.store.product.list(queryParams as any);
 
-          const { products } = await this.sdk.store.product.list(queryParams);
+    if (!products || products.length === 0) {
+      this.logger.debug('Product not found', filter);
+      return undefined;
+    }
 
-          if (!products || products.length === 0) {
-            this.logger.debug('Product not found', { handle });
-            return undefined;
-          }
+    return transformProduct(products[0], this.currencyCode);
+  }
 
-          const transformedProduct = transformProduct(products[0], this.currencyCode);
+  async getProduct(handle: string, options?: { regionId?: string }): Promise<Product | undefined> {
+    this.logger.debug('getProduct', { handle, regionId: options?.regionId });
 
-          return transformedProduct;
-        },
+    try {
+      return await this.withRetry(
+        () => this.fetchSingleProduct({ handle }, options),
         'getProduct',
         { handle, regionId: options?.regionId },
       );
@@ -436,6 +845,31 @@ export class MedusaProvider implements CommerceProvider {
     }
   }
 
+  /**
+   * Directed product lookup by backend product ID. Independent of the first
+   * listing page, mirroring `getProduct` for handle-based resolution.
+   */
+  async getProductById(
+    id: string,
+    options?: { regionId?: string },
+  ): Promise<Product | undefined> {
+    this.logger.debug('getProductById', { id, regionId: options?.regionId });
+
+    try {
+      return await this.withRetry(
+        () => this.fetchSingleProduct({ id }, options),
+        'getProductById',
+        { id, regionId: options?.regionId },
+      );
+    } catch (error: any) {
+      throw new ProviderAPIError(
+        `Failed to fetch product by id: ${error.message}`,
+        'medusa',
+        error.status,
+      );
+    }
+  }
+
   async getProducts(options: GetProductsOptions & { regionId?: string } = {}): Promise<Product[]> {
     this.logger.debug('getProducts', options);
 
@@ -448,28 +882,25 @@ export class MedusaProvider implements CommerceProvider {
           const pricingFields = ',+variants.calculated_price,+variants.prices';
           const fields = regionId ? baseFields + pricingFields : baseFields;
 
-          // Map Thor SortOption values to Medusa /store/products `order` field names.
-          // Native endpoint supports: title, -title, created_at, -created_at
-          // Price sorting (price-asc, price-desc) is not supported — omitted so
-          // products-client.tsx handles it client-side as before.
-          const SORT_KEY_MAP: Record<string, string | null> = {
-            featured:     null,          // server default order
-            name:         'title',       // A→Z by product title
-            newest:       '-created_at', // newest products first
-            'price-asc':  null,          // not supported by native endpoint → client-side
-            'price-desc': null,          // not supported by native endpoint → client-side
-            rating:       null,          // not supported → server default
-          };
+          // Map Thor sort keys to Medusa /store/products `order` field names.
+          // Native endpoint supports: title, -title, created_at, -created_at.
+          // Price/rating sorting is not supported — omitted so products-client
+          // handles it client-side as before (see MEDUSA_SORT_KEY_MAP).
 
+          // Bounded, paginated listing (change B, decision 5): the per-request
+          // limit is the configured catalog bound, never an unbounded scan.
           const queryParams: any = {
             q: options.query,
-            limit: options.first ?? 100,
-            offset: options.after ? parseInt(String(options.after), 10) : undefined,
+            limit: options.first ?? this.catalogPageSize,
+            offset:
+              options.after !== undefined
+                ? parseInt(String(options.after), 10)
+                : options.skip,
             fields,
           };
 
           if (options.sortKey) {
-            const mappedOrder = SORT_KEY_MAP[options.sortKey] ?? null;
+            const mappedOrder = MEDUSA_SORT_KEY_MAP[options.sortKey] ?? null;
             if (mappedOrder !== null) {
               queryParams.order = mappedOrder;
             }
@@ -516,12 +947,623 @@ export class MedusaProvider implements CommerceProvider {
         fullError: JSON.stringify(error, null, 2),
       });
 
-      throw new ProviderAPIError(
-        `Failed to fetch products: ${error.message || 'Unknown error'}`,
-        'medusa',
-        error.status,
-      );
+      throw new ProviderAPIError(
+        `Failed to fetch products: ${error.message || 'Unknown error'}`,
+        'medusa',
+        error.status,
+      );
+    }
+  }
+
+  /**
+   * Canonical catalog query path (E2 task 2.2).
+   *
+   * Accepts a validated `CatalogQuery`, translates it into Medusa Store
+   * `/store/products` parameters, and returns a truthful `CatalogQueryOutcome`.
+   * The route category scope is always retained and intersected with the
+   * `categories` filter; `categories`/`collections` handles are resolved to
+   * backend IDs through the existing directed lookups (`getCategory`/
+   * `getCollection`). Any requested filter this provider cannot apply
+   * (price/`inStock`/attributes) is rejected as a typed `unsupported-query`
+   * outcome naming the fields — never a partial success and never a silent
+   * drop. Pagination is `offset = (page - 1) * pageSize`, defaulting to the
+   * canonical page size.
+   *
+   * Legacy `getProducts`/`getCategoryProducts` are unchanged; this additive
+   * method is the typed seam the runtime query bridge (E2 task 3.1) consumes.
+   */
+  async getCatalogProducts(query: CatalogQuery): Promise<CatalogQueryOutcome> {
+    this.logger.debug('getCatalogProducts', query);
+
+    // Sort support is advertised explicitly by the adapter; an unadvertised
+    // sort is rejected before any provider call.
+    if (
+      query.sort !== undefined &&
+      !this.supportedCatalogSortKeys.includes(query.sort)
+    ) {
+      return this.unsupportedCatalogOutcome(['sort']);
+    }
+
+    const effectiveCategoryHandles = resolveEffectiveCategoryHandles(query);
+
+    try {
+      const categoryIds =
+        effectiveCategoryHandles !== undefined
+          ? await this.resolveCategoryIds(effectiveCategoryHandles)
+          : undefined;
+      const collectionIds = query.collections
+        ? await this.resolveCollectionIds(query.collections)
+        : undefined;
+
+      // The truthful support descriptor for this scope, proven against the real
+      // optional endpoint. It is attached to every successful result.
+      const facetSupport = await this.getCatalogFacetSupport({
+        query,
+        categoryIds,
+        collectionIds,
+        scope: query.categoryScope,
+      });
+
+      // Reject every requested advanced field that was not demonstrated BEFORE
+      // any early zero-result return, so an unsupported filter is never hidden
+      // behind an empty category intersection or an unresolved handle.
+      const requestedAdvanced = collectRequestedAdvancedFields(query);
+      const heldAdvanced = requestedAdvanced.filter(
+        (field) => !facetSupport.offered.includes(advancedFieldToFacet(field)),
+      );
+      if (heldAdvanced.length > 0) {
+        return this.unsupportedCatalogOutcome(heldAdvanced);
+      }
+
+      // A scope that matches nothing (explicit empty route-scope ∩ categories
+      // intersection, or a requested category/collection that resolves to no
+      // backend ID) is a valid zero-result query — never an unfiltered request.
+      // Requested+offered advanced filters are included as applied because the
+      // scope already excludes every product; they are not silently dropped.
+      const emptyIntersection =
+        effectiveCategoryHandles !== undefined &&
+        effectiveCategoryHandles.length === 0;
+      const categoryFilterEmpty =
+        effectiveCategoryHandles !== undefined &&
+        (categoryIds?.length ?? 0) === 0;
+      const collectionFilterEmpty =
+        query.collections !== undefined && (collectionIds?.length ?? 0) === 0;
+      if (emptyIntersection || categoryFilterEmpty || collectionFilterEmpty) {
+        return {
+          ok: true,
+          results: {
+            products: [],
+            appliedFilters: buildAppliedCatalogFilters(
+              query,
+              effectiveCategoryHandles,
+              requestedAdvanced.length > 0,
+            ),
+            facetSupport,
+          },
+        };
+      }
+
+      // When advanced filters were requested and demonstrated, the request is
+      // executed against the real advanced endpoint and re-validated there;
+      // it is never served by the basic endpoint with the filters dropped.
+      if (requestedAdvanced.length > 0) {
+        return this.queryAdvancedCatalog(
+          query,
+          categoryIds,
+          collectionIds,
+          facetSupport,
+        );
+      }
+
+      return await this.queryBasicCatalog(
+        query,
+        effectiveCategoryHandles,
+        categoryIds,
+        collectionIds,
+        facetSupport,
+      );
+    } catch (error: any) {
+      this.logger.error('getCatalogProducts error details', {
+        message: error.message,
+        status: error.status,
+      });
+      throw new ProviderAPIError(
+        `Failed to run catalog query: ${error.message || 'Unknown error'}`,
+        'medusa',
+        error.status,
+      );
+    }
+  }
+
+  /**
+   * Execute a basic-only canonical query against the equivalent basic endpoint
+   * `/store/products`, reporting the filters it actually applied.
+   */
+  private async queryBasicCatalog(
+    query: CatalogQuery,
+    effectiveCategoryHandles: string[] | undefined,
+    categoryIds: string[] | undefined,
+    collectionIds: string[] | undefined,
+    facetSupport: FacetSupport,
+  ): Promise<CatalogQueryOutcome> {
+    const pageSize = query.pageSize ?? this.catalogPageSize;
+    const page = query.page ?? 1;
+    const regionId = this.regionId;
+    const baseFields =
+      '+variants,+variants.inventory_quantity,+options,+images,+thumbnail,+tags';
+    const pricingFields = ',+variants.calculated_price,+variants.prices';
+
+    const queryParams: any = {
+      limit: pageSize,
+      offset: (page - 1) * pageSize,
+      fields: regionId ? baseFields + pricingFields : baseFields,
+    };
+
+    if (query.text) {
+      queryParams.q = query.text;
+    }
+    if (categoryIds && categoryIds.length > 0) {
+      queryParams.category_id = categoryIds;
+    }
+    if (collectionIds && collectionIds.length > 0) {
+      queryParams.collection_id = collectionIds;
+    }
+
+    // Canonical sort → Medusa `order`; `null` omits the parameter entirely.
+    if (query.sort) {
+      const mappedOrder = MEDUSA_SORT_KEY_MAP[query.sort] ?? null;
+      if (mappedOrder !== null) {
+        queryParams.order = mappedOrder;
+      }
+    }
+
+    if (regionId) {
+      queryParams.region_id = regionId;
+    }
+
+    const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+    if (salesChannelId) {
+      queryParams.sales_channel_id = [salesChannelId];
+    }
+
+    const response = (await this.sdk.store.product.list(queryParams)) as any;
+    const products = (response.products ?? []).map((p: any) =>
+      transformProduct(p, this.currencyCode),
+    );
+    const count = response.count;
+
+    return {
+      ok: true,
+      results: {
+        products,
+        // Total is only the backend's actual count; never manufactured.
+        ...(typeof count === 'number' ? { total: count } : {}),
+        appliedFilters: buildAppliedCatalogFilters(
+          query,
+          effectiveCategoryHandles,
+        ),
+        facetSupport,
+      },
+    };
+  }
+
+  /**
+   * Execute an advanced canonical query against the real optional endpoint
+   * `/store/search`, then re-validate that the response applied every requested
+   * filter. A response that does not confirm a requested field, or an endpoint
+   * failure, yields a typed `unsupported-query` error — never a partial result
+   * labelled success and never a silent fallback to the basic endpoint.
+   */
+  private async queryAdvancedCatalog(
+    query: CatalogQuery,
+    categoryIds: string[] | undefined,
+    collectionIds: string[] | undefined,
+    facetSupport: FacetSupport,
+  ): Promise<CatalogQueryOutcome> {
+    const pageSize = query.pageSize ?? this.catalogPageSize;
+    const page = query.page ?? 1;
+    const advancedQuery = this.buildAdvancedSearchQuery(
+      query,
+      categoryIds ?? [],
+      collectionIds ?? [],
+    );
+    advancedQuery.limit = pageSize;
+    advancedQuery.offset = (page - 1) * pageSize;
+
+    let data: any;
+    try {
+      // Custom route: use the SDK client so the publishable API key and headers
+      // are applied automatically (building-storefronts `sdk-client-fetch`).
+      data = await this.sdk.client.fetch(ADVANCED_SEARCH_ENDPOINT, {
+        query: advancedQuery,
+      });
+    } catch (error: any) {
+      this.logger.error('Advanced catalog listing failed', {
+        message: error?.message,
+        status: error?.status,
+      });
+      // Do not fall back to the basic endpoint: that would silently drop the
+      // requested advanced filters.
+      return this.unsupportedCatalogOutcome(
+        collectRequestedAdvancedFields(query),
+      );
+    }
+
+    const appliedRaw = data?.applied_filters ?? data?.appliedFilters;
+    if (!appliedRaw || typeof appliedRaw !== 'object') {
+      this.logger.warn('Advanced endpoint did not echo applied filters', {
+        endpoint: ADVANCED_SEARCH_ENDPOINT,
+      });
+      return this.unsupportedCatalogOutcome(
+        collectRequestedAdvancedFields(query),
+      );
+    }
+
+    const unapplied = collectUnappliedAdvancedFields(
+      appliedRaw as Record<string, unknown>,
+      query,
+    );
+    if (unapplied.length > 0) {
+      this.logger.warn('Advanced endpoint did not apply requested filters', {
+        endpoint: ADVANCED_SEARCH_ENDPOINT,
+        fields: unapplied,
+      });
+      return this.unsupportedCatalogOutcome(unapplied);
+    }
+
+    const products = (data.hits ?? []).map((hit: any) =>
+      transformProduct(hit, this.currencyCode),
+    );
+    const total =
+      typeof data.estimatedTotalHits === 'number'
+        ? data.estimatedTotalHits
+        : typeof data.count === 'number'
+          ? data.count
+          : undefined;
+
+    return {
+      ok: true,
+      results: {
+        products,
+        ...(total !== undefined ? { total } : {}),
+        appliedFilters: buildAppliedCatalogFilters(
+          query,
+          resolveEffectiveCategoryHandles(query),
+          true,
+        ),
+        facetSupport,
+      },
+    };
+  }
+
+  /** Resolve category handles to Medusa category IDs via directed lookups. */
+  private async resolveCategoryIds(handles: string[]): Promise<string[]> {
+    const ids: string[] = [];
+    for (const handle of handles) {
+      const category = await this.getCategory(handle);
+      if (category) ids.push(category.id);
+    }
+    return ids;
+  }
+
+  /** Resolve collection handles to Medusa collection IDs via directed lookups. */
+  private async resolveCollectionIds(handles: string[]): Promise<string[]> {
+    const ids: string[] = [];
+    for (const handle of handles) {
+      const collection = await this.getCollection(handle);
+      if (collection) ids.push(collection.id);
+    }
+    return ids;
+  }
+
+  /**
+   * Truthful facet-support descriptor for a scope (E2 task 2.4).
+   *
+   * Basic facets (`categories`, `collections`) are always offered: they are
+   * applied by the canonical basic endpoint `/store/products`, and the
+   * descriptor records that endpoint with the applied query and scope as their
+   * demonstration source.
+   *
+   * Optional advanced facets (`price`, `inStock`, and advertised `attr.<name>`)
+   * are offered only when the real optional `/store/search` endpoint has been
+   * demonstrated with the applied query for the current scope AND the response
+   * echoes the filter as applied. Otherwise they are held with the real probe
+   * status/reason — a capability boolean or returned facet metadata is never
+   * accepted as proof (E2 Decisions 4–5; spec "Backend support is proven against
+   * the real endpoint, not assumed").
+   *
+   * The descriptor carries no counts or ranges and no invented timestamp; every
+   * offered facet has an actual `{ endpoint, appliedQuery, scope }` source.
+   */
+  async getCatalogFacetSupport(
+    options: {
+      query?: CatalogQuery;
+      categoryIds?: string[];
+      collectionIds?: string[];
+      scope?: string;
+    } = {},
+  ): Promise<FacetSupport> {
+    const query = options.query ?? {};
+    const scope = options.scope ?? query.categoryScope;
+    const key = JSON.stringify({
+      scope: scope ?? null,
+      categoryIds: options.categoryIds ?? null,
+      collectionIds: options.collectionIds ?? null,
+      categories: query.categories ?? null,
+      text: query.text ?? null,
+      collections: query.collections ?? null,
+      priceMin: query.priceMin ?? null,
+      priceMax: query.priceMax ?? null,
+      inStock: query.inStock ?? null,
+      attributes: query.attributes ?? null,
+    });
+    const cached = this.facetSupportCache.get(key);
+    if (cached) return cached;
+    const pending = this.resolveCatalogFacetSupport(
+      query,
+      options.categoryIds,
+      options.collectionIds,
+      scope,
+    );
+    this.facetSupportCache.set(key, pending);
+    return pending;
+  }
+
+  private async resolveCatalogFacetSupport(
+    query: CatalogQuery,
+    providedCategoryIds: string[] | undefined,
+    providedCollectionIds: string[] | undefined,
+    scope: string | undefined,
+  ): Promise<FacetSupport> {
+    // The advanced demonstration records the full applied filter query; the
+    // basic demonstration records only the fields `/store/products` actually
+    // accepts (text/scope/categories/collections). Price/stock/attributes are
+    // never recorded as applied by an endpoint that does not accept them.
+    const advancedDemonstratedQuery: CatalogQuery = {
+      ...(query.text !== undefined ? { text: query.text } : {}),
+      ...(query.categoryScope !== undefined
+        ? { categoryScope: query.categoryScope }
+        : {}),
+      ...(query.categories !== undefined ? { categories: query.categories } : {}),
+      ...(query.collections !== undefined
+        ? { collections: query.collections }
+        : {}),
+      ...(query.priceMin !== undefined ? { priceMin: query.priceMin } : {}),
+      ...(query.priceMax !== undefined ? { priceMax: query.priceMax } : {}),
+      ...(query.inStock !== undefined ? { inStock: query.inStock } : {}),
+      ...(query.attributes !== undefined
+        ? { attributes: query.attributes }
+        : {}),
+    };
+    const basicDemonstratedQuery = buildBasicDemonstratedQuery(query);
+    const scopeField = scope !== undefined ? { scope } : {};
+
+    const offered: CatalogFacetId[] = ['categories', 'collections'];
+    const demonstrations: Record<string, CatalogFacetDemonstrationSource> = {
+      categories: {
+        endpoint: BASIC_LISTING_ENDPOINT,
+        appliedQuery: basicDemonstratedQuery,
+        ...scopeField,
+      },
+      collections: {
+        endpoint: BASIC_LISTING_ENDPOINT,
+        appliedQuery: basicDemonstratedQuery,
+        ...scopeField,
+      },
+    };
+    const held: CatalogFacetId[] = [];
+    const heldReasons: Record<string, string> = {};
+
+    const categoryIds =
+      providedCategoryIds ?? (await this.resolveScopeCategoryIds(query));
+    const collectionIds =
+      providedCollectionIds ??
+      (query.collections
+        ? await this.resolveCollectionIds(query.collections)
+        : []);
+    const candidates: CatalogFacetId[] = ['price', 'inStock'];
+    for (const handle of await this.resolveFilterableAttributeHandles(
+      categoryIds,
+    )) {
+      const facet = `attr.${handle}` as CatalogFacetId;
+      if (!candidates.includes(facet)) candidates.push(facet);
+    }
+
+    const probe = await this.probeAdvancedSearchSupport(
+      query,
+      categoryIds,
+      collectionIds,
+    );
+    if (probe.available) {
+      for (const facet of candidates) {
+        if (probe.applied.has(facet)) {
+          offered.push(facet);
+          demonstrations[facet] = {
+            endpoint: ADVANCED_SEARCH_ENDPOINT,
+            appliedQuery: advancedDemonstratedQuery,
+            ...scopeField,
+          };
+        } else {
+          held.push(facet);
+          heldReasons[facet] =
+            `not echoed as applied by ${ADVANCED_SEARCH_ENDPOINT}`;
+        }
+      }
+    } else {
+      for (const facet of candidates) {
+        held.push(facet);
+        heldReasons[facet] = probe.reason;
+      }
+    }
+
+    return {
+      offered,
+      held,
+      demonstrations,
+      ...(Object.keys(heldReasons).length > 0 ? { heldReasons } : {}),
+    };
+  }
+
+  /**
+   * Demonstrate the optional advanced endpoint with the applied query for the
+   * current scope. A non-2xx response (including the HTTP 404/500 an absent
+   * plugin returns), an unparseable body, or a response that does not echo the
+   * applied filters all mean the facet is not demonstrated — never a silent
+   * assumption of support. Uses a single SDK request (no retry): a support probe
+   * must not amplify a broken optional endpoint into repeated requests.
+   */
+  private async probeAdvancedSearchSupport(
+    query: CatalogQuery,
+    categoryIds: string[],
+    collectionIds: string[],
+  ): Promise<{
+    available: boolean;
+    applied: Set<CatalogFacetId>;
+    reason: string;
+    status?: number;
+  }> {
+    const advancedQuery = this.buildAdvancedSearchQuery(
+      query,
+      categoryIds,
+      collectionIds,
+    );
+    advancedQuery.limit = 1;
+    try {
+      // Custom route: use the SDK client so the publishable API key and headers
+      // are applied automatically (building-storefronts `sdk-client-fetch`).
+      const data: any = await this.sdk.client.fetch(ADVANCED_SEARCH_ENDPOINT, {
+        query: advancedQuery,
+      });
+      const appliedRaw = data?.applied_filters ?? data?.appliedFilters;
+      if (!appliedRaw || typeof appliedRaw !== 'object') {
+        return {
+          available: false,
+          applied: new Set(),
+          reason: `${ADVANCED_SEARCH_ENDPOINT} did not echo applied filters; support unverified`,
+        };
+      }
+      return {
+        available: true,
+        applied: mapAppliedFiltersToFacets(
+          appliedRaw as Record<string, unknown>,
+        ),
+        reason: `${ADVANCED_SEARCH_ENDPOINT} demonstrated with the applied query`,
+      };
+    } catch (error: any) {
+      const status =
+        typeof error?.status === 'number' ? error.status : undefined;
+      // Surface the absence/log it; never swallow it silently.
+      this.logger.warn('Optional advanced search endpoint not demonstrated', {
+        endpoint: ADVANCED_SEARCH_ENDPOINT,
+        status,
+        message: error?.message,
+      });
+      return {
+        available: false,
+        applied: new Set(),
+        reason:
+          status !== undefined
+            ? `${ADVANCED_SEARCH_ENDPOINT} returned ${status}; optional advanced endpoint not demonstrated`
+            : `${ADVANCED_SEARCH_ENDPOINT} unavailable: ${extractErrorMessage(error)}`,
+        ...(status !== undefined ? { status } : {}),
+      };
+    }
+  }
+
+  /**
+   * Build the advanced-endpoint query parameters from the canonical query. The
+   * SDK serializes the plain object, so no manual stringification is needed.
+   */
+  private buildAdvancedSearchQuery(
+    query: CatalogQuery,
+    categoryIds: string[],
+    collectionIds: string[],
+  ): Record<string, unknown> {
+    const advancedQuery: Record<string, unknown> = {};
+    if (query.text) advancedQuery.q = query.text;
+    if (categoryIds.length > 0) advancedQuery.categories = categoryIds.join(',');
+    if (collectionIds.length > 0) {
+      advancedQuery.collections = collectionIds.join(',');
+    }
+    if (query.priceMin !== undefined) advancedQuery.price_min = query.priceMin;
+    if (query.priceMax !== undefined) advancedQuery.price_max = query.priceMax;
+    if (query.inStock === true) advancedQuery.isAvailable = true;
+    if (query.attributes) {
+      // The backend route declares `attributes: z.string()` and JSON-parses an
+      // ARRAY of `{ id, values }`. The canonical query carries a
+      // `Record<string, string[]>`, so map it before serializing.
+      const attributes = Object.entries(query.attributes).map(([id, values]) => ({
+        id,
+        values,
+      }));
+      advancedQuery.attributes = JSON.stringify(attributes);
+    }
+    if (query.sort) {
+      const mappedOrder = MEDUSA_SORT_KEY_MAP[query.sort] ?? null;
+      if (mappedOrder !== null) advancedQuery.order = mappedOrder;
+    }
+    if (this.regionId) advancedQuery.region_id = this.regionId;
+    if (this.currencyCode) {
+      advancedQuery.currency_code = this.currencyCode.toLowerCase();
+    }
+    return advancedQuery;
+  }
+
+  /** Resolve the effective category scope of a query to backend IDs. */
+  private async resolveScopeCategoryIds(query: CatalogQuery): Promise<string[]> {
+    const handles = resolveEffectiveCategoryHandles(query);
+    if (handles === undefined || handles.length === 0) return [];
+    return this.resolveCategoryIds(handles);
+  }
+
+  /**
+   * Advertised filterable attribute handles for the scope. The custom-attributes
+   * endpoint is facet *metadata* (which attributes exist), not proof that a
+   * filter can be applied; these handles are candidates only, and each still
+   * requires the advanced endpoint to echo it as applied before it is offered.
+   */
+  private async resolveFilterableAttributeHandles(
+    categoryIds: string[],
+  ): Promise<string[]> {
+    const handles: string[] = [];
+    for (const categoryId of categoryIds) {
+      try {
+        // Custom route: use the SDK client so the publishable API key and
+        // headers are applied automatically (building-storefronts
+        // `sdk-client-fetch`).
+        const data: any = await this.sdk.client.fetch(
+          `/store/custom-attributes/category/${categoryId}`,
+        );
+        for (const item of data?.attributes ?? []) {
+          const attr = item.attribute ?? item;
+          if (
+            attr?.is_filterable &&
+            attr?.is_active &&
+            typeof attr.handle === 'string' &&
+            attr.handle.length > 0
+          ) {
+            handles.push(attr.handle);
+          }
+        }
+      } catch {
+        // The optional custom-attributes endpoint may be absent; its absence
+        // simply means no advertised attribute facets for the scope.
+      }
     }
+    return handles;
+  }
+
+  /** Build a typed `unsupported-query` outcome naming the offending fields. */
+  private unsupportedCatalogOutcome(fields: string[]): CatalogQueryOutcome {
+    return {
+      ok: false,
+      error: {
+        code: 'unsupported-query',
+        fields,
+        message: `Unsupported catalog query: ${fields.join(', ')}`,
+        repair: { remove: fields },
+      },
+    };
   }
 
   async getProductRecommendations(productId: string): Promise<Product[]> {
@@ -555,18 +1597,14 @@ export class MedusaProvider implements CommerceProvider {
   }> {
     this.logger.debug('searchProductsAdvanced', options);
 
-    // Check if advanced search is available
+    // Check if advanced search is available. A capability boolean is not proof,
+    // but when it is false the optional endpoint is definitely not wired; a
+    // basic-only caller still gets the faithful `getProducts` fallback while a
+    // caller that requested an advanced filter is rejected instead of silently
+    // receiving unfiltered products (E2 task 2.4).
     if (!this.capabilities.advancedSearch) {
-      this.logger.warn('Advanced search not available, falling back to getProducts()');
-      const products = await this.getProducts(options);
-      return {
-        products,
-        meta: {
-          limit: options?.first ?? 20,
-          offset: Number(options?.after ?? 0),
-          hybridSearchUsed: false,
-        },
-      };
+      this.logger.warn('Advanced search capability disabled, using faithful fallback');
+      return this.fallbackAdvancedSearch(options);
     }
 
     try {
@@ -704,22 +1742,49 @@ export class MedusaProvider implements CommerceProvider {
 
       return { products, meta };
     } catch (error: any) {
-      this.logger.error('Advanced search failed, falling back to getProducts()', {
+      this.logger.error('Advanced search failed, using faithful fallback', {
         error: error.message,
         stack: error.stack,
       });
 
-      // Graceful fallback to basic getProducts()
-      const products = await this.getProducts(options);
-      return {
-        products,
-        meta: {
-          limit: options?.first ?? 20,
-          offset: Number(options?.after ?? 0),
-          hybridSearchUsed: false,
-        },
-      };
+      // Do not silently drop advanced filters: a caller that requested price,
+      // stock, or attributes gets a typed failure; a basic-only caller keeps the
+      // faithful `getProducts` fallback.
+      return this.fallbackAdvancedSearch(options);
+    }
+  }
+
+  /**
+   * Faithful fallback for `searchProductsAdvanced`. A basic-only request is
+   * served by `getProducts`; a request that depends on the optional advanced
+   * endpoint is rejected as a typed `ProviderAPIError` naming the unappliable
+   * fields, so a failed advanced search never returns an unfiltered result
+   * labelled success (E2 task 2.4).
+   */
+  private async fallbackAdvancedSearch(
+    options?: AdvancedSearchProductsOptions,
+  ): Promise<{
+    products: Product[];
+    meta?: SearchResultMeta;
+  }> {
+    const requested = collectAdvancedSearchRequestFields(options);
+    if (requested.length > 0) {
+      throw new ProviderAPIError(
+        `Advanced search unavailable for requested fields: ${requested.join(', ')}`,
+        'medusa',
+        undefined,
+        { fields: requested, repair: { remove: requested } },
+      );
     }
+    const products = await this.getProducts(options);
+    return {
+      products,
+      meta: {
+        limit: options?.first ?? 20,
+        offset: Number(options?.after ?? 0),
+        hybridSearchUsed: false,
+      },
+    };
   }
 
   /**
@@ -780,29 +1845,38 @@ export class MedusaProvider implements CommerceProvider {
         }
       }
 
-      // 2. Advanced filters (price, stock)
-      if (options.useAdvancedSearch && this.capabilities.advancedSearch) {
-        // resolved on all requests. Currently omitted to avoid 400 errors from
-        // getProducts fallback when regionId is missing.
-        filters.push({
-          id: 'price',
-          label: 'Price',
-          type: 'range',
-          min: 0,
-          max: 10000,
-          isActive: false,
-          ranking: 0,
-        });
-
-        // Stock availability filter
-        // ID must match the URL param read by page.tsx (?isAvailable=true)
-        filters.push({
-          id: 'isAvailable',
-          label: 'In Stock',
-          type: 'boolean',
-          isActive: false,
-          ranking: 5,
+      // 2. Advanced filters (stock)
+      //
+      // A price range is emitted ONLY when the backend supplies real range
+      // metadata for the current query. Medusa's Store `/store/products`
+      // returns the matching products and a total count, not the filterable
+      // values or their numeric ranges (Store API contract; facets require a
+      // separate search plugin), so there is no price range to read here and
+      // the control is omitted instead of defaulted to a fabricated
+      // `0..10000` (E2 Decision 4; spec "Facet counts and ranges are never
+      // fabricated").
+      //
+      // The stock toggle is offered ONLY when the real optional endpoint has
+      // demonstrated `inStock` for the scope. A capability boolean is not proof
+      // (E2 task 2.4): the backend advertises `advancedSearch: true` while the
+      // optional `/store/search` endpoint is absent, so the toggle is held
+      // rather than shown.
+      if (options.useAdvancedSearch) {
+        const support = await this.getCatalogFacetSupport({
+          categoryIds: options.categoryId ? [options.categoryId] : [],
+          scope: options.categoryId,
         });
+        if (support.offered.includes('inStock')) {
+          // Stock availability filter
+          // ID must match the URL param read by page.tsx (?isAvailable=true)
+          filters.push({
+            id: 'isAvailable',
+            label: 'In Stock',
+            type: 'boolean',
+            isActive: false,
+            ranking: 5,
+          });
+        }
       }
 
       // 3. Custom attributes (category-specific)
@@ -852,20 +1926,37 @@ export class MedusaProvider implements CommerceProvider {
                 ranking: attr.ranking || 50, // Custom attributes lower priority
               };
 
-              // Add options for single/multi types
+              // Add options for single/multi types. A per-option count is
+              // attached only when the caller asked for counts AND the backend
+              // supplied a real finite number; no zero or fabricated count is
+              // invented (E2 Decision 4; spec "Facet counts and ranges are
+              // never fabricated").
               if ((filterType === 'single' || filterType === 'multi') && attr.values) {
-                filter.options = attr.values.map((val: any) => ({
-                  value: this.toSlug(val.value), // URL slug: ?ram=8gb
-                  label: val.value,              // Display: "8GB"
-                  id: val.id,                    // Backend ID: 01KN03N67V13K5S2E6B6695KRN
-                  count: options.includeFacetCounts ? val.count : undefined,
-                }));
+                filter.options = attr.values.map((val: any) => {
+                  const count = options.includeFacetCounts
+                    ? readFiniteFacetNumber(val.count)
+                    : undefined;
+                  return {
+                    value: this.toSlug(val.value), // URL slug: ?ram=8gb
+                    label: val.value,              // Display: "8GB"
+                    id: val.id,                    // Backend ID: 01KN03N67V13K5S2E6B6695KRN
+                    ...(count !== undefined ? { count } : {}),
+                  };
+                });
               }
 
-              // Add range values for numeric types
-              if (filterType === 'range' && attr.metadata) {
-                filter.min = attr.metadata.min || 0;
-                filter.max = attr.metadata.max || 100;
+              // A numeric range is emitted only when the backend supplies BOTH
+              // real bounds. A missing bound is never replaced by a fabricated
+              // `0`/`100` default; without a real range the control is omitted
+              // rather than shown with invented values (E2 Decision 4).
+              if (filterType === 'range') {
+                const min = readFiniteFacetNumber(attr.metadata?.min);
+                const max = readFiniteFacetNumber(attr.metadata?.max);
+                if (min === undefined || max === undefined) {
+                  return; // no real range → omit this range filter
+                }
+                filter.min = min;
+                filter.max = max;
               }
 
               filters.push(filter);
@@ -1311,9 +2402,9 @@ export class MedusaProvider implements CommerceProvider {
     }
 
     try {
-      // Increase limit for client-side filtering to improve search results
-      // If query is present, fetch more items (up to 1000) to increase likelihood of finding matches
-      const limit = options.query ? 1000 : (options.limit ?? 100);
+      // Bounded per-request limit (change B, decision 5): no unbounded scan.
+      // Client-side search filtering still runs over the bounded page.
+      const limit = options.limit ?? this.catalogPageSize;
 
       const queryParams: any = {
         limit,
@@ -1376,13 +2467,24 @@ export class MedusaProvider implements CommerceProvider {
       // Then get products for this category
       const categoryQueryParams: any = {
         category_id: [category.id],
-        order: options.sortKey,
-        limit: options.first ?? 100,
+        // Bounded, paginated listing (change B, decision 5).
+        limit: options.first ?? this.catalogPageSize,
         offset: options.after ? parseInt(options.after, 10) : undefined,
         fields:
-          '+variants,+variants.prices,+variants.calculated_prices,+variants.inventory_quantity,+options,+images,+tags',
+          '+variants,+variants.prices,+variants.calculated_price,+variants.inventory_quantity,+options,+images,+tags',
       };
 
+      // Translate the Thor sort key through the same mapping `getProducts` uses.
+      // A raw canonical key (`name`/`newest`/`featured`) is not a valid Medusa
+      // `order` field and would be rejected by the Store API; `null` omits
+      // `order` so the backend returns its default ordering.
+      const mappedOrder = options.sortKey
+        ? MEDUSA_SORT_KEY_MAP[options.sortKey] ?? null
+        : null;
+      if (mappedOrder !== null) {
+        categoryQueryParams.order = mappedOrder;
+      }
+
       // Region-based pricing (calculated_price requires region_id in Medusa v2)
       if (this.regionId) {
         categoryQueryParams.region_id = this.regionId;
@@ -1436,7 +2538,7 @@ export class MedusaProvider implements CommerceProvider {
       // passing it explicitly is required when the key maps to multiple
       // channels (otherwise cart creation errors).
       const salesChannelId =
-        options?.salesChannelId ?? process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+        options?.salesChannelId ?? resolveConfiguredSalesChannelId();
       if (salesChannelId) {
         createPayload.sales_channel_id = salesChannelId;
       }
@@ -1529,7 +2631,7 @@ export class MedusaProvider implements CommerceProvider {
           };
 
           // Scope to storefront sales channel when configured.
-          const salesChannelId = process.env.NEXT_PUBLIC_SALES_CHANNEL_ID;
+          const salesChannelId = resolveConfiguredSalesChannelId();
           if (salesChannelId) {
             variantCheckParams.sales_channel_id = [salesChannelId];
           }
@@ -2925,36 +4027,96 @@ export class MedusaProvider implements CommerceProvider {
    * @throws {ProviderAPIError} If checkout fails
    */
   async completeCheckout(cartId: string): Promise<Order> {
-    this.logger.debug('completeCheckout', { cartId });
-
-    try {
-      return await this.withRetry(
-        async () => {
-          // Medusa v2: POST /store/carts/:id/complete
-          const { order } = (await this.sdk.store.cart.complete(cartId)) as any;
-
-          if (!order) {
-            throw new ProviderAPIError('Checkout completed but no order returned', 'medusa', 500);
-          }
+    const result = await this.completeCart(cartId);
 
-          this.logger.info('Checkout completed successfully', {
-            orderId: order.id,
-            displayId: order.display_id,
-          });
+    if (result.type === 'order') {
+      return result.order;
+    }
 
-          return transformOrder(order);
-        },
-        'completeCheckout',
-        { cartId },
-      );
-    } catch (error: any) {
-      this.logger.error('Failed to complete checkout', { cartId, error: error.message });
+    if (result.type === 'cart') {
       throw new ProviderAPIError(
-        `Failed to complete checkout: ${error.message}`,
+        `Failed to complete checkout: ${result.error.message}`,
         'medusa',
-        error.status,
+        result.error.status,
       );
     }
+
+    throw new ProviderAPIError(
+      `Checkout outcome is unresolved: ${result.error.message}`,
+      'medusa',
+      result.error.status,
+    );
+  }
+
+  /**
+   * Complete a cart exactly once and preserve the native discriminator
+   * (change B, decision 11).
+   *
+   * Medusa's `POST /store/carts/:id/complete` returns HTTP 200 whose body is
+   * either `{ type: 'order', order }` or `{ type: 'cart', cart, error }`. This
+   * method never retries: a thrown transport/timeout/5xx failure becomes an
+   * `unresolved` result so the caller reconciles the committed cart before any
+   * further attempt. The Medusa JS SDK performs no implicit retry of its own,
+   * so there is no blind retry beneath this call either.
+   */
+  async completeCart(cartId: string): Promise<CartCompletionResult> {
+    this.logger.debug('completeCart', { cartId });
+
+    try {
+      const response = (await this.sdk.store.cart.complete(cartId, {
+        fields: MEDUSA_ORDER_COMPLETION_FIELDS,
+      } as any)) as any;
+
+      if (response?.type === 'cart' || (response?.cart && response?.error)) {
+        const error = this.toCompletionError(response.error);
+        this.logger.warn('Cart completion returned a cart with an error', {
+          cartId,
+          code: error.code,
+          message: error.message,
+        });
+        return { type: 'cart', cart: transformCart(response.cart), error };
+      }
+
+      const order = response?.order;
+      if (!order) {
+        return {
+          type: 'unresolved',
+          error: { message: 'Checkout returned neither an order nor a cart error' },
+        };
+      }
+
+      this.logger.info('Checkout completed successfully', {
+        orderId: order.id,
+        displayId: order.display_id,
+      });
+      return { type: 'order', order: transformOrder(order) };
+    } catch (error: unknown) {
+      const completionError = this.toCompletionError(error);
+      this.logger.error('Cart completion failed (unresolved, not retried)', {
+        cartId,
+        status: completionError.status,
+        message: completionError.message,
+      });
+      return { type: 'unresolved', error: completionError };
+    }
+  }
+
+  /** Normalize any thrown/returned completion failure into a structured error. */
+  private toCompletionError(error: unknown): CartCompletionError {
+    if (error && typeof error === 'object') {
+      const err = error as any;
+      const message =
+        typeof err.message === 'string' && err.message.length > 0
+          ? err.message
+          : extractErrorMessage(error);
+      return {
+        message,
+        code: typeof err.code === 'string' ? err.code : undefined,
+        status: err.status ?? err.statusCode,
+        raw: err,
+      };
+    }
+    return { message: extractErrorMessage(error), raw: error };
   }
 
   /**
@@ -2967,160 +4129,90 @@ export class MedusaProvider implements CommerceProvider {
    * @throws {ProviderAPIError} If cart not found or region not configured
    */
   async getShippingMethods(cartId: string): Promise<import('@thorprovider/types').ShippingMethod[]> {
-    this.logger.info('🚚 [DEBUG] getShippingMethods called', { cartId });
+    this.logger.debug('getShippingMethods', { cartId });
 
     try {
       return await this.withRetry(
         async () => {
-          // Get raw cart to access region
-          this.logger.info('🚚 [DEBUG] Step 1: Retrieving cart from Medusa...', { cartId });
+          // The cart supplies the region and currency the options are priced in.
           const cartResponse = (await this.sdk.store.cart.retrieve(cartId)) as any;
           const { cart } = cartResponse;
 
-          // Log raw cart response for debugging
-          this.logger.info('🚚 [DEBUG] Step 2: Cart retrieved from backend', {
-            cartId,
-            hasCart: !!cart,
-            cartKeys: cart ? Object.keys(cart) : [],
-            regionId: cart?.region_id,
-            currencyCode: cart?.currency_code,
-            shippingAddress: cart?.shipping_address
-              ? {
-                  country: cart.shipping_address.country_code,
-                  postal: cart.shipping_address.postal_code,
-                }
-              : null,
-          });
-
           if (!cart) {
-            this.logger.error('🚚 [DEBUG] ERROR: Cart not found in response', {
-              cartId,
-              cartResponse,
-            });
             throw new ResourceNotFoundError('Cart', cartId);
           }
 
           if (!cart.region_id) {
-            this.logger.error('🚚 [DEBUG] ERROR: Cart has no region_id', {
-              cartId,
-              cart: {
-                id: cart.id,
-                region_id: cart.region_id,
-                region: cart.region,
-                allKeys: Object.keys(cart),
-              },
-            });
             throw new ProviderAPIError('Cart has no region assigned', 'medusa', 400);
           }
 
-          // Fetch shipping options for cart
-          // Medusa v2 endpoint: GET /store/shipping-options?cart_id=...
-          this.logger.info('🚚 [DEBUG] Step 3: Fetching shipping options from Medusa...', {
-            cartId,
-            regionId: cart.region_id,
-            endpoint: `${this.baseUrl}store/shipping-options?cart_id=${cartId}`,
-            note: 'About to fetch shipping options (SDK when available, otherwise HTTP)',
-          });
-
-          let shippingResponse: any;
-          let shipping_options: any;
-
-          try {
-            const storeAny = this.sdk.store as any;
-
-            // Prefer SDK if present (newer SDK versions)
-            if (storeAny?.shippingOption?.list) {
-              shippingResponse = (await storeAny.shippingOption.list({
-                cart_id: cartId,
-              })) as any;
-            } else {
-              // Fallback for SDK versions that don't expose shippingOption typings/APIs
-              const baseUrl = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
-              const url = new URL('store/shipping-options', baseUrl);
-              url.searchParams.set('cart_id', cartId);
-
-              const response = await fetchWithRetry(
-                url.toString(),
-                {
-                  method: 'GET',
-                  headers: {
-                    'x-publishable-api-key': this.publishableKey,
-                    'content-type': 'application/json',
-                  },
-                },
-                this.retryConfig,
-              );
-
-              shippingResponse = (await response.json()) as any;
-            }
+          // Medusa v2: list the shipping options eligible for this cart. The
+          // JS SDK exposes `store.fulfillment.listCartOptions`; fall back to the
+          // equivalent HTTP route for SDK builds that do not.
+          let shippingOptions: any[] = [];
+          const storeAny = this.sdk.store as any;
+
+          if (storeAny?.fulfillment?.listCartOptions) {
+            const response = (await storeAny.fulfillment.listCartOptions({
+              cart_id: cartId,
+            })) as any;
+            shippingOptions = response?.shipping_options ?? [];
+          } else {
+            const baseUrl = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
+            const url = new URL('store/shipping-options', baseUrl);
+            url.searchParams.set('cart_id', cartId);
 
-            shipping_options = shippingResponse.shipping_options;
-          } catch (sdkError: any) {
-            // Log detailed error from Medusa backend
-            this.logger.error(
-              '🚚 [DEBUG] ERROR: Medusa SDK threw error when fetching shipping options',
+            const response = await fetchWithRetry(
+              url.toString(),
               {
-                cartId,
-                regionId: cart.region_id,
-                errorType: sdkError?.constructor?.name,
-                errorMessage: sdkError?.message,
-                errorStatus: sdkError?.status,
-                errorCode: sdkError?.code,
-                errorResponse: sdkError?.response
-                  ? JSON.stringify(sdkError.response, null, 2)
-                  : 'N/A',
-                errorBody: sdkError?.body ? JSON.stringify(sdkError.body, null, 2) : 'N/A',
-                fullError: JSON.stringify(sdkError, Object.getOwnPropertyNames(sdkError), 2),
+                method: 'GET',
+                headers: {
+                  'x-publishable-api-key': this.publishableKey,
+                  'content-type': 'application/json',
+                },
               },
+              this.retryConfig,
             );
-            throw sdkError;
+
+            shippingOptions = ((await response.json()) as any)?.shipping_options ?? [];
           }
 
-          // Log raw shipping options response
-          this.logger.info('🚚 [DEBUG] Step 4: Shipping options received from backend', {
-            cartId,
-            totalOptions: shipping_options?.length || 0,
-            rawResponse: JSON.stringify(shippingResponse, null, 2),
-            firstOption: shipping_options?.[0]
-              ? {
-                  id: shipping_options[0].id,
-                  name: shipping_options[0].name,
-                  allKeys: Object.keys(shipping_options[0]),
-                  price_incl_tax: shipping_options[0].price_incl_tax,
-                  amount: shipping_options[0].amount,
-                  data: shipping_options[0].data,
-                }
-              : null,
-          });
+          const currencyCode = cart.currency_code?.toUpperCase() ?? '';
 
-          const methods = shipping_options.map((option: any) => ({
-            id: option.id,
-            name: option.name,
-            price: {
-              amount: option.price_incl_tax?.toString() || option.amount?.toString() || '0',
-              currencyCode: cart.currency_code?.toUpperCase() || this.currencyCode,
-            },
-            description: option.data?.description,
-            estimatedDays: option.data?.estimated_days || 'N/A',
-          }));
+          // Truthful projection (change B, decision 17): the amount is the
+          // backend's option amount (or its tax-inclusive amount) and is never
+          // replaced with a fabricated `'0'`; an absent description/ETA is
+          // omitted rather than filled with a placeholder like `'N/A'`.
+          return shippingOptions.map((option: any) => {
+            const amount = option?.amount ?? option?.price_incl_tax;
+            const estimatedDays =
+              option?.data?.estimated_days != null
+                ? String(option.data.estimated_days)
+                : undefined;
 
-          // Log transformed methods
-          this.logger.info('🚚 [DEBUG] Step 5: Transformed methods for Thor types', {
-            cartId,
-            count: methods.length,
-            methods: JSON.stringify(methods, null, 2),
+            return {
+              id: option.id,
+              name: option.name,
+              price: {
+                amount:
+                  typeof amount === 'number' && Number.isFinite(amount)
+                    ? amount.toFixed(2)
+                    : '',
+                currencyCode,
+              },
+              description: option?.data?.description,
+              estimatedDays,
+              fulfillmentSetType: option?.service_zone?.fulfillment_set?.type ?? null,
+            };
           });
-
-          return methods;
         },
         'getShippingMethods',
         { cartId },
       );
     } catch (error: any) {
-      this.logger.error('🚚 [DEBUG] ERROR: Failed to fetch shipping methods', {
+      this.logger.error('Failed to fetch shipping methods', {
         cartId,
         errorMessage: error.message,
-        errorStack: error.stack,
         errorStatus: error.status,
       });
       throw new ProviderAPIError(
@@ -3571,22 +4663,19 @@ export class MedusaProvider implements CommerceProvider {
     this.logger.debug('addShippingMethod', { cartId, methodId });
 
     try {
-      return await this.withRetry(
-        async () => {
-          // Medusa v2: POST /store/carts/:id/shipping-methods
-          const { cart } = await this.sdk.store.cart.addShippingMethod(cartId, {
-            option_id: methodId,
-          } as any);
-
-          this.logger.info('Shipping method added successfully', { cartId, methodId });
-
-          void cart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
-        },
-        'addShippingMethod',
-        { cartId, methodId },
-      );
+      // Medusa v2: POST /store/carts/:id/shipping-methods.
+      // This is a non-idempotent mutation, so it is sent exactly once and is
+      // NOT wrapped in a retry (change B, decision 11).
+      await this.sdk.store.cart.addShippingMethod(cartId, {
+        option_id: methodId,
+      } as any);
+
+      this.logger.info('Shipping method added successfully', { cartId, methodId });
+
+      // Re-read the authoritative cart so the recalculated totals come from
+      // the backend rather than the mutation response.
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error: any) {
       this.logger.error('Failed to add shipping method', {
         cartId,
@@ -3611,199 +4700,98 @@ export class MedusaProvider implements CommerceProvider {
    * @throws {ProviderAPIError} If provider invalid or cart not ready
    */
   async initiatePaymentSession(cartId: string, providerId: string): Promise<void> {
-    this.logger.info('💳 [DEBUG] initiatePaymentSession called', { cartId, providerId });
+    this.logger.debug('initiatePaymentSession', { cartId, providerId });
 
     try {
-      await this.withRetry(
-        async () => {
-          // Get RAW cart object from Medusa SDK (not transformed)
-          // CHANGE 1: Add payment_collection fields to query
-          this.logger.info(
-            '💳 [DEBUG] Step 1: Retrieving RAW cart from Medusa for payment session...',
-            { cartId },
-          );
-          const { cart: rawCart } = await this.sdk.store.cart.retrieve(cartId, {
-            fields:
-              '+shipping_methods,+shipping_address,+email,+region_id,+total,+items,+payment_collection,+payment_collection.payment_sessions,+billing_address',
-          });
-
-          this.logger.info('💳 [DEBUG] Step 2: RAW cart retrieved, checking state...', {
-            cartId: rawCart.id,
-            hasShippingMethod: !!rawCart.shipping_methods?.length,
-            shippingMethodIds: rawCart.shipping_methods?.map((sm: any) => sm.id) || [],
-            hasShippingAddress: !!rawCart.shipping_address,
-            shippingAddressCity: rawCart.shipping_address?.city || 'N/A',
-            hasEmail: !!rawCart.email,
-            email: rawCart.email || 'N/A',
-            hasBillingAddress: !!rawCart.billing_address,
-            hasPaymentCollection: !!rawCart.payment_collection,
-            existingSessionsCount: rawCart.payment_collection?.payment_sessions?.length || 0,
-            regionId: rawCart.region_id,
-            total: rawCart.total,
-            itemCount: rawCart.items?.length || 0,
-          });
-
-          // 🛡️ VALIDATION: Cart must have items to create payment session
-          if (!rawCart.items || rawCart.items.length === 0) {
-            this.logger.error('💳 [DEBUG] ERROR: Cannot create payment session for empty cart', {
-              cartId,
-              itemCount: 0,
-              reason: 'Cart has no items',
-            });
-            throw new ProviderAPIError(
-              'Cannot create payment session: cart is empty. Please add items to your cart before checking out.',
-              'medusa',
-              400,
-            );
-          }
-
-          // 🛡️ VALIDATION: Required fields
-          if (!rawCart.shipping_address) {
-            this.logger.error('💳 [DEBUG] ERROR: Shipping address required', { cartId });
-            throw new ProviderAPIError(
-              'Shipping address is required before initiating payment session',
-              'medusa',
-              400,
-            );
-          }
-
-          if (!rawCart.shipping_methods?.length) {
-            this.logger.error('💳 [DEBUG] ERROR: Shipping method required', { cartId });
-            throw new ProviderAPIError(
-              'Shipping method is required before initiating payment session',
-              'medusa',
-              400,
-            );
-          }
-
-          if (!rawCart.email) {
-            this.logger.error('💳 [DEBUG] ERROR: Email required', { cartId });
-            throw new ProviderAPIError(
-              'Email is required before initiating payment session',
-              'medusa',
-              400,
-            );
-          }
-
-          // CHANGE 2: Validate billing address and warn if missing
-          if (!rawCart.billing_address) {
-            this.logger.warn(
-              '💳 [DEBUG] WARNING: Billing address not set, payment provider may require it',
-              {
-                cartId: rawCart.id,
-                shippingAddress: rawCart.shipping_address,
-              },
-            );
-          }
-
-          // CHANGE 3: Check for existing payment sessions (idempotency)
-          // Note: payment_collection is created automatically by Medusa when calling initiatePaymentSession
-          // So we don't need to validate its existence - just check if sessions already exist
-          const existingSessions = rawCart.payment_collection?.payment_sessions || [];
+      // Read the raw cart: the canonical transform does not carry the payment
+      // collection, and the session compatibility check needs the backend's own
+      // session shape (provider, amount, status).
+      const { cart: rawCart } = await this.sdk.store.cart.retrieve(cartId, {
+        fields:
+          '+shipping_methods,+shipping_address,+email,+region_id,+total,+items,+payment_collection,+payment_collection.payment_sessions,+billing_address',
+      });
 
-          if (existingSessions.length > 0) {
-            this.logger.info('💳 [DEBUG] Payment session already exists, skipping creation', {
-              cartId: rawCart.id,
-              sessionCount: existingSessions.length,
-              sessionIds: existingSessions.map((s: any) => s.id),
-            });
+      if (!rawCart.items || rawCart.items.length === 0) {
+        throw new ProviderAPIError(
+          'Cannot create payment session: cart is empty. Please add items to your cart before checking out.',
+          'medusa',
+          400,
+        );
+      }
 
-            // Return early - session already exists
-            return;
-          }
+      if (!rawCart.shipping_address) {
+        throw new ProviderAPIError(
+          'Shipping address is required before initiating payment session',
+          'medusa',
+          400,
+        );
+      }
 
-          this.logger.info('💳 [DEBUG] Step 2.5: No existing payment sessions, will create new one', {
-            cartId: rawCart.id,
-            hasPaymentCollection: !!rawCart.payment_collection,
-            providerId,
-          });
+      // Payment is applied only after shipping totals are final (decision 10).
+      if (!rawCart.shipping_methods?.length) {
+        throw new ProviderAPIError(
+          'Shipping method is required before initiating payment session',
+          'medusa',
+          400,
+        );
+      }
 
-          // Medusa v2 SDK: sdk.store.payment.initiatePaymentSession(cart, options)
-          this.logger.info('💳 [DEBUG] Step 3: Calling Medusa SDK initiatePaymentSession...', {
-            cartId,
-            providerId,
-            endpoint: `${this.baseUrl}store/payment-collections`,
-            note: 'About to call SDK method',
-          });
+      if (!rawCart.email) {
+        throw new ProviderAPIError(
+          'Email is required before initiating payment session',
+          'medusa',
+          400,
+        );
+      }
 
-          // VALIDATION: Ensure provider_id is a valid backend ID
-          // Prevent sending normalized types like 'card', 'wallet', 'cash_on_delivery'
-          this.logger.info('💳 [DEBUG] Step 2.5: Validating provider ID...', {
-            providerId,
-          });
+      validatePaymentId(providerId);
+
+      // Reuse an existing session ONLY when its provider, state and amount are
+      // compatible with the current cart; otherwise create/replace it.
+      const existingSessions: any[] = rawCart.payment_collection?.payment_sessions ?? [];
+      const compatible = existingSessions.find((session: any) => {
+        const statusOk = ['pending', 'requires_more', 'authorized'].includes(session?.status);
+        return (
+          session?.provider_id === providerId &&
+          session?.amount === rawCart.total &&
+          statusOk
+        );
+      });
 
-          try {
-            validatePaymentId(providerId);
-            this.logger.info('💳 [DEBUG] Provider ID validation passed', { providerId });
-          } catch (validationError: any) {
-            this.logger.error('💳 [DEBUG] ERROR: Invalid provider ID detected', {
-              providerId,
-              error: validationError.message,
-              hint: 'Use getBackendProviderId(paymentMethod) to extract correct ID',
-            });
-            throw new ProviderAPIError(
-              validationError.message,
-              'medusa',
-              400
-            );
-          }
+      if (compatible) {
+        this.logger.info('Reusing compatible payment session', {
+          cartId,
+          providerId,
+          sessionId: compatible.id,
+          amount: compatible.amount,
+        });
+        return;
+      }
 
-          let paymentResponse: any;
-          try {
-            paymentResponse = await this.sdk.store.payment.initiatePaymentSession(rawCart as any, {
-              provider_id: providerId,
-            });
+      if (existingSessions.length > 0) {
+        this.logger.info('Existing payment session incompatible; replacing it', {
+          cartId,
+          providerId,
+          existing: existingSessions.map((session: any) => ({
+            id: session.id,
+            providerId: session.provider_id,
+            amount: session.amount,
+            status: session.status,
+          })),
+        });
+      }
 
-            this.logger.info('💳 [DEBUG] Step 4: Payment session response received', {
-              cartId,
-              providerId,
-              responseKeys: paymentResponse ? Object.keys(paymentResponse) : [],
-              response: JSON.stringify(paymentResponse, null, 2),
-            });
-          } catch (sdkError: any) {
-            // CHANGE 4: Enhanced error context
-            this.logger.error(
-              '💳 [DEBUG] ERROR: Medusa SDK threw error when initiating payment session',
-              {
-                cartId,
-                providerId,
-                errorType: sdkError?.constructor?.name,
-                errorMessage: sdkError?.message,
-                errorStatus: sdkError?.status,
-                errorCode: sdkError?.code,
-                errorResponse: sdkError?.response
-                  ? JSON.stringify(sdkError.response, null, 2)
-                  : 'N/A',
-                errorBody: sdkError?.body ? JSON.stringify(sdkError.body, null, 2) : 'N/A',
-                fullError: JSON.stringify(sdkError, Object.getOwnPropertyNames(sdkError), 2),
-                // Include cart state in error for debugging
-                cartState: {
-                  hasShippingMethod: !!rawCart.shipping_methods?.length,
-                  hasShippingAddress: !!rawCart.shipping_address,
-                  hasBillingAddress: !!rawCart.billing_address,
-                  hasEmail: !!rawCart.email,
-                  total: rawCart.total,
-                  itemCount: rawCart.items?.length || 0,
-                },
-              },
-            );
-            throw sdkError;
-          }
+      // Non-idempotent mutation: sent exactly once, never retried.
+      await this.sdk.store.payment.initiatePaymentSession(rawCart as any, {
+        provider_id: providerId,
+      });
 
-          this.logger.info('💳 [DEBUG] Payment session initiated successfully', {
-            cartId,
-            providerId,
-          });
-        },
-        'initiatePaymentSession',
-        { cartId, providerId },
-      );
+      this.logger.info('Payment session initiated', { cartId, providerId });
     } catch (error: any) {
-      this.logger.error('💳 [DEBUG] ERROR: Failed to initiate payment session', {
+      this.logger.error('Failed to initiate payment session', {
         cartId,
         providerId,
         errorMessage: error.message,
-        errorStack: error.stack,
         errorStatus: error.status,
       });
       throw new ProviderAPIError(
@@ -3828,36 +4816,28 @@ export class MedusaProvider implements CommerceProvider {
     this.logger.debug('applyDiscountCode', { cartId, code });
 
     try {
-      return await this.withRetry(
-        async () => {
-          // Medusa v2: POST /store/carts/:id/promotions
-          const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
-            method: 'POST',
-            headers: {
-              'Content-Type': 'application/json',
-              'x-publishable-api-key': this.publishableKey || '',
-            },
-            body: JSON.stringify({
-              promo_codes: [code],
-            }),
-          });
-
-          if (!response.ok) {
-            const error = await response.json();
-            throw new Error(error.message || 'Failed to apply discount code');
-          }
+      // Medusa v2: POST /store/carts/:id/promotions.
+      // Non-idempotent mutation: sent exactly once, never retried.
+      const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-publishable-api-key': this.publishableKey || '',
+        },
+        body: JSON.stringify({
+          promo_codes: [code],
+        }),
+      });
 
-          const { cart: medusaCart } = await response.json();
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || 'Failed to apply discount code');
+      }
 
-          this.logger.info('Discount code applied successfully', { cartId, code });
+      this.logger.info('Discount code applied successfully', { cartId, code });
 
-          void medusaCart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
-        },
-        'applyDiscountCode',
-        { cartId, code },
-      );
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error: any) {
       this.logger.error('Failed to apply discount code', { cartId, code, error: error.message });
       throw new ProviderAPIError(
@@ -3882,36 +4862,28 @@ export class MedusaProvider implements CommerceProvider {
     this.logger.debug('removeDiscountCode', { cartId, code });
 
     try {
-      return await this.withRetry(
-        async () => {
-          // Medusa v2: DELETE /store/carts/:id/promotions
-          const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
-            method: 'DELETE',
-            headers: {
-              'Content-Type': 'application/json',
-              'x-publishable-api-key': this.publishableKey || '',
-            },
-            body: JSON.stringify({
-              promo_codes: [code],
-            }),
-          });
-
-          if (!response.ok) {
-            const error = await response.json();
-            throw new Error(error.message || 'Failed to remove discount code');
-          }
+      // Medusa v2: DELETE /store/carts/:id/promotions.
+      // Non-idempotent mutation: sent exactly once, never retried.
+      const response = await fetch(`${this.baseUrl}/store/carts/${cartId}/promotions`, {
+        method: 'DELETE',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-publishable-api-key': this.publishableKey || '',
+        },
+        body: JSON.stringify({
+          promo_codes: [code],
+        }),
+      });
 
-          const { cart: medusaCart } = await response.json();
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || 'Failed to remove discount code');
+      }
 
-          this.logger.info('Discount code removed successfully', { cartId, code });
+      this.logger.info('Discount code removed successfully', { cartId, code });
 
-          void medusaCart;
-          const updatedCart = await this.retrieveCartWithLineDetails(cartId);
-          return transformCart(updatedCart);
-        },
-        'removeDiscountCode',
-        { cartId, code },
-      );
+      const updatedCart = await this.retrieveCartWithLineDetails(cartId);
+      return transformCart(updatedCart);
     } catch (error: any) {
       this.logger.error('Failed to remove discount code', { cartId, code, error: error.message });
       throw new ProviderAPIError(