Module M (Merchandising) — Functional Decomposition

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

Governing thesis

M is the B2B intelligence layer of the Canary spine — the surface that distinguishes wholesale accounts, landscaper clients, and project-tier buyers from casual retail consumers. Against the Counterpoint substrate, M has no dedicated endpoint family of its own. Everything M knows about a commercial customer is derived from AR fields that Counterpoint already surfaces through the Customer and Customer_OpenItems endpoints: account category codes (AR_CUST.CATEG_COD), credit terms (AR_CUST.NO_CR_LIM, CR_RATE, BAL), multi-tier control flags (AR_CUST_CTL), and outstanding AR balances (Customer_OpenItems). M reads these from R's substrate publications and builds B2B classification on top of them.

The opportunity is real: at a garden center, 20-40% of gross revenue typically comes from commercial accounts (landscapers buying for projects, nurseries reselling wholesale, municipality contracts). These accounts operate on different credit terms, purchase at different price tiers, and carry different risk profiles than retail walk-in traffic. Counterpoint stores all of this — but doesn't surface it as a distinct B2B-intelligence layer. Canary does.

The derived-module shape is the load-bearing design constraint. M cannot fire without R (customer master) and F (AR ledger) being in place. This ordering is a build-sequence constraint, not just a data dependency: M is the Module 4 in the Canary v2 ring, behind R (Module 2) and F (Module 3). The L2 split below reflects this dependency chain explicitly.

Executive summary

Posture: first fully-derived module in this decomposition pass. M contributes no own Counterpoint polling; all substrate comes from R and F. The B2B classification and credit-posture L2s are Canary-native intelligence built on top of R's customer substrate and F's AR ledger. Garden-center vertical context — landscaper tiers, project-PO billing, municipality accounts — shapes every L2.

Counterpoint Endpoint Substrate

L1 → L2 → L3 framework

L1 (Solution Map cell)         M = ◐ Derived
                                 │  (no own Counterpoint endpoints;
                                 │   derived from R's AR_CUST/AR_CUST_CTL substrate
                                 │   + F's AR ledger + T's behavioral pattern)
                                 │
L2 (Process areas)               ├── M.1  B2B classification derivation    ★ Canary-native (from R)
                                 ├── M.2  Per-customer credit posture       ★ Canary-native (from R + F)
                                 ├── M.3  AR ledger surface                 ◐ Derived (cross-cut F.6)
                                 ├── M.4  B2B-specific detection rules      ★ Canary-native (cross-cut Q)
                                 └── M.5  Cross-module substrate contracts
                                 │
