2026-04-25

Module Q (Loss Prevention) — Functional Decomposition

Artifact layer. Third of three Canary module artifact layers: 1. Canonical spec (vendor-neutral) — Canary-Retail-Brain/modules/Q-loss-prevention.md 2. Code/schema crosswalk (Canary-specific) — Brain/wiki/canary-module-q-loss-prevention.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

Q is the only spine module that is ★ Canary native in every Counterpoint Solution Map, because Counterpoint exposes the substrate (audit logs, drawer sessions, void-comp reasons, pricing decisions, category margin targets) but no detection layer. Q's functional surface is dominated by detection rule execution — 23 rules across 10 families — wrapped by five cross-cutting concerns (substrate ingestion, detection lifecycle, tuning, investigator surface, deployment phasing) and one vertical concern (garden-center allow-list framework).

The decomposition is observer-shaped end to end. Cashiers ring sales; Q watches the Documents arrive. Every L3 has actors drawn from Chirp (the rule engine), Owl (analyst-facing natural-language surface), Fox (case management), and the human store GM / LP analyst who consumes what those agents surface. There are no L3 processes whose actor is "the cashier" — that decomposition lives in Counterpoint's UI, not in Canary.

Executive summary

Dimension	Count	Source
L2 process areas	7	This card
L3 functional processes	38	This card
Detection rules referenced	23	`canary-module-q-counterpoint-rule-catalog.md`
Detection rule families (L3 grouping)	10	Rule catalog
Garden-center allow-lists (first-class)	5	Rule catalog + garden-center-operating-reality
Assumptions requiring real-customer validation	12	Tagged `ASSUMPTION-Q-NN`
User stories enumerated	71	Observer-perspective; actor ∈

Posture: archetype-shaped. No real customer engaged. Every assumption marker exists because the answer requires either a Rapid Garden POS sandbox database, a real customer's data, or both. The card is reusable across Counterpoint-shaped customers; per-customer overrides slot into the final section.

L1 → L2 → L3 framework

L1 (Solution Map cell)         Q = ★ Canary native
                                 │
L2 (Process areas)               ├── Q.1  Substrate ingestion
                                 ├── Q.2  Detection rule execution
                                 ├── Q.3  Detection lifecycle
                                 ├── Q.4  Tuning & allow-list management
                                 ├── Q.5  Investigator & analyst surface
                                 ├── Q.6  Vertical configuration
                                 └── Q.7  Deployment phasing
                                 │
