[Feature Request]: New Local Fulfillment official extension for *Search* and *Lookup* endpoints.

[nicolasgarnier]

Is your feature request related to a problem? Please describe.

Right now, the Search and Lookup endpoints (see PR #55) tell you what a product is, but not where you can actually get it (fulfillment information). For merchants with multiple physical stores, and especially for local pickup use-cases "in stock" is too vague. Users and agents need to know if a product is sitting on a shelf at a specific local branch so they can actually go pick it up.

Describe the solution you'd like

Currently this is possible using a custom extension that adds local fulfillment data to the Search and Lookup responses. Such as:

{
    "availability": {
      "available": true,
      "stores": [
        {
          "id": "store_sf_downtown",
          "name": "San Francisco - Downtown",
          "address": { ... },
          "pickup_available": true,
          ...
        },
        {
          "id": "store_palo_alto",
          "name": "Palo Alto",
          "address": { ... },
          },
          "pickup_available": false,
          ...
        }
      ]
    }
  }

The discussion here would be about wether we want an "official" common UCP extension for this, this would decrease fragmentation and enable better, more automated agentic experience.

Describe alternatives you've considered

We could leave it as is and force agents to parse a, non-standard inventory extensions.

Additional context

This is a follow-up to the discussion started in PR #55-3824223394. @igrigorik left some specific technical suggestions in that comments.

[poojithg14]

retail_location.json already exists for pickup destinations in the fulfillment flow, has id, name, and address. Worth reusing that shape here instead of defining a new store object, so there's one consistent representation of a physical location across the protocol.

The tricky part is where this lives. Right now, variant.availability is a flat object (an available boolean and a status string). Per-store availability is fundamentally per-variant, not per-product. Store A might have the blue one but not the red one. This should be set at the variant level, not at the product level.

Also, the search request already accepts location hints through context (address_country, address_region, postal_code) but the response doesn't do anything with them. Could those hints determine which stores appear in the response, for example, by returning only stores within a radius of the buyer's postal code?