L3 (Functional processes)       (26 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Canary-Retail-Brain/modules/M-merchandising.md
                                  + canary-module-m-merchandising.md (schema crosswalk)
                                  + future Canary/docs/sdds/v2/commercial.md

M.1 — B2B classification derivation

Coverage posture. ★ Canary-native, built from R's substrate. Counterpoint stores account categorization in AR_CUST.CATEG_COD but does not differentiate B2B from retail algorithmically. Canary derives B2B classification from a combination of account-category codes, credit-terms configuration, and transaction behavioral pattern from T.

Companion cards. canary-module-c-functional-decomposition.md (M.2 tier identity, M.3 loyalty + AR — M inherits both), garden-center-operating-reality.md (landscaper / wholesale / project-tier vertical reality).

L3 processes

User stories

• As M's Classifier, I want every Counterpoint customer with non-default price-tier access (AR_CUST_CTL price-2/3 flags) identified as commercial-strong-signal, regardless of whether their CATEG_COD has been set — price-tier access is the most reliable B2B indicator in the substrate.
• As a Garden-Center Account Manager in Owl, I want to ask "show me all commercial accounts" and get a ranked list by B2B classification tier (landscaper / wholesale / project / uncertain), with the signals that drove the classification visible.
• As M's Classifier, I want CATEG_COD reclassifications propagated within one R-poll cycle — a landscaper who gets reclassified to wholesale should see their M.2 credit posture recalculated immediately.
• As an Operator, I want CLASSIFICATION-UNCERTAIN accounts flagged in the onboarding review queue — accounts with no category code, no credit terms, and below-threshold average order value need a human decision on B2B status.

M.2 — Per-customer credit posture

Coverage posture. ★ Canary-native, built from R's substrate and F's AR ledger. Counterpoint stores credit limit and balance in AR_CUST; Canary's contribution is building a credit posture signal — current utilization, aging pattern, payment-velocity — that Counterpoint doesn't surface as a risk score.

Companion cards. canary-module-c-functional-decomposition.md (M.3 loyalty + AR), canary-module-f-functional-decomposition.md (F.6 AR ledger — M.3 below is the cross-cut).

L3 processes

User stories

• As M's Credit Engine, I want per-account credit utilization recalculated after each payment recorded in Customer_OpenItems, so the CREDIT_POSTURE signal reflects real-time balance, not last-week's snapshot.
• As a Garden-Center Account Manager, I want to ask "which commercial accounts are past 60 days on their balance?" and get a ranked list with current balance, credit limit, and payment velocity — so I can prioritize outreach before accounts hit the formal collections threshold.
• As M, I want CREDIT_POSTURE:AT-LIMIT accounts to surface an alert to the account manager before the next transaction — Counterpoint doesn't prevent a new sale to an at-limit account; Canary should surface the warning.
• As an LP Analyst (Q.6), I want accounts with deteriorating credit posture (trending toward past-due) cross-referenced against recent high-value transactions — a landscaper maxing their credit right before going dark is a Q-relevant pattern.

M.3 — AR ledger surface (cross-cut with F.6)

Coverage posture. ◐ Derived — cross-cut with F's AR module. The AR ledger (open items, aging, payment history) is owned by F.6 from the finance side; M surfaces the same data through the account-management lens. This L2 is the contractual handshake between M and F — two modules reading the same substrate for different analytical purposes.

Companion cards. canary-module-f-functional-decomposition.md (F.6 AR ledger — this L2 is M's read of F's surface).

L3 processes

User stories

• As an Account Manager in Owl, I want a per-account AR summary (total outstanding, oldest item, aging buckets) visible alongside the customer's transaction history — not a separate AR module the operations team lives in.
• As M, I want F.6's AR ledger as my substrate for M.3 — I do not want to poll Customer_OpenItems independently. If F.6 polls it, I read from F.6's publication. One poller per endpoint.
• As M's Anomaly Detector, I want accounts whose payment velocity has slowed more than 20% vs. their 90-day baseline flagged as a M.4 Q-rule input — slow-pay trend is a leading indicator, not a lagging one.

M.4 — B2B-specific detection rules (cross-cut with Q)

Coverage posture. ★ Canary-native. B2B-specific detection rules are Canary-native — Counterpoint has no analytics over commercial accounts. These rules cross-cut Q's detection engine and are triggered by M's signals (credit posture, classification tier, AR pattern).

Companion cards. canary-module-q-functional-decomposition.md (Q-rule catalog — M-family rules cross-cut Q's detection framework).

L3 processes

Canary Detection Hooks

M.4 rules are cataloged in the Q rule catalog under the Q-M (Commercial / B2B) family. M derives the input signals; Q fires the alert via Chirp. These are account-management alerts, not LP fraud alerts — routed to the account manager surface in Owl rather than the LP queue.

See canary-module-q-counterpoint-rule-catalog.md §Commercial / B2B for substrate, logic, parameters, and allow-list for each rule.

User stories

• As Q's Detection Engine (M-rule family), I want M.4.1 B2B-CREDIT-01 to fire an alert to the account manager — not a fraud alert — when an at-limit commercial account attempts a new purchase. The operator decides whether to override the credit hold.
• As an Account Manager in Owl, I want M.4.2 (rapid credit-consumption spike) surfaced as a proactive alert before the account hits the formal past-due threshold — the signal should arrive when the account is still recoverable.
• As M's Rule Engine, I want B2B-TIER-01 (price-tier mismatch) to fire as a data-quality flag, not a fraud detection — it most likely means the account was set up incorrectly in Counterpoint, not that someone is gaming the system.
• As a store manager, I need to reclassify a customer from retail to wholesale tier during the spring landscape-contractor season so that their pricing reflects their current purchase volume.
• As an account manager, I need to approve a one-time credit-hold override for a trusted B2B account that is temporarily over-limit so that they can complete a critical end-of-season order.
• As a loss prevention analyst, I need to detect when a customer's current tier (WHOLESALE) conflicts with their historical transactions (RETAIL pricing) so I can flag potential retroactive pricing abuse.

M.5 — Cross-module substrate contracts

Purpose. M is a derived module — it depends on R and F for its substrate, and it promises classification signals to Q and the account-management surface. These contracts are the dependency chain that makes M safe to build after R and F are stable.

User stories

• As Q's Rule Engine, I want M's B2B_CLASS and CREDIT_POSTURE signals as inputs so M.4.x rules can fire without M re-deriving classification from scratch at rule-evaluation time.
• As J's Recommendation Engine, I want price-tier context for commercial accounts (M.5.5) so that wholesale-tier accounts don't get replenishment recommendations calibrated for retail-unit sale velocity.
• As an Account Manager, I want M.5.6 CLASSIFICATION-UNCERTAIN flagged accounts surfaced in a review queue at onboarding, so I'm not discovering mystery accounts when they first hit a credit alert.

Assumptions requiring real-customer validation

Highest-leverage gaps: ASSUMPTION-M-01 (CATEG_COD configuration) and ASSUMPTION-M-05 (AR module in use) are the two substrate-availability gaps that most affect M's classification fidelity. Both are engagement-knowable at customer onboarding — not platform-knowable from sandbox alone. ASSUMPTION-M-02 (AR_CUST_CTL price-tier as definitive B2B signal) is platform-knowable from sandbox inspection and should be resolved before Phase 1 adapter work begins.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
B2B tier taxonomy: <landscaper/wholesale/project-tier (default) | <customer-specific tiers>>
CATEG_COD to tier mapping: <standard mapping | customer-specific>
AR module in use: <yes | no — M.3 and M.2.3 empty>
Credit hold mode: <alert-only (default) | block-transaction>
B2B-CREDIT alert threshold: <AT-LIMIT (default) | >XX% utilization>
B2B-AR past-due threshold: <60 days (default) | <N> days>
Price-tier access signal: <AR_CUST_CTL (default) | customer-specific override>
Disabled M.x processes (with reason):
  M.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-M-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

Cast of actors:

M is a derived module — build sequence matters. M cannot function without R (customer master, AR fields) and F (AR ledger). The build sequence constraint is load-bearing: M is not an early-sprint candidate. It is the Module 4 in the v2 ring, behind R and F.

The B2B signal in Counterpoint is distributed, not concentrated. Unlike Square (which doesn't carry B2B metadata at all), Counterpoint carries useful signals across multiple fields — but none of them is a single "this is a commercial account" flag. M's value is the multi-signal derivation that turns CATEG_COD + price-tier + credit-terms + behavioral pattern into a clean classification. That synthesis doesn't exist in Counterpoint and is a genuine Canary contribution.

Garden-center vertical context is load-bearing for M. The landscaper / wholesale / project-tier taxonomy is not a generic retail construct — it's the specific commercial-account structure that garden centers operate with. Municipality contracts (parks departments, school districts), landscape contractors buying for large installation projects, and wholesale nursery accounts all have different risk profiles. M's classification must accommodate this without over-generalizing.

Related

• Canary-Retail-Brain/modules/M-merchandising.md — L1 canonical spec
• canary-module-m-merchandising.md — L2 Canary code/schema crosswalk
• canary-module-c-functional-decomposition.md — sister card; M inherits M.2 (tier identity) and M.3 (loyalty + AR); R is M's primary substrate dependency
• canary-module-f-functional-decomposition.md — sister card; M.3 reads from F.6's AR ledger; F is M's secondary substrate dependency
• canary-module-q-functional-decomposition.md — sister card; M.4 rules route to Q's detection pipeline; Q-rule catalog M-family
• canary-module-t-functional-decomposition.md — sister card; T's transaction stream is M.1.4's behavioral-pattern input and M.4.5's rule substrate
• ncr-counterpoint-api-reference.md — AR_CUST, AR_CUST_CTL, Customer_OpenItems field context
• ncr-counterpoint-endpoint-spine-map.md — M-column placement (no dedicated endpoints; derived from R's AR surface)
• garden-center-operating-reality.md — landscaper / wholesale / project-tier reality; municipality accounts; B2B revenue mix
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — M row = ◐ Derived; this card is the L2/L3 expansion of that cell