L3 (Functional processes)       (38 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Lives in SDDs + module specs
                                  (canary-module-q-loss-prevention.md,
                                   canary-module-q-counterpoint-rule-catalog.md,
                                   ncr-counterpoint-retail-spine-integration.md)

Q.1 — Substrate ingestion

Purpose. Q reads CRDM only. T/R/N/S/F/D adapters populate CRDM from Counterpoint. Q never reaches into Counterpoint directly. This L2 enumerates which CRDM entities Q depends on, what fields it needs, and what cross-module contracts it asserts.

Dependency posture. Q is a read-only consumer of every other in-scope module. Any field Q needs must be exposed by the upstream module's adapter; Q does not write back into substrate.

A.3.1 dependency (load-bearing): Q.2 detection rules depend on A.3.1 asset-item registry as allow-list input. Items classified as non-inventory assets (ITEM_TYP = N or fixture class) must be excluded from Q detection rule evaluation. Q.2 must consume A.3.1 before firing inventory-discrepancy rules.

N.5 upstream contract: Q.1.4 store-config threshold context is sourced from N.5 (store-demographic config + LP threshold publication). N.5 must hold for Q.1.4 baseline expectations to be accurate. Changes to N.4 thresholds require Q rule re-evaluation.

L3 processes

ID	L3 process	Substrate read	Owning upstream module	Notes
Q.1.1	Read transaction headers	`Events.transactions` ← `PS_DOC_HDR`	T	DOC_ID, STR_ID, STA_ID, DRW_ID, DRW_SESSION_ID, USR_ID, SLS_REP, CUST_NO, TKT_NO, RS_UTC_DT, IS_DOC_COMMITTED, IS_REL_TKT
Q.1.2	Read transaction lines	`Events.transaction_lines` ← `PS_DOC_LIN[]`	T	LIN_TYP, ITEM_NO, QTY_SOLD, PRC, REG_PRC, EXT_COST, EXT_PRC, MIX_MATCH_COD, IS_DISCNTBL, HAS_PRC_OVRD
Q.1.3	Read payments	`Events.payments` ← `PS_DOC_PMT[]`	F (with T)	PAY_COD, PAY_COD_TYP, AMT, CARD_IS_NEW, SWIPED, EDC_AUTH_FLG
Q.1.4	Read multi-authority taxes	`Events.transaction_taxes` ← `PS_DOC_TAX[]`	F	AUTH_COD, RUL_COD, TAX_AMT, TXBL_LIN_AMT
Q.1.5	Read audit log	`Events.audit_log_entries` ← `PS_DOC_AUDIT_LOG[]`	T	LOG_SEQ_NO, CURR_USR_ID, CURR_DT, CURR_STA_ID, CURR_DRW_ID, ACTIV, LOG_ENTRY
Q.1.6	Read pricing decisions	`Events.pricing_decisions` ← `PS_DOC_LIN_PRICE[]`	T (with P-derived)	PRC_JUST_STR, PRC_GRP_TYP, PRC_RUL_SEQ_NO, UNIT_PRC, QTY_PRCD
Q.1.7	Read original-doc references	`Events.original_doc_refs` ← `PS_DOC_HDR_ORIG_DOC[]`	T	Links return → original sale, void → original sale
Q.1.8	Read store config thresholds	`Places.stores` ← `PS_STR_CFG_PS`	N	MAX_DISC_AMT, MAX_DISC_PCT, USE_VOID_COMP_REAS, RETAIN_CR_CARD_NO_HIST, ALLOW_DRW_REACTIV
Q.1.9	Read item categories with margin targets	`Things.item_categories` ← `IM_CATEG_COD`	S	CATEG_COD, MIN_PFT_PCT, TRGT_PFT_PCT
Q.1.10	Read customer tier + AR posture	`People.customers` ← `AR_CUST`	R	CUST_NO, CATEG_COD (tier), CR_RATE, NO_CR_LIM, BAL, IS_TAX_EXEMPT
Q.1.11	Read transfers, receivers, RTVs	`Events.transfers / receivers / returns_to_vendor` ← Document with DOC_TYP=XFER/RECVR/RTV	D, J	Source/dest store, vendor, items, quantities, payment if any

User stories

As Chirp, I want every CRDM field listed in Q.1.x to be present and typed before any rule fires, so that no rule silently misses data due to upstream adapter gaps.
As Chirp, I want substrate-staleness signals (last_polled_at per entity per tenant) so I can suppress alerts when the substrate is older than my freshness budget.
As an LP Analyst in Owl, I want to ask "what data is Q seeing for this store today" and get a freshness + completeness scorecard, not just rule output.

Cross-module contracts asserted

T must surface PS_DOC_AUDIT_LOG flattened with ACTIV and LOG_ENTRY preserved verbatim — Q rules pattern-match on these strings (ASSUMPTION-Q-01: full ACTIV code list)
T must surface PS_DOC_HDR_ORIG_DOC even when empty — Q.2.2 distinguishes "no link" from "no array"
N must surface PS_STR_CFG_PS thresholds at tenant-config time, not per-transaction (cached daily)
S must surface category margin targets (MIN_PFT_PCT, TRGT_PFT_PCT) on every item join

Q.2 — Detection rule execution

Purpose. Run the rule catalog. Each rule has substrate, logic, parameters, allow-lists, and severity. This L2 organizes the 23 rules into 10 families; the detailed rule definitions live in the rule catalog companion.

MECE assertion. Every detection in Canary against a Counterpoint substrate routes to exactly one rule family. New detection categories require a new family, not stuffing into an existing one.

L3 processes (rule families)

ID	Family	Rule IDs	What it detects	Garden-center wrinkle
Q.2.1	Discount-and-markdown	Q-DM-01, Q-DM-02, Q-DM-03	Price-override abuse, markdown-then-buy, below-cost sales	Wholesale tier customers may legitimately exceed store MAX_DISC_PCT — allow-list per CATEG_COD
Q.2.2	Void-and-return	Q-VR-01, Q-VR-02, Q-VR-03	Voids without original ticket, refunds without lookup, employee void clusters	None vertical-specific; rules apply uniformly
Q.2.3	Tender-mix anomalies	Q-TM-01, Q-TM-02, Q-TM-03	Cash-only register patterns, tender swaps, payment fragmentation	Farmers-market / event days legitimately cash-skewed — temporal allow-list
Q.2.4	Drawer-and-session	Q-DS-01, Q-DS-02, Q-DS-03	Drawer-count shrinkage, post-close activity, drawer reactivation	None vertical-specific
Q.2.5	Audit-trail anomalies	Q-AT-01, Q-AT-02, Q-AT-03	Document edits after payment, cross-station handling, manager-override frequency	Layaway / order-pickup workflows naturally cross-station — allow-list legitimate hold-and-recall flows
Q.2.6	Margin-erosion	Q-ME-01, Q-ME-02	Below-category-target margin sales, free-item patterns	Mix-and-match groups have intentionally low line margin (bundle margin is positive) — bundle-aware aggregation
Q.2.7	Inventory-and-shrink	Q-IS-01, Q-IS-02, Q-IS-03, Q-IS-04	Receiver-vs-PO discrepancy, cash-paid receivers (informational), transfer loss, dead-count tracking (informational)	First-class garden-center awareness: Q-IS-02 is allow-list-as-rule (cash receivers are normal). Q-IS-04 is informational tracking against seasonal baseline, not fraud
Q.2.8	Tax-and-compliance	Q-TC-01, Q-TC-02	Multi-authority tax mismatches, tax-exempt customer abuse	Landscaper customers may carry resale exemption; pattern-detect retail use of exemption
Q.2.9	Customer-tier abuse	Q-CT-01, Q-CT-02	Wholesale tier on retail-pattern customer, pre-purchase tier upgrade	Garden-center customer tiers are particularly volatile (seasonal landscaper conversions) — wider time window for Q-CT-02
Q.2.10	Mix-and-match abuse (garden-center-specific)	Q-MM-01, Q-MM-02	Mix-and-match producing below-cost line, mix-match code on non-grouped item	Entire family is garden-center-originated; will need re-shaping for non-garden verticals

User stories per family

Q.2.1 Discount-and-markdown

As Chirp, I want to flag any line where HAS_PRC_OVRD = "Y" and per-line discount exceeds the store's MAX_DISC_AMT/PCT threshold, with the customer's tier (AR_CUST.CATEG_COD) joined so wholesale-tier overrides are auto-suppressed.
As Chirp, I want to detect markdown-then-buy patterns by joining Things.items price-change events to subsequent transactions involving the same ITEM_NO and same USR_ID/SLS_REP within 24h.
As an LP Analyst in Owl, I want to ask "show me all below-cost sales by employee this month" and get a ranked list with each row drillable to the originating Document audit log.

Q.2.2 Void-and-return

As Chirp, I want to flag any voided transaction whose Events.original_doc_refs is empty, distinguishing "no link present" (suspicious) from "training-mode transaction" (allow-listed).
As Chirp, I want to flag refund transactions where no receipt-lookup audit-log entry preceded the refund — refund without ticket lookup is the high-confidence cash-refund-fraud signal.
As Fox, I want same-employee void clusters within a single drawer session bundled into a single case rather than fired as N separate detections.

Q.2.3 Tender-mix anomalies

As Chirp, I want to compare the cash-share at each (STA_ID, DRW_SESSION_ID) to that station's rolling baseline and flag sessions that deviate beyond threshold.
As Chirp, I want to detect tender-swap patterns by replaying audit-log entries on a Document and flagging cases where original tender = card and a later edit changed it to cash.
As an LP Analyst, I want a Friday-and-Saturday allow-list for stations designated as "event tents" so farmers-market-day cash patterns don't fire weekly false positives.

Q.2.4 Drawer-and-session

As Chirp, I want every drawer-close event to compare reconciled cash count to expected and emit a Q-DS-01 detection if the gap exceeds (dollar_threshold OR pct_threshold).
As Chirp, I want any audit-log entry on a Document committed AFTER its drawer-close timestamp to fire Q-DS-02, with a configurable grace window.
As Fox, I want recurring per-employee shrinkage across multiple sessions auto-promoted from low-severity individual detections to a single high-severity case.

Q.2.5 Audit-trail anomalies

As Chirp, I want to flag any line modification on a Document where IS_DOC_COMMITTED = "Y" was set before the modification timestamp — committed Documents shouldn't be edited.
As Chirp, I want to flag any single Document whose audit log shows CURR_STA_ID changing across 3+ stations, with layaway/order-pickup workflows allow-listed.
As an LP Analyst, I want manager-override frequency reported as a trend not as alerts — it's a pattern signal, not a per-event signal.

Q.2.6 Margin-erosion

As Chirp, I want every transaction line to compute (EXT_PRC - EXT_COST) / EXT_PRC and compare against the line's category MIN_PFT_PCT, aggregating below-target-margin volume per employee per week.
As Chirp, I want any line with EXT_PRC = 0 and HAS_PRC_OVRD = "Y" to count toward Q-ME-02 free-item-pattern detection per (USR_ID, DRW_SESSION_ID).
As Owl, I want to answer "which categories are running below margin target this month and why" with the per-line breakdown drillable to the contributing Documents.

Q.2.7 Inventory-and-shrink

As Chirp, I want to flag any receiver Document whose total quantity differs from the originating PO by > 5% or > $100, allow-listing documented short-shipments.
As Chirp, I want cash-paid receiver classification (Q-IS-02) routed to an "ad-hoc-vendor-payment" review queue, NOT the fraud queue — this is the load-bearing garden-center allow-list.
As Chirp, I want every transfer Document compared source-quantity vs destination-received-quantity, aggregating shrinkage to a per-route trend.
As a Garden-Center GM in Owl, I want dead-count write-offs tracked against seasonal baseline (per category, per season) so spikes surface but normal seasonal shrink doesn't.

Q.2.8 Tax-and-compliance

As Chirp, I want every Document's tax stack compared to the store's expected jurisdiction stack and flag any mismatches (could indicate misconfiguration or tax-evasion).
As Chirp, I want tax-exempt-customer transactions pattern-matched against retail-walk-in shape (single-line, low-dollar, retail SKUs) and flag suspected exemption abuse.
As an LP Analyst, I want a per-customer history view showing tax-exempt usage across 90 days so a known landscaper's legitimate exempt purchases are obvious.

Q.2.9 Customer-tier abuse

As Chirp, I want any customer whose CATEG_COD = WHOLESALE/LANDSCAPER but transaction history matches retail (avg ticket < $X, single-line walk-in) flagged for tier review.
As Chirp, I want any tier change on a customer record within 72h of a large purchase flagged as Q-CT-02, distinguishing legitimate sales-rep promotions from same-day-upgrade-then-buy patterns.
As Owl, I want to answer "which wholesale-tier customers actually shop like wholesale customers" and get the segmentation with explicit thresholds.

Q.2.10 Mix-and-match abuse (garden-center-specific)

As Chirp, I want bundle-level margin computed for any transaction containing MIX_MATCH_COD lines — flag only when the BUNDLE margin is negative, not when individual line margins are.
As Chirp, I want to flag any line carrying a MIX_MATCH_COD whose corresponding IM_ITEM is not part of that mix-match group — manual override pattern.
As Fox, I want mix-and-match abuse cases tagged with the bundle definition snapshot at detection time so retroactive bundle changes don't invalidate the case.

Cross-cutting rule contracts

Every rule has a dry_run | observation | alerting mode (per Q.7 phasing)
Every rule produces a Detection row carrying the substrate snapshot, not just IDs (so retroactive substrate changes don't invalidate detections)
Every rule has explicit allow-list hooks at the parameter layer (per Q.4)
Every rule emits to Fox case-bundling per (employee, session, time-window) co-occurrence rules

Q.3 — Detection lifecycle

Purpose. A detection isn't a one-shot fire-and-forget. Every Q.2 rule output flows through the same lifecycle stages: emit → suppress → bundle → escalate → case → close. This L2 owns the lifecycle.

L3 processes

ID	L3 process	Triggers	Output	Notes
Q.3.1	Detection emission	Rule fires against substrate	`Detection` row	Carries substrate snapshot, not just FK references
Q.3.2	Suppression evaluation	New detection arrives	suppress / pass-through	Allow-list match → suppressed-with-reason; threshold-below → suppressed-as-noise
Q.3.3	Case bundling	Multiple detections within `(employee, session, time-window)`	`Case` row groups N detections	Fox owns the bundling policy
Q.3.4	Severity escalation	Bundled case crosses severity threshold	severity bumped (low → medium → high)	E.g., 3+ low-sev shrinkage detections in 7d → medium case
Q.3.5	Investigator notification	Case reaches alerting threshold	Slack / email / dashboard alert	Per-tenant notification config
Q.3.6	Case investigation	Investigator opens case in Fox	Case state machine: open → in-progress → resolved/dismissed	Investigator notes, evidence attachment, audit trail
Q.3.7	Case close + outcome capture	Investigator marks resolved	Outcome enum: confirmed-fraud / training-issue / false-positive / unactionable	Outcomes feed back into rule tuning

User stories

As Chirp, I want every detection emission to write the substrate snapshot inline so a parser change tomorrow doesn't retroactively invalidate yesterday's detection.
As Fox, I want the bundling policy to be configurable per tenant (some merchants want per-employee-per-day, others per-employee-per-session).
As an LP Analyst, I want every dismissed false-positive to feed into a per-rule false-positive-rate metric so rule tuning is grounded in real outcomes, not vibes.
As a Store GM, I want one daily case digest instead of N individual alerts — Fox's bundling is the difference between Q being useful and Q being noise.
As Owl, I want to answer "which cases are still open across our stores" with the case state machine queryable.

Q.4 — Tuning & allow-list management

Purpose. Every rule is tunable by parameter; every rule has an allow-list. This L2 owns the operator-facing controls and the audit discipline around them.

L3 processes

ID	L3 process	Surface	Audit
Q.4.1	Threshold tuning per rule	`tune_rule_threshold(rule_id, parameter, value)` MCP tool	Audit-logged with operator + before/after + reason
Q.4.2	Allow-list entry creation	`add_allow_list_entry(rule_id, scope, reason)` MCP tool	Audit-logged; entries carry expiration
Q.4.3	Allow-list expiration / sunset	Automatic expiration job + manual revocation	Expired entries logged; renewal requires fresh reason
Q.4.4	Vertical-pack application	Apply garden-center pack at tenant onboarding (Q.6)	Snapshot at apply time; per-customer overrides tracked
Q.4.5	Rule promotion (dry-run → alerting)	`promote_rule(rule_id, mode)` MCP tool	Audit-logged with operator + readiness check

User stories

As an Operator in Owl, I want to tune Q-DM-01.severity_threshold from 1.0 to 1.5 with one MCP call and see the new value reflected in the next rule evaluation.
As an Operator, I want to add an allow-list entry for "customer 12345 — wholesale exemption granted by GM, expires 2027-04-25" with one call, with the expiration enforced automatically.
As an LP Analyst, I want to see the audit log of every threshold change and allow-list entry across the last 90 days, so audit-time reviews are clean.
As Fox, I want every detection to carry the threshold-as-of-detection-time so retroactive threshold tuning doesn't invalidate past detections.

Q.5 — Investigator & analyst surface

Purpose. Q outputs are meant to be consumed. This L2 owns the surfaces — Owl natural-language queries, Fox case management, MCP tools for programmatic access.

L3 processes

ID	L3 process	Surface	Actor
Q.5.1	Detection query	`query_detections(rule_id?, date_range, store_id?)` MCP tool	LP Analyst, Operator
Q.5.2	Detection detail	`get_detection_detail(detection_id)` — full substrate snapshot + audit trail	LP Analyst
Q.5.3	Owl natural-language Q&A over detections	Owl prompt → SQL/MCP synthesis → answer	Store GM, Exec
Q.5.4	Fox case workflow	Case open/in-progress/resolved/dismissed state machine	LP Analyst, Investigator
Q.5.5	Dry-run preview	`dry_run_rule(rule_id, date_range)` MCP tool — execute rule without writing detections	Operator (during tuning)
Q.5.6	Per-store / per-employee dashboards	Pre-built tiles surfacing Q outputs	Store GM, LP Analyst
Q.5.7	Case digest (daily/weekly)	Scheduled digest of open cases per recipient	Store GM, Exec

User stories

As a Store GM in Owl, I want to ask "what should I be paying attention to today?" and get the top 3 open Q cases for my store, ranked by severity and drillable to investigation context.
As an LP Analyst in Fox, I want to open a case, see all bundled detections + substrate snapshots + audit trails on one screen, attach my notes, and resolve with an outcome — without ever running a SQL query.
As an Operator, I want to dry-run a tuned rule against the last 30 days of data and see how many detections it would have produced, before I promote it to alerting.
As an Exec, I want a weekly digest with: cases opened, cases closed, confirmed-fraud-rate, top 3 patterns by frequency. One scrollable email.
As Owl, I want to answer "did our LP improve this month vs last" with a per-store comparison drawn from the case state machine.

Q.6 — Vertical configuration

Purpose. Q is the most vertical-aware module. Garden-center allow-lists are first-class, not bolt-on. This L2 owns the vertical-pack framework: what's in the garden-center pack today, how new vertical packs get added.

L3 processes (the 5 garden-center allow-lists)

ID	Allow-list	Rules affected	Behavior
Q.6.1	Cash-vendor-payment (load-bearing)	Q-IS-02 (cash-paid receivers)	Classify as ad-hoc-vendor-payment, route to review queue, NOT fraud queue
Q.6.2	Manual-entry noise	Q-IS-01, Q-IS-03 (receiver / transfer discrepancies)	Wider tolerance bands for receiver/transfer reconciliation
Q.6.3	Item-code drift	Q-ME-01, Q-CT-01 (margin / tier-on-retail)	Items churning in/out of catalog mid-season treated as expected
Q.6.4	Live-goods write-off	Q-IS-04 (dead-count tracking)	Seasonal baseline per category; only spikes above baseline flag
Q.6.5	Mix-and-match expected overlap	Q-MM-01 (mix-match below-cost line)	Bundle-margin computed; flag only when BUNDLE goes negative

L3 processes (vertical-pack management)

ID	L3 process	Notes
Q.6.6	Apply vertical pack at tenant onboarding	Garden-center pack applied to any tenant flagged `vertical=garden-center`
Q.6.7	Override vertical pack per-tenant	Customer-specific tightening or relaxation, audit-logged
Q.6.8	Author new vertical pack	When second vertical (gun store, feed-and-tack, specialty food, wine) onboards

User stories

As an Operator onboarding a new garden-center tenant in Owl, I want to apply the garden-center vertical pack with one call and see all 5 allow-lists become active, with per-tenant override available.
As an Operator, I want to see exactly which Q rules a vertical pack tunes and exactly what each tuning does, before I apply it.
As a Garden-Center GM, I want cash-paid receivers from my specialty growers to land in a "review and confirm" queue, not in the same alert stream as suspected fraud — Canary should know specialty growers paid in cash are normal.
As an LP Analyst at a non-garden-center customer, I want a clear UI signal that "this rule has a garden-center allow-list bypass that does NOT apply to this tenant" so I'm not confused about why a rule's behavior differs across tenants.

Q.7 — Deployment phasing

Purpose. Rules don't all fire on day-zero of a customer deployment. This L2 owns the per-tenant rollout discipline: backfill → observation → tuning → steady state. The phases come from the existing rule catalog; this card formalizes them as L3 processes.

L3 processes (per-tenant cutover phases)

ID	Phase	Window	Behavior
Q.7.1	Day 0 — backfill + dry-run	Tenant install + initial 24-72h Document backfill	All rules in dry-run mode; historical analysis only; no detections written; produces sample case packs for tuning
Q.7.2	Day 1-7 — observation	First operational week post-cutover	Low-FPR rules promoted to informational alerts; high-FPR rules stay dry-run; investigator pre-tuning baseline established
Q.7.3	Day 8-30 — tuning	Operator reviews dry-run outputs, tunes thresholds + allow-lists	Rules promoted per-rule based on dry-run outcome quality; vertical pack applied + customer-specific overrides set
Q.7.4	Day 30+ — steady state	All planned rules in alerting	Continuous tuning per investigator-feedback loop; quarterly rule-catalog audit

L3 processes (deployment ops)

ID	L3 process	Notes
Q.7.5	Tenant cutover playbook	Runbook for taking a tenant from Q.7.1 → Q.7.4
Q.7.6	Per-tenant rollback	If a rule fires badly, demote back to dry-run without blocking other rules
Q.7.7	Rule-catalog version pinning per tenant	Tenants can stay on rule catalog v1.x while v2.x deploys to new tenants — controlled migration

User stories

As an Operator cutting over a new garden-center tenant, I want a runbook that takes me through Q.7.1 → Q.7.4 with explicit go/no-go gates, not a vague "tune as needed" instruction.
As an Operator, I want to demote any individual rule from alerting back to dry-run with one MCP call when a tuning miss surfaces in production, without affecting other rules' state.
As Canary's Product Owner, I want every customer's rule-catalog version pinned and visible, so a v2.x rollout doesn't silently change behavior for v1.x tenants.
As an LP Analyst, I want the Day-30 tuning review to be backed by data — every rule promoted-or-demoted with explicit dry-run evidence, not gut feel.

Assumptions requiring real-customer validation

These markers exist because the answer requires either a Rapid Garden POS sandbox database, a real Counterpoint customer's data, or both. Until resolved, the corresponding rule logic is best-effort against public-source archetype information.

ID	Assumption	What it blocks	Resolution path
ASSUMPTION-Q-01	Counterpoint audit-log `ACTIV` codes — what each code means	Q.2.5 rules pattern-match on `LOG_ENTRY` strings; ACTIV is the intended discriminator	Sandbox DB inspection or NCR doc deep-read
ASSUMPTION-Q-02	Drawer reconciliation event modeling — captured in `PS_DOC_AUDIT_LOG`, separate `KeyValueData`, or different endpoint	Q.2.4 (Q-DS-01 drawer-shrinkage) substrate path	Sandbox DB inspection
ASSUMPTION-Q-03	Manager-override flag representation — explicit `USR_ID` role marker, or inferred from override-having + `Roles` membership	Q-DM-01 (discount-cap-exceeded confirmation), Q-AT-03 (manager-override frequency)	Sandbox DB or live customer Roles config
ASSUMPTION-Q-04	Tax-exempt customer field name — likely `AR_CUST.IS_TAX_EXEMPT`, not directly visible in current sample	Q-TC-02 (tax-exempt abuse) substrate path	Sandbox DB schema inspection
ASSUMPTION-Q-05	Dead-count / write-off Document type code — RTV with reason code, separate adjustment workflow, or other	Q-IS-04 (dead-count tracking) entire substrate path	Real garden-center customer data — this is the highest-leverage gap
ASSUMPTION-Q-06	Document edit-after-commit — does Counterpoint allow this, or do edits require void+reissue	Q-AT-01 (edit-after-payment) — if void+reissue, rule needs reframing	Sandbox DB workflow test
ASSUMPTION-Q-07	Multi-name plant convention — which fields hold botanical / Spanish / common names	Q.1.x substrate ingestion completeness for L&G item identity	Real Rapid Garden POS customer DB
ASSUMPTION-Q-08	Rapid POS proprietary tables on top of standard Counterpoint schema	Whether Q rules need additional substrate joins	Direct conversation with Rapid POS / customer
ASSUMPTION-Q-09	Real customer's category margin targets (defaults from API, but every customer tunes)	Q-ME-01 thresholds	Tenant onboarding — first 30 days observation
ASSUMPTION-Q-10	Real customer's tier code conventions (`CATEG_COD` values vary per VAR / customer)	Q-CT-01 (wholesale-on-retail-pattern), Q.6 vertical pack tier-aware allow-lists	Tenant onboarding
ASSUMPTION-Q-11	Day-0 backfill data volume and cleanliness — historical Documents may have schema drift, missing audit logs, etc.	Q.7.1 (backfill + dry-run) feasibility for tenants with long history	Customer-specific scoping at onboarding
ASSUMPTION-Q-12	Mix-and-match grouping conventions per Rapid Garden POS — whether bundles are stored as `MIX_MATCH_COD` groups or via Rapid-proprietary extensions	Q.2.10 (mix-and-match abuse) entire substrate path	Real garden-center customer DB

Highest-leverage gaps: ASSUMPTION-Q-05 (dead-count workflow) and ASSUMPTION-Q-12 (mix-and-match implementation) — both are garden-center-distinctive and both require a real customer database. These should be priority asks of any first Rapid Garden POS customer engagement.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
Vertical pack: <garden-center | gun-store | feed-and-tack | ...>
Tier code conventions:
  WHOLESALE → ...
  LANDSCAPER → ...
  RETAIL → ...
Per-rule overrides:
  Q-XX-NN: <parameter> = <value> (reason; expires <date>)
  ...
Allow-list additions:
  <rule>: <scope>, <reason>, <expiration>
  ...
Disabled rules (with reason):
  <rule>: <reason>
  ...
ASSUMPTION resolutions:
  ASSUMPTION-Q-NN: resolved as <answer>; source: <evidence>
  ...

Operating notes

This card is the L2/L3 functional decomposition for one module. Sister cards (T, R, N, S, F, D) are next; format must remain consistent across them so the Solution Map cells can cross-reference cleanly.
The methodology gap this card stands in is real: CATz Phase II has no named artifact at this layer. Once 2-3 module cards are stable, propose CATz/method/artifacts/module-functional-decomposition.md formally with this Q card as the worked-example proof.
Every L3 process here either has a corresponding rule in canary-module-q-counterpoint-rule-catalog.md (for Q.2 detection), an MCP tool surface (for Q.4–Q.5), or a runbook (for Q.7). Nothing is purely speculative — but every L3 has assumption markers where the substrate-side answer requires real-customer ground-truthing.

canary-module-q-counterpoint-rule-catalog.md — full rule definitions (substrate × logic × parameters × allow-lists × severity); referenced by Q.2
canary-module-q-loss-prevention.md — Module Q general overview (architecture-level, not functional decomposition)
ncr-counterpoint-document-model.md — Document substrate detail (audit log, original-doc refs, pricing rules, taxes); referenced by Q.1
ncr-counterpoint-api-reference.md — full API surface + Store config thresholds + category margin targets; referenced by Q.1.8 / Q.1.9
ncr-counterpoint-endpoint-spine-map.md — per-endpoint × CRDM × spine map; referenced by every Q.1 substrate row
garden-center-operating-reality.md — vertical-specific allow-list logic; referenced by Q.6
rapid-pos-counterpoint-user-pain-points.md — public-source pain themes informing rule prioritization
rapid-pos-counterpoint-market-research-tam.md — engagement sizing context
ncr-counterpoint-rapid-pos-relationship.md — VAR clarification + feature-to-API mapping
(CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — Q row = ★ Canary native; this card is the L2/L3 expansion of that cell
(CATz) method/artifacts/solution-map.md — L1 artifact this card sits below
(CATz, proposed) method/artifacts/module-functional-decomposition.md — the artifact template this card proves out; not yet authored

Module Q (Loss Prevention) — Functional Decomposition

Governing thesis

Executive summary

L1 → L2 → L3 framework

Q.1 — Substrate ingestion

L3 processes

User stories

Cross-module contracts asserted

Q.2 — Detection rule execution

L3 processes (rule families)

User stories per family

Q.2.1 Discount-and-markdown

Q.2.2 Void-and-return

Q.2.3 Tender-mix anomalies

Q.2.4 Drawer-and-session

Q.2.5 Audit-trail anomalies

Q.2.6 Margin-erosion

Q.2.7 Inventory-and-shrink

Q.2.8 Tax-and-compliance

Q.2.9 Customer-tier abuse

Q.2.10 Mix-and-match abuse (garden-center-specific)

Cross-cutting rule contracts

Q.3 — Detection lifecycle

L3 processes

User stories

Q.4 — Tuning & allow-list management

L3 processes

User stories

Q.5 — Investigator & analyst surface

L3 processes

User stories

Q.6 — Vertical configuration

L3 processes (the 5 garden-center allow-lists)

L3 processes (vertical-pack management)

User stories

Q.7 — Deployment phasing

L3 processes (per-tenant cutover phases)

L3 processes (deployment ops)

User stories

Assumptions requiring real-customer validation

Customer-specific overrides

Operating notes

Related