Module P (Pricing & Promotion) — Functional Decomposition

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

Governing thesis

P is the pricing observer in the Canary spine — the module that turns Counterpoint's raw price data into actionable pricing intelligence. Against the Counterpoint substrate, P's coverage gap is total: Counterpoint has no Pricing endpoint family and no Promotion API. There is no endpoint for promotion rules, no endpoint for markdown workflows, and no endpoint for elasticity signals. What Counterpoint does expose is the outcome of its internal pricing engine: multi-tier retail price fields on each item (IM_ITEM.PRC_1, REG_PRC, PREF_UNIT_PRC_1) and — critically — the per-line actual-price-charged on every sales ticket (PS_DOC_LIN_PRICE). That's the substrate.

The gap between "I can see what price was charged" and "I can model promotion rules, markdown cadence, and elasticity" is where Canary does its work. P.1 (multi-tier price derivation) reads the static tier structure. P.2 (promotion lifecycle) builds the promotion calendar Canary-native from transaction evidence — Counterpoint doesn't surface promotion rules to the API, so Canary infers promotional periods from discount-vs-list-price variance on PS_DOC_LIN_PRICE. P.3 (markdown management) is a Canary-native lifecycle built on top of P.1's price snapshots. P.4 (elasticity tracking) is the analytical layer that O.8 depends on for promotional-demand isolation.

This architecture has an important implication for J: J.8a's promotional-demand isolation requires that P's promotion calendar be populated. If P doesn't have promotion windows identified, J cannot isolate promotional lift from base demand. The P→J cross-cut is load-bearing, not advisory.

Executive summary

Posture: derived observer for the price-tier structure; Canary-native for promotion lifecycle, markdown management, and elasticity. The P.2 promotional-calendar build from transaction evidence (rather than from an explicit Counterpoint promotion API) is the most architecturally novel aspect of this module — it inverts the usual order of operations (normally you read rules and verify against transactions; here you infer rules from transaction evidence).

Counterpoint Endpoint Substrate

Canary Detection Hooks

P does not own detection rules — that is Q's surface. However, P is a first-class upstream signal supplier to several Q rule families and one J demand-isolation process. The hooks below document what P publishes and where it lands.

• P.2.6 (Undeclared promotions) → Q-DM-03: Undeclared promotional pricing events (price drop without a PS_PRC_GRP promotion record) are published as Q-DM-03 discount-manipulation signals to Chirp.
• P.4.1 (Elasticity signal) → O.1.4: P's elasticity coefficient for a SKU is published to O.1.4 as promotional-demand lift factor. This is a J dependency, not a Chirp signal — P does not directly write to Chirp.
• P.3 (Price-change audit) → Q-IS rule family: Bulk price changes (≥N items in a single session) are flagged as Q-IS accumulation signals, surfaced via Chirp's investigation queue.

L1 → L2 → L3 framework

L1 (Solution Map cell)         P = ◐ Derived
                                 │  (no Counterpoint Pricing or Promotion endpoints;
                                 │   price-tier structure read from IM_ITEM via S;
                                 │   promotion periods inferred from PS_DOC_LIN_PRICE via T;
                                 │   markdown + elasticity are Canary-native)
                                 │
L2 (Process areas)               ├── P.1  Multi-tier price derivation          ◐ Derived (from S)
                                 ├── P.2  Promotion lifecycle                   ★ Canary-native (inferred from T)
                                 ├── P.3  Markdown management                   ★ Canary-native
                                 ├── P.4  Elasticity tracking                   ★ Canary-native
                                 ├── P.5  Mass price maintenance + linked items ◐ Derived (cross-cut S)
                                 └── P.6  Cross-module substrate contracts
                                 │
