# AI-Ready Business Data Layer

Companion to **Why Your eCommerce Data Is Not Ready for AI Agents**.

This is the **cross-domain** data layer (orders, customers, products, inventory, returns, support, marketing). The SKU contract for search/recs/agents is [`ai-ready-catalog-contract.md`](ai-ready-catalog-contract.md) — do not duplicate it here.

An AI-ready business data layer is **not** a warehouse copilot and **not** unrestricted SQL.

## Domains and common breaks

| Domain | Agent needs | Typical break |
| ------ | ----------- | ------------- |
| **Orders** | Canonical order id, status, lines, payments (tokenized), `asOf` | Shopify id ≠ OMS id ≠ WMS id |
| **Customers** | Stable customer id, not email-as-key | Duplicate customers; guest vs account |
| **Products** | Parent/child, GTIN, required attrs | See catalog contract |
| **Inventory** | ATP on the **sellable** SKU | Nightly dump; location vs online mismatch |
| **Returns** | RMA id, reason, refund state, prior RMAs | Return not joined to original line |
| **Support** | Ticket id, order ref, policy version | Tickets without order id |
| **Marketing** | Campaign id, spend, attributed orders | Ads in a CSV; no join to SKU |

## Common problems (checklist)

- [ ] Different IDs across storefront / OMS / WMS / helpdesk
- [ ] Missing fields the first workflow requires
- [ ] Duplicate customers (email + phone + guest)
- [ ] Incomplete products (required attrs empty)
- [ ] Disconnected systems (no API, only UI)
- [ ] Delayed data (no `asOf`; cache older than SLA)

## Minimum viable layer for a first agent

Pick **one** workflow. Require:

1. Join key documented (example: `shopify_order_id` → `oms_order_id`)
2. Named **read** tools (not `SELECT *`)
3. `asOf` on inventory and price
4. PII columns **not** in the tool response unless the Identity role allows it

## Related

- Catalog slice: [`ai-ready-catalog-contract.md`](ai-ready-catalog-contract.md)
- Data agent tools: [`ai-data-agent-tool-catalog.md`](ai-data-agent-tool-catalog.md)
- Quality monitors: [`data-quality-monitor-rules.md`](data-quality-monitor-rules.md)