fix(wix-manage): three Catalog V3 frictions in find-products and update-product - #927

Three Catalog V3 frictions found in recorded runs, across the two recipes an agent uses together to change something on an existing product. They are in one PR because they compound: an agent answering "set the SKU on the Large size" reads Find Products to locate the product and Update Product to change it, and each defect below costs it a rejected call or a wasted round trip on that single task.

1. Price questions were routed into a full-catalog scan

Query Products cannot filter on price. The recipe listed its filterable fields and said nothing further, so agents paged the whole catalog and compared amounts in their own code.

Price is filterable — on Search Products, via actualPriceRange.minValue.amount, which accepts $lt, $gt, $lte, $gte and the rest. STEP 1 now shows an executable filter, the routing table gains a price row, and STEP 4 says explicitly that price is not in Query Products' set.

Worth recording: adding the routing-table row alone did not change behaviour — the agent kept scanning client-side after reading the recipe, twice. Only making the example executable made it stable.

2. The response envelope was never shown

Neither Search nor Query documented where results arrive. Agents fell back to a Catalog V1-shaped guess and lost a round trip:

the first API execution failed to locate the product because it incorrectly parsed the
search response using Catalog V1/V2 structure (productResults.results) instead of V3
(products), requiring a second corrected API execution

STEP 1 now shows the envelope. Prose competes with a strong prior weakly; an example does not compete at all.

Also corrects the fields enum MIN_VARIANT_PRICE_INFO → MIN_PRICE_VARIANT. The old name does not exist in the API.

3. Variant updates dropped state, twice over

Each variant object is replaced, not merged. The recipe said to pass the entire array and include each existing id — both of which an agent can satisfy while rebuilding each variant from just its id plus the field it is changing. Everything else goes with it:

400 product is invalid: variantsInfo is invalid: variants [at index 0] is invalid:
    price must not be empty
    (REQUIRED_FIELD on product.variantsInfo.variants[0].price)

The error table made this harder to spot — it attributed the error to "new" variants, so an agent updating an existing one read it as not applying.

Variant choice names are opt-in on read. The recipe tells you to write optionChoiceNames, so agents expect to read them back. Get Product returns optionChoiceIds only, and populates names just when the request's fields includes "VARIANT_OPTION_CHOICE_NAMES". Matching on a name the response never carried raises nothing — it selects no variant. In a recorded run the agent spent two extra calls inspecting the product's options before resolving the choice GUID.

Coverage

Two scenarios, three assertions each with the path judge gating at 7, per this repo's eval-scenario guide:

• stores/find-products-under-price-catalog-v3
• stores/update-product-sku-full-variant — seeds a two-variant product so the agent must send both variants complete; a single-variant fixture let a run pass without exercising the rule at all.

What is and isn't proven

The price-filter change earned required on a decision assertion, path judge 9/10 against 2/10 on production.

The variant changes are supported but not certified. In a paired run where both arms read the recipe, production reproduced the choice-name defect and the PR arm did not — the change doing its job — but the PR arm still fell short of a clean path because of defect 2, which is why these are now in one PR rather than two. Earlier runs also confirmed defect 3's rejection appears without the fix.

These recipes carry more residual friction than any single change removes, so a scenario here can fail its path judge for a reason unrelated to the change under test. Each claim above is tied to a specific recorded run rather than to the verdict.