L3 (Functional processes)       (33 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Canary-Retail-Brain/modules/P-pricing-promotion.md
                                  + canary-module-p-pricing-promotion.md (schema crosswalk)
                                  + future Canary/docs/sdds/v3/pricing-promotion.md

P.1 — Multi-tier price derivation

Coverage posture. ◐ Derived from S's item master. Counterpoint stores multiple retail price fields per item. Canary reads these from S's item publication and builds a price-tier model that maps each field to a tier name and customer eligibility.

Companion cards. canary-module-s-functional-decomposition.md (S publishes IM_ITEM including price fields), canary-module-m-functional-decomposition.md (M.5.5 price-tier assignment per commercial account — reads P.1's tier structure).

L3 processes

User stories

• As P's Price Reader, I want every item's price-tier matrix (retail / commercial / wholesale at current and cost) maintained as a rolling snapshot, with the delta between REG_PRC and PRC_1 surfaced as an active-markdown indicator.
• As a Garden-Center Buyer in Owl, I want to ask "show me all items where our wholesale price is less than 30% margin" and get a ranked list with cost, tier price, and item category — so margin compression on commercial accounts is visible before it becomes a problem.
• As P, I want price-tier changes detected and published as events within one S-poll cycle — a supplier cost increase that erodes our margin at wholesale tier should trigger a P.4 elasticity re-evaluation, not wait for a monthly price audit.
• As C's Price-Tier Assigner, I want P.1.5's tier mapping so that M.5.5 can surface the correct preferred-unit price to T's transaction validator without duplicating the derivation.

P.2 — Promotion lifecycle

Coverage posture. ★ Canary-native. Counterpoint has no promotion-rule endpoint. Canary infers promotion windows from the evidence left in transaction data: when PS_DOC_LIN_PRICE diverges from IM_ITEM.PRC_1 for a high proportion of transactions on a given item over a date window, Canary detects a likely promotional period. The buyer confirms or defines the promotion formally in Canary; the transaction evidence is the discovery surface, not the definition surface.

Companion cards. retail-promotion-workflow.md (promotion lifecycle — companion not lineage), canary-module-o-functional-decomposition.md (J.8a promotional-demand isolation reads P's promotion calendar — load-bearing contract), canary-module-q-functional-decomposition.md (Q-DM-01/02/03 read pricing decisions; Q-MM-01 reads bundle pricing).

L3 processes

User stories

• As P's Promotion Detector, I want transaction-price variance patterns to surface LIKELY-PROMOTION flags automatically, so the buyer doesn't have to build a promotion record retroactively — the discovery comes from the data, the confirmation comes from the buyer.
• As a Garden-Center Buyer running a spring perennials promotion, I want to define the promotion in Canary (period, items, discount type) and have it propagate to J's promotion calendar immediately, so J.8a is isolating the promotional lift from the base forecast during the promotion window.
• As J's Demand Forecaster, I want P's promotion calendar as a first-class input — if P.2.4's contract fails (calendar not published, promotion record missing), J.8a should flag an isolation gap, not silently contaminate the base forecast.
• As an LP Analyst (Q.6), I want undeclared-promotion detection (P.2.6) surfaced as a Q-DM audit event — a period where 40% of perennial transactions went out at 30% off with no promotion record is either a pricing error or an undocumented discount.
• As a Buyer reviewing last season, I want per-promotion performance: units, revenue, margin impact, and demand lift vs. baseline — so I can decide whether to run it again and at what discount depth.

P.3 — Markdown management

Coverage posture. ★ Canary-native. Counterpoint executes markdown pricing internally (buyer edits PRC_1 or REG_PRC in the Counterpoint UI); it has no markdown-lifecycle endpoint. Canary observes markdown execution via P.1.2's REG_PRC vs. PRC_1 gap, and builds the proposal→approval→execution→analytics lifecycle on top.

Companion cards. retail-merchandise-planning-otb.md (markdown as OTB-event; markdown execution affects planned sales and remaining OTB), canary-module-f-functional-decomposition.md (F posts GL markdown-variance entries that P tracks for cost-complement impact).

L3 processes

User stories

• As a Garden-Center Buyer preparing for end-of-season clearance, I want to submit a markdown proposal for all annuals above reorder-point at locations where the season ends in 3 weeks — Canary builds the proposed list, I review, approve, and execute in Counterpoint.
• As P's Markdown Tracker, I want markdown execution detected from the REG_PRC/PRC_1 delta within one S-poll cycle, linked to the pending proposal record — so markdown "executed in Counterpoint by the buyer" is captured automatically, not through manual Canary entry.
• As a Buyer, I want end-of-markdown performance: did the clearance move units faster than pre-markdown velocity, and at what margin? If the markdown didn't work, I need to know before committing to the same approach next season.
• As Finance, I want every markdown event linked to the Counterpoint price change and surfaced to F's GL posting pipeline — markdown execution is a GL event, not just a price change.

P.4 — Elasticity tracking

Coverage posture. ★ Canary-native. Counterpoint has no elasticity surface. Canary builds elasticity signals from the combination of P.3.5 (markdown performance vs. pre-markdown velocity) and P.2.5 (promotion lift vs. baseline). Elasticity is the analytical layer that connects P's pricing observations to J's demand forecast.

Companion cards. canary-module-o-functional-decomposition.md (O.1.4 demand forecast consumes P.4 elasticity; O.8.2 promotional-lift quarantine requires P.4 signals to attribute lift correctly).

L3 processes

User stories

• As P's Elasticity Engine, I want per-item price-elasticity coefficients calculated from markdown-period velocity vs. pre-markdown baseline, with a minimum-observations threshold before I call a coefficient reliable — no elasticity coefficient from a single markdown event.
• As a Buyer planning next spring's promotion strategy, I want to ask "which perennial categories are elastic enough that a 20% discount drives 40%+ volume increase?" — so I invest promotion budget in the elastic items, not the inelastic ones.
• As J's Demand Forecaster, I want P's elasticity signals to inform my promotional-demand projection — if perennials are elastic at 1.4x, O.8's pre-promotion demand projection should account for the expected lift, not just use the base forecast.

P.5 — Mass price maintenance + linked items

Coverage posture. ◐ Derived cross-cut with S. Mass price changes (supplier cost increase propagated across all items from that supplier, or category-level retail-price adjustment) are buyer-initiated in Counterpoint but affect P.1's price snapshots at scale. S's item-master pipeline is the substrate; P needs to handle bulk change events without treating them as individual markup alerts.

Companion cards. canary-module-s-functional-decomposition.md (S publishes bulk price-change events), canary-module-o-functional-decomposition.md (O.8.3 recurring-promotion blending benefits from P.5 linked-item awareness).

L3 processes

User stories

• As P's Bulk Change Detector, I want a single supplier cost passthrough that updates 200 items in Counterpoint recognized as a single bulk-change event — not 200 individual price-change events that flood the alert queue.
• As a Buyer, I want bulk price changes that erode commercial-tier margins below the configured floor (e.g., PRC_3 wholesale margin < 15%) flagged before they execute — so I can reprice the commercial tier before the next commercial-account transaction.
• As a buyer, I need Canary to detect when two active promotions apply to the same item and their combined discount exceeds the margin floor so that I can resolve the conflict before the transaction is processed.
• As a merchandising manager, I need to see when a buy-2-of-category-A-get-discount-on-category-B promotion produces unexpected cross-category margin erosion so I can adjust the promotion parameters.
• As a loss prevention analyst, I need Canary to detect when a buyer reverts a markdown in Counterpoint after it has already been applied to transactions so I can assess whether transactions occurred at the erroneous price.

P.6 — Cross-module substrate contracts

Purpose. P's most critical downstream contract is to J.8a — the promotional-demand isolation that prevents promotional lift from contaminating base forecasts. If P.6.3 fails, J's forecasts are wrong. The contracts below make this dependency explicit and testable.

J.8a dependency (load-bearing, reciprocal): P.6.3 promotion calendar contract is architecturally load-bearing to J demand forecasting (J.8a). P must publish promotion calendar records before J computes baseline demand. Failure of P.6.3 degrades J forecast accuracy.

User stories

• As J.8a's Demand Isolator, I want P.6.3 as a first-class dependency — if P's promotion calendar is empty for a period where Q-DM-03 (or P.2.6) detected an undeclared promotion, J.8a should halt isolation and surface a "calendar gap" warning rather than silently contaminating the base forecast.
• As Q's Detection Engine, I want P.6.2's active-markdown indicator as context for Q-DM-01 — a transaction where charged-price < list-price during an active markdown is expected; the same transaction outside a markdown window is a discount-audit event.
• As F's GL Engine, I want P.6.4 markdown-approval events to trigger the GL markdown-variance posting immediately on approval — not on the next price-change poll cycle.

Assumptions requiring real-customer validation

Highest-leverage gaps: ASSUMPTION-P-01 (PS_DOC_LIN_PRICE population) is the single most critical platform-knowable assumption — if this field is not reliably populated, P.2.1's LIKELY-PROMOTION detection collapses and P.4.1's elasticity calculation has no substrate. Sandbox-resolvable before Phase 1 adapter work begins. ASSUMPTION-P-02 (REG_PRC usage) is engagement-knowable at onboarding and determines whether P.3.1 markdown detection works out of the box or requires a fallback path.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
Multi-tier pricing in use: <yes (P.1.3 active) | no — flat pricing only>
REG_PRC usage: <consistent | inconsistent — P.3.1 fallback mode>
Promotion definition: <buyer-confirms LIKELY-PROMOTION (default) | buyer-creates-proactively | both>
Markdown approval required: <yes — buyer threshold $<N> | no — auto-execute>
Seasonal markdown template: <spring/end-of-season/holiday-weekend | custom per customer>
Bundle pricing in scope: <yes — P.5.3 active | no>
Elasticity minimum observations: <N markdowns before coefficient is reliable (default: 3)>
Undeclared-promotion detection: <enabled (default) | disabled>
Disabled P.x processes (with reason):
  P.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-P-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

Cast of actors:

P is an observer module with one bidirectional dependency. Counterpoint executes pricing; Canary observes. The one exception is the markdown proposal workflow (P.3.2) — the buyer drafts a markdown in Canary, but execution happens in Counterpoint UI (buyer sets PRC_1), and Canary detects the execution via P.3.1. This mirrors J's v2 buyer-mediated pattern (O.5.1) and carries the same assumption: buyers will tolerate "plan in Canary, execute in Counterpoint."

The J.8a dependency is load-bearing and must be surfaced as a Phase III contract test. J.8a's promotional-demand isolation fails silently if P's promotion calendar is incomplete. The "J forecast contaminated by undeclared promotion" failure mode is one of the hardest bugs to diagnose in a production system because the data looks plausible — it's just wrong. P.6.3 and P.6.7 exist to make this failure mode detectable. The corresponding contract test must confirm that J.8a halts isolation and surfaces a warning when the calendar is empty during a suspected promotion period.

Garden-center seasonal pricing reality is distinctive. L&G operators run 2-4 major markdown events per year (spring opening, Mother's Day weekend, fall clearance, holiday-weekend discount days). These are predictable enough that P.3.7 can build a seasonal calendar template, but their depth and timing vary enough by location and year that the template is a starting point, not a fixed schedule. Elasticity on live goods is also seasonally dependent — a 20% off perennial in week 3 of spring moves very differently than the same item in week 10.

Related

• Canary-Retail-Brain/modules/P-pricing-promotion.md — L1 canonical spec
• canary-module-p-pricing-promotion.md — L2 Canary code/schema crosswalk
• canary-module-o-functional-decomposition.md — sister card; J.8a (promotional-demand isolation) is P.6.3's primary consumer — load-bearing contract; O.1.4 and O.1.6 consume P.6.5 elasticity
• canary-module-q-functional-decomposition.md — sister card; Q-DM-01/02/03 consume P.6.2 (active markdown), P.6.3 (promotion calendar), P.6.7 (undeclared-promotion events); Q-MM-01 reads bundle pricing
• canary-module-s-functional-decomposition.md — sister card; P reads IM_ITEM price fields via S; P.5.1 bulk-change detection reads S event stream
• canary-module-f-functional-decomposition.md — sister card; F's GL posting pipeline receives P.6.4 markdown-approval events
• canary-module-m-functional-decomposition.md — sister card; M.5.5 price-tier assignment reads P.6.6 tier mapping; C's OTB co-ownership is invoked by P.3.3 markdown approval gate
• canary-module-t-functional-decomposition.md — sister card; T's transaction stream is P.2.1's LIKELY-PROMOTION substrate and P.4.1's elasticity calculation input
• retail-promotion-workflow.md — promotion lifecycle companion; companion not lineage
• retail-merchandise-planning-otb.md — OTB as markdown-event context for P.3.3 approval gate
• ncr-counterpoint-api-reference.md — IM_ITEM price field context; confirms no Pricing/Promotion endpoint family
• ncr-counterpoint-endpoint-spine-map.md — P-column placement (no dedicated endpoints; derived via S and T)
• garden-center-operating-reality.md — seasonal markdown cadence; live-goods elasticity; commercial-account pricing reality
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — P row = ◐ Derived; this card is the L2/L3 expansion of that cell