Module S (Space) — Functional Decomposition

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

Governing thesis

S is the catalog substrate for everything in the spine that touches a product. Q reads category margin targets from S. P-derived pricing observations join through S. J's like-item forecasting reaches into S for category-average velocity. T's transaction lines reference S for item identity. R's tier-aware allow-lists join through S to apply per-category exemptions. Every non-trivial detection or projection routes through S.

Counterpoint's catalog surface is the richest of any spine module — 17 endpoints covering item master, categories, serial numbers, images, per-location inventory, vendor-item linkage, and a parallel eCommerce catalog. For a Lawn & Garden tenant specifically, three vertical capabilities sit on top of this substrate and are load-bearing: mix-and-match groups (MIX_MATCH_COD on items + per-line on Documents), fractional unit modeling (PREF_UNIT_NUMER/DENOM/NAM for "sell flat OR sell individual plant from flat"), and multi-name plant identity (botanical / common / Spanish names — convention-dependent across the ADDL_DESCR_* and ATTR_COD_* slots).

S is ● Full direct in every Counterpoint Solution Map cell, but the cell hides three real architectural concerns that don't show up in simpler retail verticals: (1) item lifecycle is short and seasonal — the catalog churns mid-season, item-code drift across intakes is normal not anomalous, (2) the ecommerce catalog runs in parallel with separate publish flags + state machine + control table, and (3) per-customer naming conventions for multi-name fields vary across Rapid POS deployments — there is no universal mapping for which ADDL_DESCR_N slot holds which language.

Counterpoint Endpoint Substrate

Executive summary

Posture: archetype-shaped against Counterpoint specifically. The garden-center vertical concerns (mix-and-match, fractional units, multi-name plants) are first-class L2/L3 areas because they're load-bearing for Q rules and P-derived pricing observations. Per-customer convention discovery for multi-name fields and category-margin targets happens at onboarding.

L1 → L2 → L3 framework

L1 (Solution Map cell)         S = ● Full direct (Counterpoint Item / Inventory / EC families — 17 endpoints)
                                 │
L2 (Process areas)               ├── S.1  Item master ingestion + sync
                                 ├── S.2  Category hierarchy + margin targets
                                 ├── S.3  Mix-and-match group surfacing      (garden-center distinctive)
                                 ├── S.4  Fractional unit modeling           (garden-center distinctive)
                                 ├── S.5  Item lifecycle + drift handling    (garden-center reality)
                                 ├── S.6  eCommerce catalog surface
                                 └── S.7  Cross-module substrate contracts
                                 │
