Home ›Brain ›Modules ›O Orders
2026-04-26

Module O (Orders) — Functional Decomposition

Artifact layer. Third of three Canary module artifact layers: 1. Canonical spec (vendor-neutral) — Canary-Retail-Brain/modules/O-orders.md 2. Code/schema crosswalk (Canary-specific) — Brain/wiki/canary-module-o-orders.md 3. Functional decomposition (Counterpoint-substrate-aware, L2/L3 + user stories) — this card

Governing thesis

J is the first partial-coverage cell we've decomposed — and the partial-ness is the point. Counterpoint exposes the order side cleanly (POs, PREQs, RECVRs, RTVs all flow through the Document omnibus via DOC_TYP) but exposes no forecast surface, no replenishment engine, and no OTB management at the API. Specialty retail buying as Canary defines it requires all three: an OTB pyramid that constrains commitment, a promotion-aware demand model, and a PO chain that ties planning to execution. The gap between the two is the J opportunity — Canary fills the plan side natively while reading the order side as substrate.

J is also the first module that writes back to Counterpoint in a non-trivial way. Q reads Counterpoint and produces detections inside Canary. T reads Counterpoint and publishes canonical events inside Canary. R reads Counterpoint and curates a privacy-bounded customer registry inside Canary. J's full lifecycle ends with a Counterpoint PO — meaning a Document with DOC_TYP=PO has to land in Counterpoint, either by buyer-entry-in-the-Counterpoint-UI (v2 default, low-coupling) or by Canary-POST /Document-back (v3+ option, higher-coupling, requires write-tier API key permissions).

For a Lawn & Garden tenant specifically, the J surface is shaped by three vertical realities: (1) vendor data quality is heterogeneous — large nurseries are EDI-capable, mid-tier growers are PDF/email, hobbyist suppliers are cash-and-paper; (2) item lifecycle is short and seasonal — replenishment forecasting on a stable SKU base is the wrong mental model; (3) promotional demand isolation is non-trivial — every spring-promotion lift must be quarantined from the next-year base forecast or replenishment double-orders.

Executive summary

Dimension Count Source
L2 process areas 8 This card
L3 functional processes 47 This card
Counterpoint endpoints in J's path 5 (Document POST/GET, VendorItem, Inventory_ByLocation, Items_ByLocation) API reference
Document types J type-routes 4 (PO, PREQ, RECVR, RTV) Document model + Workgroup numbering
Canary-native L2 areas (no Counterpoint coverage) 3 (O.1 forecasting, O.2 replenishment params, O.3 OTB) Solution Map gap
Counterpoint-substrate L2 areas 3 (O.5 PO generation, O.6 receiving, O.7 RTV) Document family
Cross-cutting L2 areas 2 (O.4 recommendation+approval, O.8 contracts) Bridges
Substrate contracts J owes downstream 11 This card §O.8
Assumptions requiring real-customer validation 14 Tagged ASSUMPTION-J-NN
User stories enumerated 68 Observer + actor mix; cast in §Operating notes

Posture: archetype-shaped against Counterpoint specifically, with explicit accommodation for the gap between canonical retail planning and Counterpoint's UI-only replenishment engine. The L2 split below makes the Canary-native vs Counterpoint-substrate distinction load-bearing — every L3 declares which side it's on.

L1 → L2 → L3 framework

L1 (Solution Map cell)         J = ◐ Partial
                                 │  (Counterpoint covers PO/PREQ/RECVR/RTV via Document;
                                 │   forecasting + replenishment params + OTB are gaps)
                                 │
L2 (Process areas)               ├── O.1  Demand forecasting        ★ Canary-native (gap)
                                 ├── O.2  Replenishment parameters  ★ Canary-native (gap)
                                 ├── O.3  Open-to-Buy management    ★ Canary-native (gap; cross-cut with P)
                                 ├── O.4  PO recommendation + approval  bridge (Canary plan → Counterpoint PO)
                                 ├── O.5  PO generation + transmission  ◐ Counterpoint-substrate (Document POST or buyer-UI)
                                 ├── O.6  Receiving + three-way match   ◐ Counterpoint-substrate (DOC_TYP=RECVR)
                                 ├── O.7  Short-ship + RTV handling     ◐ Counterpoint-substrate (DOC_TYP=RTV)
                                 └── O.8  Promotional-demand isolation + cross-module contracts
                                 │
