# Restaurant order-state design sheet

Complete this with menu operations, POS engineering, product, restaurant staff, payments, and QA.

## 1. State model

Define each status and who may move the order.

| State | Meaning | Allowed writes | Exit condition | Caller language |
| --- | --- | --- | --- | --- |
| `empty` | No accepted item | Add item | First valid item |  |
| `proposed` | Caller stated choices; not fully validated | Add, update, remove | Catalog and policy checks pass |  |
| `validated` | Items, modifiers, location, price, and availability checked | Safe versioned correction | Complete readback begins |  |
| `confirmed` | Caller approved the final structured cart | Commit only | POS accepts or fails |  |
| `committed` | Durable POS order matches confirmed cart | Policy-controlled post-order change | Final acknowledgement |  |
| `handoff` | Human owns the next action | No automated write unless explicitly allowed | Human outcome recorded |  |
| `failed` | Safe completion is not possible | Recovery only | Caller receives approved fallback |  |

## 2. Line identity

- [ ] Every line item has a stable `line_id`.
- [ ] Duplicate products remain distinct.
- [ ] A changed item keeps provenance from its original line.
- [ ] References such as “the second one” resolve to exactly one line or trigger clarification.
- [ ] Item deletion never depends on product name alone.

## 3. Operation contract

List allowed operations.

| Operation | Required fields | Validation | Idempotency rule | Undo rule |
| --- | --- | --- | --- | --- |
| `ADD_ITEM` |  |  |  |  |
| `REMOVE_ITEM` |  |  |  |  |
| `SET_QUANTITY` |  |  |  |  |
| `SET_VARIATION` |  |  |  |  |
| `ADD_MODIFIER` |  |  |  |  |
| `REMOVE_MODIFIER` |  |  |  |  |
| `SET_FULFILLMENT` |  |  |  |  |
| `SET_LOCATION` |  |  |  |  |
| `UNDO_LAST_CHANGE` |  |  |  |  |

## 4. Catalog and menu validation

- [ ] Spoken items map to catalog IDs, not free-text POS items by default.
- [ ] Variation and modifier groups are validated against the selected item.
- [ ] Location, time, inventory, and channel availability are checked.
- [ ] Allergen statements use approved data and escalation rules.
- [ ] Price comes from an authoritative source.
- [ ] A location change revalidates every affected line.
- [ ] Unsupported requests never become invented products or modifiers.

## 5. Correction handling

- [ ] Mid-sentence self-corrections discard the abandoned proposal.
- [ ] Caller corrections create a new entity or cart version.
- [ ] Superseded values cannot reach later tool writes.
- [ ] Corrections during a POS request have a documented cancel, reconcile, or follow-up path.
- [ ] Corrections after commit follow restaurant and POS policy.
- [ ] The delivered audio prefix is stored for interrupted readbacks.

## 6. Confirmation

Define the readback order:

1. [ ] Item, variation, and quantity.
2. [ ] Modifiers and removals.
3. [ ] Fulfillment mode and location.
4. [ ] Price, tax, and fees from the authoritative source.
5. [ ] Allergens or special instructions under approved policy.
6. [ ] Explicit confirmation phrase.

- [ ] Readback is generated from structured state.
- [ ] The caller can correct any line before commit.
- [ ] The system requests fresh confirmation after a material change.

## 7. POS boundary

| Field | Voice state source | POS field | Conversion | Verification |
| --- | --- | --- | --- | --- |
| Location |  |  |  |  |
| Item |  |  |  |  |
| Variation |  |  |  |  |
| Modifier |  |  |  |  |
| Quantity |  |  |  |  |
| Fulfillment |  |  |  |  |
| Customer note |  |  |  |  |
| Price |  |  |  |  |

- [ ] Writes carry the current order version.
- [ ] Every intended mutation has an idempotency key.
- [ ] Timeout recovery checks whether the write committed before retry.
- [ ] The final POS order is read back and compared with the confirmed cart.
- [ ] Spoken success occurs only after durable verification.

## 8. Release evidence

- [ ] Deterministic operation tests pass.
- [ ] Duplicate-item reference tests pass.
- [ ] Tool timeout and stale-version tests pass.
- [ ] Text conversation tests pass.
- [ ] Audio correction and interruption tests pass.
- [ ] Restaurant staff reviewed final ticket readability.
- [ ] Every mismatch has an owner and safe handoff.