Align v1 docs and OpenAPI around device identity, order flow, and inventory safety #2

Merged

caleb-brown merged 1 commit from codex/docs-review into dev

2026-03-08 12:00:28 -04:00

caleb-brown commented

2026-03-08 11:57:00 -04:00

Owner

Summary

This is a docs/contract alignment PR only. No application code changes are included.

The main goal is to make docs/v1/*, README.md, and openapi.yaml describe the same MVP.

What Changed

align the high-level README with the updated v1 docs
make device identity explicit with hidden actor_id plus display-name snapshots
clarify that Today is read-only and Orders is the mutation queue
document one-time stock deduction on brewing and optional refund-on-cancel
add waste and correction semantics to manual inventory adjustments
update openapi.yaml to match the v1 docs contract

Notable Contract Changes

new order identity fields: created_by_actor_id, claimed_by_actor_id
new order reconciliation fields: stock_deducted_at, stock_reconciled_at
new order metadata field: cancel_reason
inventory transaction enum now includes waste
inventory adjustment requests now distinguish relative amount from correction target_quantity
order cancellation documents optional refund_stock

Validation

git diff --check
npx --yes @redocly/cli lint openapi.yaml --skip-rule info-license
grep checks for stale nickname-only / barista-mode wording

Notes

These are breaking API-doc changes relative to the previous checked-in openapi.yaml.

## Summary This is a docs/contract alignment PR only. No application code changes are included. The main goal is to make `docs/v1/*`, `README.md`, and `openapi.yaml` describe the same MVP. ## What Changed - align the high-level README with the updated v1 docs - make device identity explicit with hidden `actor_id` plus display-name snapshots - clarify that `Today` is read-only and `Orders` is the mutation queue - document one-time stock deduction on `brewing` and optional refund-on-cancel - add `waste` and correction semantics to manual inventory adjustments - update `openapi.yaml` to match the v1 docs contract ## Notable Contract Changes - new order identity fields: `created_by_actor_id`, `claimed_by_actor_id` - new order reconciliation fields: `stock_deducted_at`, `stock_reconciled_at` - new order metadata field: `cancel_reason` - inventory transaction enum now includes `waste` - inventory adjustment requests now distinguish relative `amount` from correction `target_quantity` - order cancellation documents optional `refund_stock` ## Validation - `git diff --check` - `npx --yes @redocly/cli lint openapi.yaml --skip-rule info-license` - grep checks for stale nickname-only / barista-mode wording ## Notes These are breaking API-doc changes relative to the previous checked-in `openapi.yaml`.

caleb-brown added 1 commit

2026-03-08 11:57:00 -04:00