feat(schema): add inventory signals to variant availability

[hemanth]

Right now, variant availability is a boolean plus an enum. You know if something is available, and roughly what state it is in (in_stock, backorder, etc). But that is about it.

For agents doing the talking -- especially voice agents where you can not show a grid of alternatives -- "available" vs "unavailable" is not enough. "Only 2 left" changes buying behavior. "Back in stock next Tuesday" changes whether the buyer waits or goes elsewhere.

This PR extends the existing availability object on variants with optional inventory fields. Nothing breaks, nothing is required, businesses that do not track inventory just skip the new fields.

Closes #345

What changed

One file: source/schemas/shopping/types/variant.json

The availability object gets four new optional properties:

• quantity (integer) -- current stock count. Some businesses will share this, others will not. Both are fine.
• low_stock_threshold (integer) -- the business defines what "low stock" means to them. Platforms can use this to show "almost gone" or similar messaging.
• restock_at (date-time) -- estimated restock date for out-of-stock or backordered items. Useful for "check back on Tuesday" type conversations.
• locations (array) -- per-location availability for multi-location businesses. Each location has an id, name, available flag, optional quantity, and status.

The existing available boolean and status enum are untouched.

What it looks like

{
  "id": "variant_mug_blue",
  "title": "Ceramic Mug - Blue",
  "availability": {
    "available": true,
    "status": "in_stock",
    "quantity": 4,
    "low_stock_threshold": 5,
    "restock_at": "2026-05-10T00:00:00Z",
    "locations": [
      { "id": "loc_downtown", "name": "Downtown", "available": true, "quantity": 3 },
      { "id": "loc_online", "name": "Online", "available": true, "quantity": 1 }
    ]
  }
}

A business that does not track inventory still returns what they always returned:

{
  "availability": {
    "available": true,
    "status": "in_stock"
  }
}

No change needed on their side.

Why this matters for agents

A voice agent can not show a product grid. The conversation is linear, so the agent needs to make good recommendations with the information it has. Knowing stock levels lets it say things like:

• "That is running low -- want me to grab one before it is gone?"
• "It is out of stock online but the downtown store has 3 left."
• "They expect more on May 10th. Want me to check back then?"

Without these signals, the agent is stuck with "it is available" or "it is not available." That is a worse experience for the buyer.

[BuyWhere]

This is a great addition. From building BuyWhere (a product search API across SEA marketplaces), we found that inventory signals are one of the most critical data points for AI agents making purchase decisions.

A few data points from our experience:

• “Low stock” warnings change agent recommendations ~40% of the time when alternatives exist
• Restock ETA is the build(deps): bump uv from 0.2.23 to 0.9.6 #1 most-requested field from our agent developer users (after price)
• Marketplace-specific inventory semantics vary wildly — “available” means different things on Shopee vs Lazada

One thing worth considering: should the spec include a “lock” mechanism for cart-level inventory? Some marketplaces reserve inventory for minutes after add-to-cart, which is important for agents doing multi-step checkout flows.