L3 (Functional processes)       (47 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Canary-Retail-Brain/modules/O-orders.md
                                  + canary-module-o-orders.md (schema)
                                  + future Canary/docs/sdds/v2/forecast.md

O.1 — Demand forecasting

Coverage posture. ★ Canary-native (gap). Counterpoint exposes no forecast endpoint. Replenishment recommendations in Counterpoint are UI-only and rule-based, not statistically derived. Canary fills this end-to-end.

Companion cards. retail-merchandise-planning-otb (the planning pyramid Canary operates against), Canary-Retail-Brain/modules/O-orders.md (canonical spec), canary-module-o-orders.md (schema crosswalk).

L3 processes

ID L3 process Substrate read Notes
O.1.1 Read movement history per item per location T's Events.transactions + Events.transaction_lines (sales) + D's Events.transfers/receivers/RTVs (movements) over trailing 12-26 weeks Demand-derivation input data
O.1.2 Calculate demand velocity (units/day, units/week) per item per location Movement history aggregation Per-(item, location) velocity
O.1.3 Calculate demand variance (stable / variable / volatile classification) Movement history variance Drives safety-stock decision in O.2
O.1.4 Produce 13-week rolling forecast per item per location Velocity + variance + (later) seasonal model Stationary at v2; seasonal at v2.1
O.1.5 Hierarchy-volatility-aware forecasting S's category hierarchy + history-of-hierarchy-assignments Per retail-planning § "hierarchy reorganizations break historical comparability" — when a style moves categories mid-season, history must be restated
O.1.6 Like-item forecasting for new SKUs C's item attributes + S's category for like-item lookup New garden-center items mid-season have no history; use category-average velocity scaled by attributes. → TBD: L4 — like-item lookup algorithm: weighted average of comparables by category + velocity band; comparables selection criteria TBD per L4 spec.
O.1.7 Per-channel demand attribution T's transaction EC flag + Document EC indicators Online vs in-store demand split for omnichannel forecast
O.1.8 Forecast accuracy tracking (MAPE, bias) Prior forecasts vs actual sales Per forecast_results schema; feeds parameter retuning

User stories

O.2 — Replenishment parameter calculation

Coverage posture. ★ Canary-native (gap). Counterpoint allows manual ROP entry per item but does not calculate or maintain it from demand signal.

Companion cards. retail-po-from-plan (replenishment for NOS items), Canary-Retail-Brain/modules/O-orders.md (canonical spec), canary-module-o-orders.md (replenishment_params schema).

L3 processes

ID L3 process Inputs Notes
O.2.1 Calculate Reorder Point (ROP) per (item, location) velocity (O.1.2) × supplier lead time + safety stock (O.2.3) Initial value buyer-set; auto-recalculated after N months actual data
O.2.2 Calculate Economic Order Quantity (EOQ) per (item, location) EOQ formula + vendor-pack minimum + minimum-order-value Never below vendor pack minimum
O.2.3 Calculate Safety Stock per (item, location) Demand variance (O.1.3) + lead-time variance + service-level target Higher for volatile-demand items + variable-lead-time vendors
O.2.4 Maintain Weeks-of-Supply target per category Buyer-set per category Drives ROP and safety stock jointly per retail-planning §
O.2.5 Counter stock exclusion Per-store buyer-specified counter stock quantity Excluded from "available SOH" for replenishment calc — display fixtures, testers, seasonal displays
O.2.6 Lead-time variance modeling Supplier consistency tracking per vendor → v2.1 deferred: L4 — lead-time variance model (exponential smoothing with seasonal adjustment); fallback: rolling 13-week average lead time per vendor. See ASSUMPTION-J-04.
O.2.7 Pre-pack-aware EOQ Vendor pre-pack assortment definition Order quantities round to pre-pack multiples for branded-vendor items

User stories

O.3 — Open-to-Buy management

Coverage posture. ★ Canary-native (gap). Counterpoint has no OTB endpoint or budget structure at the API. OTB is a planning concept Canary brings to the Counterpoint substrate.

Companion cards. retail-merchandise-planning-otb (OTB definition + state changes + approval gates), cross-cuts with P (Pricing/Promotion).

Why J owns this and not P. OTB is the budget side of order recommendation. P maintains the seasonal plan and the budget definition; J is the consumer that validates every PO recommendation against remaining OTB headroom. This is the load-bearing cross-module contract between P and J.

L3 processes

ID L3 process Source Notes
O.3.1 Read OTB budget per (department, period) from P's seasonal plan P-derived Per retail-planning § "Seasonal Merchandise Plan (Department/Category)"
O.3.2 Calculate committed receipts per (department, period) Sum of PO line costs by receipt month Subtracts from OTB to compute remaining headroom
O.3.3 Compute remaining OTB headroom (rolling) OTB − committed receipts ± actuals adjustments The rolling operating forecast
O.3.4 OTB preview before PO commit O.4 — recommendation displays OTB impact before buyer commits Known failure mode in legacy systems: OTB consumed at save without preview, forcing the buyer to discover overcommit after the fact
O.3.5 OTB state-change events PO commit / cancel / sales-vs-plan delta / markdown execute All affect remaining OTB
O.3.6 OTB approval gate routing Buyer threshold → dept head → VP merch → finance Multi-tier escalation; per-role dollar threshold; finance involvement when vendor co-op funds in play
O.3.7 Locked-period override Once a plan period is locked, changes require override approval Audit-logged

User stories

O.4 — PO recommendation + approval workflow

Coverage posture. Bridge — Canary computes the recommendation (Canary-native), Counterpoint receives the resulting PO (substrate). The bridge is buyer-mediated at v2, optionally Canary-POST /Document-mediated at v3+.

Companion cards. retail-po-from-plan (PO generation chain), Canary-Retail-Brain/modules/O-orders.md (PO-recommendation workflow), canary-module-o-orders.md (po_recommendations schema).

L3 processes

ID L3 process Side Notes
O.4.1 Detect below-ROP items per scan Canary-native (O.2.1 + ledger SOH) Projected on-hand = SOH + on-order − expected sales over lead time
O.4.2 Generate PO recommendation per (supplier, receipt-week) bundle Canary-native Bundles same-supplier same-week items into one recommendation; respects EOQ from O.2.2
O.4.3 OTB headroom validation per recommendation O.3.4 Recommendation marked otb_validated=Y/N with available headroom inline
O.4.4 Recommendation prioritization Canary-native Below-ROP severity ordering (how-far-below-ROP, days-of-supply-remaining)
O.4.5 Buyer review + accept/modify/reject Canary-native UI / MCP / Owl Buyer adjusts quantity, supplier, receipt date inline; rejection captures reason
O.4.6 Multi-tier approval routing Canary-native (mirrors O.3.6) Buyer threshold → dept head → VP merch; approval state machine
O.4.7 Auto-commit threshold (per-tenant configurable) Canary-native Recommendations below $threshold optionally auto-commit; default off
O.4.8 What-if simulation Canary-native (planner role) Simulate "if I bump safety stock 20% on this category, what happens to next month's PO recs"

User stories

O.5 — PO generation + transmission

Coverage posture. ◐ Counterpoint-substrate. Once a recommendation is approved, it becomes a Counterpoint Document with DOC_TYP=PO. Two paths: buyer enters in Counterpoint UI (v2 default — Canary tracks the recommendation→entered transition by polling for new PO Documents) or Canary POST /Document (v3+ — requires write-tier API key + reconciliation between Canary recommendation_id and Counterpoint PO_NO).

Companion cards. ncr-counterpoint-document-model (POST /Document, Workgroup NXT_PO_NO), retail-po-from-plan (pre-distributed vs bulk PO patterns).

L3 processes

ID L3 process Path Notes
O.5.1 Buyer-entered-in-Counterpoint path (v2 default) Buyer takes recommendation to Counterpoint UI; enters PO; Canary detects new PO via T's poll loop Loose coupling; recommendation_id reconciled to PO_NO via heuristic match (supplier + items + window)
O.5.2 Canary-POST-Document path (v3+) Canary calls POST /Document with DOC_TYP=PO + lines + allocation; Counterpoint returns DOC_ID Tight coupling; reconciliation deterministic; requires write-tier API key
O.5.3 PO header generation Total cost, total retail, markup %, DC identifier, terms, cancellation date Per retail-planning § "Purchase Order Contents" — header section
O.5.4 PO line generation Cost/retail/margin per unit, cancellation date per line, allocation summary Per retail-planning § "Purchase Order Contents" — line section
O.5.5 Pre-distributed PO with allocation attached Allocation table set before vendor transmission; vendor packs by store; cross-dock at DC The pattern for branded vendors and cross-dock-capable suppliers
O.5.6 Bulk PO with allocation deferred PO total committed; allocation at DC receiving The pattern for warehouse-and-pick distribution; default for SMB
O.5.7 EDI transmission to vendor (External — outside Counterpoint API) Counterpoint API doesn't carry EDI; standalone EDI integration; out of v2 scope
O.5.8 New article creation at PO entry Buyer at trade show creates PO before article master exists Counterpoint workflow; Canary surfaces this through C's article-creation contract
O.5.9 PO change message on allocation revision Allocation change after PO transmission Triggers EDI PO-change to vendor when EDI in play

User stories

O.6 — Receiving + three-way match

Coverage posture. ◐ Counterpoint-substrate. Receivers flow as Documents with DOC_TYP=RECVR, automatically polled by T. Three-way match (PO + receipt + invoice) reconciles cost flow into F.

Companion cards. ncr-counterpoint-document-model (DOC_TYP=RECVR, Workgroup NXT_RECVR_NO), retail-po-from-plan (allocation-to-PO + short-ship), garden-center-operating-reality (thin-metadata receivers as normal, not anomalous).

L3 processes

ID L3 process Substrate Notes
O.6.1 Detect new receiver Documents T's poll loop (DOC_TYP=RECVR) Routes to J's receiving subscriber per T.4.7
O.6.2 Match receiver to PO via PS_DOC_HDR_ORIG_DOC T.7.2 (T's contract) If link present, deterministic match; if absent, heuristic match by vendor + items + window
O.6.3 Quantity reconciliation Receiver line qty vs PO line qty Discrepancy threshold flags Q-IS-01 (receiver-vs-PO discrepancy)
O.6.4 Cost reconciliation Receiver landed cost vs PO line cost Variance posts to F's GL adjustment
O.6.5 OTB closeout Receiver completes the PO's OTB consumption (in-progress → realized) Updates O.3.3 remaining headroom
O.6.6 Forecast accuracy feedback Actual receipt date vs requested date Feeds O.1.8 forecast-accuracy tracking + supplier-lead-time-variance tracking (O.2.6)
O.6.7 Thin-metadata receiver tolerance Garden-center reality: hand-typed receivers may have missing/default fields Flag-and-ingest, not reject — per garden-center wiki § "Receivers with thin metadata are normal"
O.6.8 Cash-paid receiver classification Receivers with PayCode=CASH Routes to ad-hoc-vendor-payment review queue per Q-IS-02 — NOT fraud queue

User stories

O.7 — Short-ship + RTV handling

Coverage posture. ◐ Counterpoint-substrate. Short-ship triggers re-allocation; RTV flows as DOC_TYP=RTV. Both feed back into O.3 (OTB headroom restoration) and O.1 (demand-forecast adjustment for items that didn't actually arrive).

Companion cards. retail-po-from-plan (short-ship + NOS replenishment), ncr-counterpoint-document-model (DOC_TYP=RTV, Workgroup NXT_RTV_NO).

L3 processes

ID L3 process Substrate Notes
O.7.1 Short-ship detection O.6.3 quantity reconciliation flags shortfall Triggers re-allocation flow
O.7.2 Re-allocation logic on short-ship Tier-aware: protect top-tier stores first; proportional remainder; bottom-tier may receive zero Default proportional reduction is wrong for SMB — implement tier-aware logic
O.7.3 PO change message for cancelled balance Standard back-order vs cancel decision Cancel remaining quantity per buyer instruction
O.7.4 RTV recommendation generation Damaged goods, vendor-quality issues, return-to-vendor Buyer-initiated; substrate flows as DOC_TYP=RTV
O.7.5 RTV impact on OTB Restores OTB headroom for the affected receipt period O.3.5 OTB state-change
O.7.6 RTV reason-code tracking Per RTV reason; aggregates to vendor-quality signal Feeds Q-IS-* (vendor-quality patterns) and supplier scorecard
O.7.7 Dead-count / live-goods write-off (garden-center-specific) Likely DOC_TYP=RTV with reason code OR separate adjustment workflow (ASSUMPTION-J-12) Counterpoint convention undocumented; tracked against seasonal baseline per Q-IS-04

User stories

O.8 — Promotional-demand isolation + cross-module substrate contracts

Purpose. Two distinct concerns share this L2 because both are cross-module: (1) promotional demand isolation (cross-cut with P), and (2) the substrate contract registry to D/F/P/T.

J.8a — Promotional-demand isolation (cross-cut with P)

Companion cards. retail-promotion-workflow (promotion + replenishment integration).

ID L3 process Substrate Notes
O.8.1 Read promotion calendar from P P's promotions table Replenishment must know about active + planned promotions on each item
O.8.2 Quarantine promotional lift from base demand Tag transactions with promotion ID at parse; J reads tagged-vs-untagged separately Promotional lift must never inflate the base forecast used for next-cycle replenishment
O.8.3 Recurring-promotion blending Per-item config: "include in base" vs "smooth out of base" Same week every year → include; one-time → smooth
O.8.4 Pre-promotion demand projection Add planned promotional demand to forecast horizon Avoids replenishment double-ordering during promo windows

J.8b — Substrate contract registry (symmetric to T.7, C.6, Q.1)

ID Contract Owner downstream What J promises
O.8.5 PO recommendations as event substrate F (formal PO commitment), Q (recommendation-vs-actual auditing) Every recommendation persisted with snapshot inputs; not regenerated on parameter change
O.8.6 Forecast snapshot per recommendation Future audit / compliance Forecast version + parameters used at recommendation time
O.8.7 OTB validation outcome inline F (commit gating), Buyer review Recommendation carries otb_validated boolean + available_headroom inline
O.8.8 Per-recommendation buyer modifications captured Audit trail Original recommendation + buyer modifications + final approved PO all linked
O.8.9 Receiver→PO match status F (three-way match), Q (Q-IS-01) Match outcome (deterministic / heuristic / unmatched) preserved per receiver event
O.8.10 Lead-time-variance per supplier O.2.6 self-feedback + supplier scorecard Aggregated across receivers; updated per receipt event
O.8.11 Demand-forecast snapshot for accuracy tracking O.1.8 self-feedback Per (item, location, period) forecast-vs-actual preserved indefinitely

Cross-module dependency notes (load-bearing):

User stories

Assumptions requiring real-customer validation

ID Assumption What it blocks Resolution path
ASSUMPTION-J-01 PO Document type code — likely PO; Workgroup numbering confirms NXT_PO_NO O.5 entire substrate path; T-01 dependency Sandbox or sample PO Document inspection
ASSUMPTION-J-02 PREQ vs PO distinction — purchase request workflow O.4 approval routing (does PREQ exist as a Counterpoint state, or is it Canary-internal-only) Sandbox workflow test
ASSUMPTION-J-03 RECVR Document linkage to PO via PS_DOC_HDR_ORIG_DOC — assumed but unconfirmed O.6.2 deterministic match Sandbox workflow test
ASSUMPTION-J-04 RTV Document reason-code field — schema location O.7.6 reason tracking; Q-IS feedback Sandbox DB inspection
ASSUMPTION-J-05 Vendor master via VendorItem — single endpoint; full vendor record may live in AP_VEND (not exposed?) J vendor-data completeness; supplier-scorecard fidelity API doc deep-read; possibly direct-DB fallback
ASSUMPTION-J-06 OTB representation in Counterpoint — believed UI-only / spreadsheet-only O.3 entire L2 (Canary-native confirmed) Customer interview; if customer maintains OTB in Counterpoint custom tables, path differs
ASSUMPTION-J-07 Per-customer category margin targets (MIN_PFT_PCT, TRGT_PFT_PCT) actually tuned, or default values O.1 like-item forecasting needs realistic margin context Tenant onboarding
ASSUMPTION-J-08 Buyer-driven PO entry workflow at v2 — does buyer copy from Canary or rekey O.5.1 v2 path UX assumption Real customer workflow observation
ASSUMPTION-J-09 Write-tier API key feasibility for v3 POST /Document path O.5.2 entire path NCR partner / customer permission negotiation
ASSUMPTION-J-10 Pre-pack vendor coverage in L&G vertical — branded vendors common, but unclear if dominant O.5.5 pre-distributed PO L3 priority Customer interview
ASSUMPTION-J-11 EDI transmission scope — most L&G customers do NOT have EDI; manual phone/email/fax O.5.7 likely deferred indefinitely for SMB L&G Customer interview
ASSUMPTION-J-12 Dead-count / live-goods write-off Document type — RTV with reason, separate adjustment workflow, or other (same as ASSUMPTION-Q-05) O.7.7 entire substrate path; Q-IS-04 Real garden-center customer DB
ASSUMPTION-J-13 Promotion calendar in Counterpoint vs Canary — Counterpoint has no promotion endpoint family per api-reference O.8.1 read-from-P assumes P maintains the calendar Canary-side Confirms Canary-native P; no Counterpoint conflict
ASSUMPTION-J-14 Supplier lead time field on item or vendor — schema location O.2.1 ROP calculation Sandbox DB inspection

Highest-leverage gaps: J-06 (OTB representation) and J-08 (buyer workflow at v2). J-06 is the load-bearing assumption for the entire O.3 L2; if a customer maintains OTB in Counterpoint custom tables (Rapid POS proprietary extension), Canary's O.3 path changes from "build OTB from scratch" to "ingest customer's existing OTB." J-08 is the load-bearing UX assumption for v2; if buyers won't tolerate copy-from-Canary-then-enter-in-Counterpoint, v3 POST /Document becomes urgent rather than optional.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
PO entry path: <buyer-via-Counterpoint-UI | Canary POST_Document | hybrid>
Write-tier API key: <granted | denied | not-yet-requested>
OTB management: <Canary-native | Counterpoint custom tables | spreadsheet-side>
EDI in play: <yes — vendor list | no>
Pre-pack vendor coverage: <% of $ / % of vendors>
Per-tenant auto-commit threshold: <$X | disabled (default)>
Demand-forecast cadence: <daily | weekly | manual-only>
Promotional-isolation per category:
  <category>: <include in base | smooth out>
Disabled J.x processes (with reason):
  J.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-J-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

Cast of actors (J is more populated than Q/T/R):

Actor Role Lives where
Forecast Engine Demand projection service Canary-internal (O.1)
ROP Calculator Replenishment parameter service Canary-internal (O.2)
OTB Validator Headroom-check service Canary-internal (O.3)
PO Recommender Recommendation generator Canary-internal (O.4)
Buyer / Merchandiser Human-in-the-loop, approves recommendations Customer org
Department Head / VP Merch Multi-tier approval Customer org
Receiver subscriber Three-way-match service at goods-in Canary-internal (O.6)
Owl / Fox Analyst-facing surface Canary-internal (O.4 + O.6 surfaces)
Counterpoint Document writer Optional POST /Document writer at v3+ Canary-internal (O.5.2)

The partial-coverage cell drives the L2 split. J's L2 explicitly tags Canary-native vs Counterpoint-substrate vs bridge for each area. This pattern should generalize to any other ◐ Partial cells (P-derived, A-derived, C-derived) — the format earns its keep precisely because gap-shaped modules need this distinction load-bearing.

The OTB / PO / promotion process trio gives plan-shaped modules a stable L2 backbone. The pyramid, chain, and lifecycle aren't aspirational — they're the operating shape Canary commits to. Future module cards (P, S in particular) reference the same three companion cards because the patterns are shared, not because the source is.

The buyer-mediated v2 path is the load-bearing UX assumption. Until a real customer can confirm buyers will tolerate "review recommendation in Canary, then enter PO in Counterpoint," J's actual deployment shape is uncertain. If they won't, v3 POST /Document becomes the v2 default. This is the single highest-priority discovery question for any first L&G customer.

Canary Retail Brain · GrowDirect LLC canary@growdirect.io