L3 (Functional processes)       (36 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Lives in SDDs + module specs
                                  (Canary-Retail-Brain/modules/S-space.md,
                                   docs/sdds/canary/ncr-counterpoint-retail-spine-integration.md §6.4)

S.1 — Item master ingestion + sync

Purpose. Pull the Counterpoint item catalog into CRDM. Counterpoint's Item endpoint is the single richest entity surface in the API — IM_ITEM carries dozens of fields covering identity, classification, pricing, costing, attributes, ecommerce flags, mix-and-match grouping, vendor linkage, and serial-number tracking. S surfaces all of it without normalization.

Companion cards. ncr-counterpoint-api-reference (Item endpoint family + cache discipline), Canary-Retail-Brain/modules/S-space.md (canonical spec), canary-module-s-space.md (schema crosswalk).

L3 processes

User stories

• As S's catalog ingester, I want the daily item-metadata poll to respect the 24h server-cache by default and only force ServerCache: no-cache when an item-attribute change is suspected (price update, vendor change, attribute toggle).
• As S, I want every IM_ITEM field preserved verbatim through ingestion — downstream modules (P-derived pricing, Q margin rules) need the raw values, not a normalized subset.
• As Q, I want category and subcategory codes attached to every item reference at parse-time, so margin-erosion rules don't need a second join to resolve item context.
• As J, I want vendor-item linkage available without a separate Counterpoint call per recommendation — the supplier should be on the item record at recommendation generation time.

S.2 — Category hierarchy + margin targets

Purpose. Counterpoint exposes category and subcategory codes plus per-category margin targets (MIN_PFT_PCT, TRGT_PFT_PCT). These are load-bearing for Q's margin-erosion rules (Q-ME-01) and informational for P-derived pricing observations. The hierarchy is also the foundation for J's like-item forecasting and S's own assortment-and-range execution surface.

Companion cards. ncr-counterpoint-api-reference § "Category margin targets", canary-module-q-counterpoint-rule-catalog.md § Q-ME-01 (consumer of margin targets).

L3 processes

User stories

• As S, I want every item join to carry the category's MIN_PFT_PCT and TRGT_PFT_PCT inline, so Q-ME-01 can compute realized-vs-target margin per line without a second lookup.
• As S, I want category reassignment events captured with effective dates so historical sales attribute correctly to "the category at the time of the sale" — not "the category as of today" — for plan-vs-actual comparisons.
• As a Garden-Center GM in Owl, I want to ask "which categories are below margin target this month" and get a per-category rollup with the contributing items drillable.
• As J's like-item forecaster, I want category-average velocity available per (category, location) so new mid-season SKUs can use category context for their initial forecast.

S.3 — Mix-and-match group surfacing (garden-center distinctive)

Purpose. Mix-and-match flat pricing — buy 6 perennials for $30 regardless of which 6 — is a defining capability of garden-center retail. Counterpoint surfaces this through MIX_MATCH_COD on IM_ITEM (group identity) and on PS_DOC_LIN (per-line membership at sale time, plus MIX_MATCH_CONTRIB and MIX_MATCH_PRC_BASED_ON for the bundle math). S surfaces the group identity; T captures the per-line application; Q audits the bundle integrity.

Companion cards. ncr-counterpoint-rapid-pos-relationship § "Mix-and-match flats / bundle pricing", canary-module-q-counterpoint-rule-catalog.md § Q-MM-01 / Q-MM-02 (consumer of mix-and-match group identity).

L3 processes

User stories

• As S, I want to surface every item's MIX_MATCH_COD so Q can build a per-bundle membership table at boot and answer "is this line legitimately part of this bundle" deterministically.
• As Q, I want bundle-level margin computed — sum of bundle line EXT_PRC minus sum of bundle line EXT_COST — flagged only when the BUNDLE goes negative, not when individual lines do (intentional structure of mix-and-match flat pricing).
• As an LP Analyst investigating a Q-MM-01 case in Fox, I want to see the bundle definition snapshot at detection time + the lines actually rung + the resulting bundle margin, all on one screen.
• As a Garden-Center GM in Owl, I want to ask "which mix-and-match bundles are running below target this season" and get the per-bundle drilldown.

S.4 — Fractional unit modeling (garden-center distinctive)

Purpose. Garden centers sell the same physical item at multiple unit granularities — buy a flat of 18 perennials, or buy a single perennial from the same flat. Counterpoint models this through IM_ITEM.PREF_UNIT_NUMER/DENOM/NAM + STK_UNIT and per-line PS_DOC_LIN.QTY_NUMER/QTY_DENOM/QTY_UNIT/SELL_UNIT. The fractional model is also load-bearing for non-plant categories (bulk soil sold by cubic foot or yard, fertilizer sold by lb or bag).

Companion cards. ncr-counterpoint-rapid-pos-relationship § "Bulk-to-fractional sales".

L3 processes

User stories

• As S, I want every item's stock-unit and preferred-sell-unit available so D can decrement inventory correctly when a fractional quantity is sold.
• As Owl, I want to answer "how many flats of perennials sold this week" by aggregating fractional quantities back to flat-equivalents transparently — the user shouldn't need to know whether each sale was a flat or 18 individual plants.
• As Q, I want to recognize fractional-unit sales as legitimate — a single-plant sale shouldn't fire Q-DM-03 (below-cost) just because the per-unit cost lookup gave the flat cost not the plant cost.

S.5 — Item lifecycle + drift handling

Purpose. Garden-center catalogs are short-lifecycle and high-churn. New items appear mid-season as new shipments arrive; old items retire. Item-code drift is normal — the same plant cultivar may exist as multiple ITEM_NO records over time as different intakes get coded differently. Multi-name plant identity (botanical / common / Spanish) is convention-dependent across the ADDL_DESCR_* and ATTR_COD_* slots; per-customer convention discovery happens at onboarding.

Companion cards. garden-center-operating-reality § "What this means for the data flow" (item-code drift, mid-season ad-hoc additions, multi-name plants).

L3 processes

User stories

• As S, I want item-code drift recognized as normal — when two different ITEM_NOs have very similar descriptions and the same vendor, surface the linkage as a hint to investigators rather than treating each as fully independent.
• As S, I want per-customer multi-name field convention captured at onboarding — for Customer X, ADDL_DESCR_1 is botanical name, ADDL_DESCR_2 is Spanish — so plant lookups across languages work consistently.
• As a Garden-Center GM in Owl, I want to search "monstera" and find both the item with DESCR='Monstera Deliciosa' and the item with ADDL_DESCR_2='Costilla de Adán' (Spanish common name) — the multi-name discovery is the language layer over the catalog.
• As Q.6 vertical pack, I want item-code drift on the allow-list for Q-ME-01 (margin) and Q-CT-01 (tier-on-retail-pattern) so churning catalog doesn't fire spurious detections.

S.6 — eCommerce catalog surface

Purpose. Counterpoint runs a parallel eCommerce catalog with its own publish state machine, EC-specific flags on items, EC-specific category tree, and EC-specific inventory snapshots. Whether a tenant uses NCR Retail Online, a third-party connector (IceSync / Shopify integration / etc.), or DIY against the API, the EC fields surface through the same standard endpoints.

Companion cards. ncr-counterpoint-api-reference § "Ecommerce surface — Counterpoint as omnichannel hub", garden-center-operating-reality § "The omnichannel reality".

L3 processes

User stories

• As S, I want every item's EC publish state surfaced so Q can monitor for stuck-in-publishing items (which sometimes indicate a broken eCommerce sync — a known pain pattern in the user-pain-points wiki).
• As an Operator monitoring an omnichannel garden-center tenant, I want a per-tenant EC sync health dashboard showing items pending publish, items with publish failures, and items with EC-vs-physical inventory mismatches.
• As Owl, I want to answer "how is online performing vs in-store this season" by joining Document EC flags through to S's per-item EC attribution.

S.7 — Cross-module substrate contracts

Purpose. S supplies catalog substrate to nearly every other spine module. This L2 is the contract registry — what fields, what preservation rules, what freshness commitments. Symmetric to T.7 / C.6 / J.8b.

L3 contracts (registry)

User stories

• As S, I want every contract in S.7 enforced via the contract test suite — adding a third POS adapter requires it to surface every S.7 field or it doesn't pass conformance.
• As Q, I want to assert at boot that S surfaces all contracted fields including MIN_PFT_PCT and mix-and-match group identity, so a silent S contract break shows up at startup not at first detection-miss.
• As J, I want vendor-item linkage on every item record so my recommendation generation never blocks waiting for a separate VendorItem call.

Canary Detection Hooks

Additional User Stories

• As a loss prevention analyst using Owl, I need to see which planogram positions are chronically out-of-stock relative to online availability so I can identify potential diversion at the display level.

Assumptions requiring real-customer validation

Highest-leverage gaps: S-04 (mix-and-match bundle pricing storage) and S-07 (multi-name plant convention). S-04 is the load-bearing assumption for Q-MM-01 + the entire S.3 L2. S-07 is the load-bearing assumption for the multi-language Owl search experience and is engagement-knowable only — every customer is unique.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
Multi-name field convention:
  ADDL_DESCR_1 → <botanical | Spanish | common | other>
  ADDL_DESCR_2 → <...>
  ADDL_DESCR_3 → <...>
  ATTR_COD_1 → <...>
  ATTR_COD_2 → <...>
Mix-and-match bundle pricing storage: <where bundles' target prices live>
Fractional-unit categories actively used: [perennials, bulk soil, fertilizer, ...]
Per-category margin targets (overrides to API defaults):
  <CATEG_COD>: MIN=<%>, TRGT=<%>
EC platform: <NCR Retail Online | Shopify connector | IceSync | DIY | none>
EC inventory model: <held-for-fulfillment | shared-with-physical | other>
Rapid POS proprietary extensions in scope: <field list | none>
Disabled S.x processes (with reason):
  S.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-S-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

Cast of actors:

S is the most vertical-distinctive substrate module. Three full L2 areas (S.3 mix-and-match, S.4 fractional units, S.5 lifecycle/drift) exist because L&G retail demands them. A non-garden vertical pack would re-shape these — a gun-store pack would emphasize serial-number tracking (S.1.5/S.1.6) and ATF-compliance category attributes; a wine pack would emphasize vintage and varietal attributes via the same ADDL_DESCR_* slots with different conventions.

The category-margin-target contract (S.7.2) is the load-bearing producer-side bridge to Q. Q.2.6 (margin-erosion) and Q-ME-01 specifically depend on category targets being inline on every item join. This is the highest-frequency contract S delivers — every transaction line carries it.

The multi-name plant convention (S.5.2 + S.7.5) is engagement-knowable only. Platform-level discovery cannot resolve which slot means what — every customer has unique conventions. Capture at onboarding, audit at customer review, never assume across customers.

Related

• Canary-Retail-Brain/modules/S-space.md — L1 canonical spec
• canary-module-s-space.md — L2 Canary code/schema crosswalk
• canary-module-q-functional-decomposition.md — sister card; S.2.3 + S.7.2 (margin targets) + S.3 (mix-and-match) + S.5 (drift) drive Q rule families
• canary-module-t-functional-decomposition.md — sister card; T's transaction-line parse needs S's item context (T.7.8 contract)
• canary-module-c-functional-decomposition.md — sister card; R's tier-aware allow-lists join through S categories
• canary-module-o-functional-decomposition.md — sister card; J's like-item forecasting and vendor-scorecard depend on S.2 + S.7.8
• ncr-counterpoint-api-reference.md — full Item / Inventory / EC family detail
• ncr-counterpoint-endpoint-spine-map.md — per-endpoint × CRDM × spine map for Item family
• ncr-counterpoint-rapid-pos-relationship.md — feature-to-API mapping (mix-and-match, fractional, multi-name)
• garden-center-operating-reality.md — vertical reality (item-code drift, mid-season churn, multi-name conventions)
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — S row = ● Full direct
• (CATz) method/artifacts/module-functional-decomposition.md — the artifact template this card follows