Module C (Customer) — Functional Decomposition

Artifact layer. Third of three Canary module artifact layers: 1. Canonical spec (vendor-neutral) — Canary-Retail-Brain/modules/C-customer.md 2. Code/schema crosswalk (Canary-specific) — Brain/wiki/canary-module-c-customer.md (planned for Q/T/R; exists for J/P/F/C) 3. Functional decomposition (Counterpoint-substrate-aware, L2/L3 + user stories) — this card

Governing thesis

R owns the People entity in CRDM, specifically the customer subset. Counterpoint exposes the richest People surface of any spine module — 17 endpoints covering AR_CUST + addresses + notes + cards + open AR + control + workgroup-driven defaults — and adds two capabilities Square has no equivalent for: multi-tier pricing identity (AR_CUST.CATEG_COD) and embedded loyalty (12 LOY_* fields per customer). For a Lawn & Garden tenant specifically, the multi-tier identity is the load-bearing feature: every Q rule that distinguishes wholesale from retail behavior depends on R, every P-derived pricing observation depends on R, every C-derived B2B classification depends on R.

R holds a deliberate inversion of the dominant industry default: the Canary v1 spec stores no PII at rest. Counterpoint, by contrast, holds full PII (name, email, phone, address, card-on-file, AR ledger, loyalty history). R's Counterpoint posture must reconcile these two: the Canary-side privacy commitment AND the Counterpoint-side full customer record. The reconciliation is read-through-to-Counterpoint at query time, not "ingest everything Counterpoint knows."

R is ● Full direct in every Counterpoint Solution Map cell, but the cell hides three real architectural decisions: (1) multi-company-per-tenant customer namespace handling, (2) the privacy-posture reconciliation just described, and (3) tier-code conventions that vary per-VAR and per-customer (every Counterpoint deployment uses CATEG_COD differently — there is no universal taxonomy).

Counterpoint Endpoint Substrate

Executive summary

Posture: archetype-shaped against Counterpoint specifically. The privacy-first v1 design (no PII at rest) is preserved. Per-VAR tier-code variance is acknowledged as a discovery surface at every customer onboarding — there is no universal CATEG_COD mapping.

L1 → L2 → L3 framework

L1 (Solution Map cell)         R = ● Full direct (Counterpoint Customer family — 17 endpoints)
                                 │
L2 (Process areas)               ├── C.1  Customer registry & upsert
                                 ├── C.2  Tier identity & multi-tier pricing context
                                 ├── C.3  Loyalty + AR ledger surfacing
                                 ├── C.4  Privacy posture (no PII at rest)
                                 ├── C.5  Identity resolution (cross-company, future cross-vendor)
                                 └── C.6  Investigator surface + downstream contracts
                                 │
