Feature: Recipe/BOM ingredient depletion pilot #769

Status

Planned, evidence-gated follow-on after supplies stock in #768. The completed product-ledger baseline is #280 / PR #775. This issue records a pilot boundary only; it does not authorize recipe or ingredient implementation.

Problem or motivation

A product-level sale can say that one burger was sold, but it cannot infer that a bun, patty, lettuce, and a configured amount of sauce were consumed. Merchants who need that behavior require explicit recipe/BOM components, units, yields, and lifecycle rules rather than a guess based on product stock.

Current behavior

FloCafe has completed product stock movements, but no ingredient catalog, base-unit conversion model, recipe versions, component snapshots, or automatic ingredient depletion. Add-on stock remains the separate sellable-modifier scope in #358; it is not recipe inventory.

Desired outcome

Pilot automatic depletion for only three to five high-volume menu products after merchants demonstrate that they can maintain representative recipes and reconcile physical counts. The pilot must be atomic, idempotent, auditable, offline-capable, and explicit about every order lifecycle transition.

Proposed technical approach

• Define versioned recipe/BOM headers and components linked to stock items from #768, with explicit base units, conversions, quantity, yield, portion, and rounding rules.
• Persist an immutable recipe/component snapshot or equivalent provenance on each consuming order item so later recipe edits cannot change historical restoration quantities.
• Choose and document one depletion trigger (order creation, kitchen send, or payment) before coding; preserve the existing product-stock timing unless a separate decision approves otherwise.
• Write component movements atomically with the order mutation, with stable references, actor attribution, and retry/concurrency protection.
• Define behavior for pending cancellation, progressed void, item restore, completed refund, insufficient component stock, and offline retry. Do not silently alter the current product cancellation/refund rules.
• Start with a small pilot and an explicit reconciliation/variance review before expanding beyond the initial products.

Alternatives considered

• Product stock alone cannot represent raw ingredients or portion quantities.
• A broad ERP/purchasing implementation is not necessary to validate recipe depletion and would create an unbounded migration and operational surface.
• Add-on stock in #358 addresses selectable extras such as “extra cheese,” not ingredients consumed by every recipe.

Area

Inventory / Products / Menu

Acceptance criteria

• Merchants provide three to five representative recipes, units, yields, variants, and a clear meaning of “after each sale.”
• Recipe versions and component quantities use explicit units/conversions and preserve an immutable sale-time snapshot.
• One approved depletion trigger and the cancellation/void/restore/refund policy are documented and tested.
• Component deduction and reversal are atomic, idempotent, actor-attributed, and safe for offline retries.
• Insufficient stock and rounding behavior are explicit and cannot silently produce invalid quantities.
• The pilot proves physical-count reconciliation before any broader rollout.

Explicit exclusions

No supplier accounts, purchasing, invoices, accounts payable, partial payments, multi-location transfers, demand forecasting, lot/expiry/serial tracking, production planning, valuation, broad theoretical-vs-actual variance, add-on stock implementation, or full ERP/accounting behavior.

Dependencies and sequencing

The delivered product ledger in #280 is the audit/atomicity precedent. This pilot is sequenced after manual supplies stock #768 and before receipt tender/change projection #770, but no implementation dependency is implied until the acceptance gate is met. Materials expense remains separate in #645, and the cash-drawer foundation is already delivered in PR #772.

Review request

@itsbkm, please review the pilot boundary and sequencing, share your thoughts on the evidence gate and lifecycle semantics, and let us know whether you are willing to take over or collaborate.

Additional context

The phrase “after each sale” is intentionally unresolved until merchant examples establish whether it means order creation, kitchen send, or payment. That decision must not be guessed in implementation.