L3 (Functional processes)       (32 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Lives in SDDs + module specs
                                  (Canary-Retail-Brain/modules/C-customer.md,
                                   docs/sdds/canary/ncr-counterpoint-retail-spine-integration.md §6.2)

C.1 — Customer registry & upsert

Purpose. Maintain one row per merchant per Counterpoint customer (per company alias, for multi-company tenants). T's parsed transaction stream triggers shell-row upserts before R has polled the Customer endpoint; R catches up async. The registry is the FK target every other module depends on for People references.

L3 processes

User stories

• As R, I want T's CUST_NO references to immediately upsert a shell row so transaction events never reference unknown customers, even if the Customer endpoint hasn't been polled yet.
• As R, I want the GET /Customers incremental poll to respect a per-(tenant, company_alias) watermark so I never re-fetch already-consumed customers and never miss a customer modified during my last cycle.
• As an Operator in Owl, I want to ask "which customer references are still in shell-row state for tenant X" and get an enrichment-lag report so stale references surface before they break downstream queries.
• As an Operator at a multi-company tenant, I want CUST_NO=12345 in companyA and CUST_NO=12345 in companyB to be unambiguously different customers in R, with the company alias preserved in every join key.

C.2 — Tier identity & multi-tier pricing context

Purpose. This is the load-bearing L&G capability. Counterpoint's AR_CUST.CATEG_COD is the multi-tier pricing identity field; for a garden-center tenant, the typical taxonomy is RETAIL / MEMBER / LANDSCAPER / PROJECT / WHOLESALE. Q.2.9 (customer-tier abuse), Q.6.x vertical-pack tier-aware allow-lists, and P-derived multi-tier pricing observations all depend on R surfacing the tier cleanly.

No universal taxonomy. Every Counterpoint deployment uses CATEG_COD differently. Per-VAR conventions vary; per-customer conventions vary within a VAR. This L2 surfaces the field; tier-meaning interpretation is a per-tenant configuration that gets captured at onboarding (see ASSUMPTION-R-03).

L3 processes

User stories

• As Q.2.9, I want every customer's tier code (CATEG_COD) and its tenant-specific meaning available on every transaction join, so the wholesale-on-retail-pattern rule fires correctly across tenants with different code conventions.
• As Q.2.9, I want tier-change events on a customer record exposed as their own substrate (C.2.3) so the pre-purchase tier-upgrade rule can correlate against transaction timestamps.
• As an LP Analyst at a garden center, I want to see the per-customer history "RET → LSC → WHL" with audit timestamps when investigating a tier-abuse case, so legitimate sales-rep promotions are visible.
• As an Operator onboarding a Counterpoint tenant in Owl, I want to declare the tier-code → tier-meaning mapping interactively, with auto-suggested mappings inferred from the customer's existing AR_CUST data.
• As C (the derived B2B module), I want the union of AR_CUST.CATEG_COD ∈ wholesale-tier-set plus AR_CUST.NO_CR_LIM > 0 plus OpenItems non-empty to identify B2B customers without reaching into Counterpoint twice.

C.3 — Loyalty + AR ledger surfacing

Purpose. Counterpoint embeds 12 loyalty fields per customer (LOY_PGM_COD, LOY_PTS_BAL, LOY_CARD_NO, etc.) plus a full AR ledger via Customer_OpenItems. R surfaces both as substrate without persisting PII; loyalty + AR shape feeds C.6 contracts to downstream modules (Q for velocity rules, F for AR-vs-tender reconciliation, future C for B2B account behavior).

L3 processes

User stories

• As R, I want loyalty enrollment and balance surfaced as integer-shape substrate so downstream rules can pattern-match without R ever persisting PII.
• As Q, I want loyalty redemption events available alongside transaction events so redemption-pattern rules (over-redemption per session, redemption-then-refund pattern) can fire.
• As F, I want per-customer open AR aging (current / 30 / 60 / 90+) available without joining back to Counterpoint, so AR collection workflows can run from CRDM.
• As an LP Analyst at a garden center, I want loyalty redemption activity per cashier per session visible — loyalty-redemption-then-refund is a known fraud pattern in retail.

C.4 — Privacy posture (no PII at rest)

Purpose. R is the most architecturally opinionated module: the v1 implementation deliberately stores no PII at rest. Names, emails, phone numbers, addresses are intentionally not in R's tables. Counterpoint holds them; Canary reads at query time when the workflow demands it. This L2 owns that posture and the schema enforcement that makes it structural, not procedural.

Why this matters for Counterpoint. Square's customer surface is lighter. Counterpoint's AR_CUST carries deep PII (name, email, phone, multiple ship-to addresses, card-on-file, AR ledger, loyalty history). The naive integration would ingest all of it. R deliberately doesn't.

L3 processes

User stories

• As Canary's Compliance Story, I want the schema itself to enforce no-PII-at-rest in R, so a future engineer cannot accidentally introduce a name column without an explicit migration that triggers compliance review.
• As R, I want every read-through to Counterpoint to be request-scoped and never cached — the query returns the data, the data evaporates from Canary.
• As an LP Analyst investigating a case in Fox, I want customer name + contact info displayed in the case view by reading-through to Counterpoint at click time, with the read audit-logged so privacy review can prove no bulk extraction.
• As Canary's Product Owner, I want a profile-extension opt-in path that explicitly requires a data-handling agreement, so customers who genuinely need first-party PII storage have a path that's not ad-hoc.
• As an Auditor, I want to confirm that a full database exfiltration of R yields only opaque IDs and integer aggregates — re-identification requires also breaching Counterpoint.

C.5 — Identity resolution (cross-company, future cross-vendor)

Purpose. A single Canary tenant may run multiple Counterpoint companies (multi-company-per-tenant is real) and may eventually run Square-in-store + Counterpoint-online (cross-vendor). Today: per-(tenant, company_alias) namespaces are independent. v2: explicit identity resolution surface for cross-namespace customers.

L3 processes

User stories

• As R, I want cross-company customer references treated as independent until an Operator explicitly links them, so multi-company tenants don't get accidental customer merges from same CUST_NO collision.
• As an Operator at a multi-company garden-center chain in Owl, I want to manually link two Counterpoint customer records (e.g., a landscaper who shops at both armstrong-glendora and armstrong-irvine companies) with one MCP call, audit-logged.
• As Canary's Product Owner, I want cross-vendor identity resolution explicitly punted to v2 with a documented matching-policy decision required before build — getting this wrong silently merges different customers and has GDPR consequences.

C.6 — Investigator surface + downstream contracts

Purpose. R outputs feed two surfaces: (1) read-only customer queries from Owl/Fox/Operator MCP tools, and (2) substrate contracts to downstream modules. This L2 is symmetric to T.7 — same producer-view-of-contracts pattern.

L3 processes (investigator surface)

L3 contracts (substrate registry — symmetric to T.7)

User stories

• As an LP Analyst in Fox, I want to look up a customer by CUST_NO and see their tier, LTV, transaction count, AR balance, and loyalty status — without needing PII to investigate a case.
• As an LP Analyst, I want to click through to "show contact info" only when I need to actually contact the customer, with the read audit-logged for compliance review.
• As Q (Q.6.x vertical pack), I want to assert at boot that R surfaces tier code, tier-meaning mapping, AR aging, and tax-exempt flag for the active tenant — failing fast if the substrate contract is broken.
• As a Store GM in Owl, I want to ask "show me wholesale customers I haven't seen in 60 days" and get a per-customer drilldown without leaving the conversation.
• As Marketing (deferred v3), I want cohort projections by tier × LTV available as a queryable surface — but only when the profile-extension opt-in (C.4.6) is enabled and the data-handling agreement is in place.

Canary Detection Hooks

Additional User Stories

• As a loss prevention analyst, I need to detect when the same customer appears under two different company IDs with matching contact information so I can investigate potential account manipulation.
• As a store manager, I need customer profile extensions (loyalty tier, spend band) to be available in Canary reporting even before v3 enrichment, so I can filter investigation queues by customer segment.

Assumptions requiring real-customer validation

These markers exist because the answer requires either a Rapid Garden POS sandbox database, a real customer's AR_CUST corpus, or both.

Highest-leverage gaps: R-03 (tier-code conventions) — load-bearing for every L&G-distinctive Q rule. Cannot be assumed at platform level; must be discovered per-tenant. Capture as part of CATz Phase II To-Be Workshop output.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
Counterpoint deployment: <single-company | multi-company (N companies)>
Company aliases: [<alias1>, <alias2>, ...]
Tier-code mapping (C.2.2):
  CATEG_COD value | meaning
  ---             | ---
  WHL             | wholesale
  LSC             | landscaper
  MBR             | member
  RET             | retail
  PRJ             | project (one-time landscape)
  ...
Loyalty program in use: <yes — program name | no>
Loyalty enrollment field convention: <which LOY_* field>
AR ledger active: <yes | no>
Tax-exempt convention: <field name + value convention>
Profile-extension opt-in: <off — default | on — DPA reference>
Disabled R.x processes (with reason):
  R.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-R-NN: resolved as <answer>; source: <evidence>
  ...
Manual identity links (C.5.3):
  <link entry list>

Operating notes

• R inherits T.7.7 (T's customer-reference upsert contract) — every transaction reference upserts a shell row in R before the transaction event publishes. R's C.1.1 is the receiver of T.7.7. The two contracts must stay symmetric; drift between them silently breaks downstream joins.
• R is the substrate provider for two derived modules (P-derived multi-tier pricing, C-derived B2B classification) per the Solution Map. The L3 processes in C.2 and C.3 are explicitly designed to surface fields those derivations need.
• The privacy-first posture (C.4) is a deliberate inversion of the dominant industry default. It is a marketable property of the platform, not just a technical choice. Customers who genuinely need first-party PII opt in via C.4.6 with a documented data-handling agreement; default is off.
• Tier-code conventions (ASSUMPTION-R-03) are load-bearing AND not platform-knowable. Every customer engagement needs explicit tier-mapping discovery during CATz Phase II To-Be Workshops. This is a methodology hook as much as an engineering one.

Related

• Canary-Retail-Brain/modules/C-customer.md — module-level architectural spec (CRDM, BSTs, schema, agent surface, security posture); referenced throughout
• canary-module-q-functional-decomposition.md — sister card; C.6.7-C.6.12 contracts are consumed by Q.1 + Q.2.9 + Q.6
• canary-module-t-functional-decomposition.md — sister card; T.7.7 (customer-ref upsert) is the producer-side of C.1.1
• ncr-counterpoint-api-reference.md — full Customer family (17 endpoints) detail; CustomerControl semantics; cached-data discipline
• ncr-counterpoint-endpoint-spine-map.md — per-endpoint × CRDM × spine map for Customer family
• ncr-counterpoint-rapid-pos-relationship.md — feature-to-API mapping (multi-tier pricing → CATEG_COD; loyalty → 12 LOY_* fields); referenced in C.2 and C.3
• garden-center-operating-reality.md — customer-tier reality for L&G (walk-in / member / landscaper / project / wholesale); referenced in C.2
• rapid-pos-counterpoint-user-pain-points.md — pricing-rules complexity, customer-tier handling pain themes
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — R row = ● Full direct; this card is the L2/L3 expansion of that cell
• (CATz, proposed) method/artifacts/module-functional-decomposition.md — the artifact template this card proves out alongside Q and T