Home ›Brain ›Cards

What this is

The unified item authorization model: the convergence of item master eligibility, site-level regulatory restrictions, planogram listing state, and operational blocks into a single salability gate — the definitive answer to "is this item authorized for sale at this store right now, and why or why not?"

Purpose

This is the convergence gap conventional retail platforms have never closed. Item status lived in the item master. Regulatory restrictions lived in the site master — when they were maintained at all. Planogram listing state lived in the space planning system, loosely synchronized on a batch cycle. Operational blocks (recall, LP hold, merchant clearance-only designation, legal hold) lived in POS parameter files, spreadsheet emails to the POS team, and, frequently, nowhere recoverable at all. The POS became the de facto convergence point — it had to carry local copies of all these dimensions in its own parameter database — with all the synchronization failure modes that implies. An item cleared for recall in the item master might remain saleable at POS for days. An age-restricted item might sell freely at a store in a jurisdiction where local ordinance requires electronic ID verification. A planogram reset might remove an item from the shelf while the listing system still authorizes replenishment.

Item authorization exists as a distinct model because no other module owns the convergence. Each upstream system owns one dimension. No upstream system owns the synthesized answer. Without a unified authorization model, the POS is the system of record by default — and that is the worst possible place for it to be.

Structure

Item authorization has four dimensions. All four must resolve to "authorized" for a transaction to proceed. A block on any single dimension produces a salability denial, with a reason code indicating which dimension blocked and why.

Dimension 1 — Item eligibility

Item-level flags maintained in the item master that govern universal eligibility regardless of site:

Item eligibility is binary and site-agnostic. An item under recall is blocked at every store simultaneously, not routed through store-by-store updates.

Dimension 2 — Site regulatory zone

Site-level configuration that overlays item eligibility with jurisdiction-specific restrictions. The regulatory zone is a property of the site, not the item. One item may be fully authorized at Store A and restricted at Store B because of their respective regulatory zones.

Regulatory zone data must be maintained in the site master and kept current. Regulatory change (e.g., federal minimum tobacco age increase) requires a systematic sweep of the site regulatory configuration, not store-by-store updates. The regulatory zone is the configuration layer that localizes a national assortment to a specific legal environment.

Dimension 3 — Planogram listing state

An item is authorized for sale only at stores where it is listed on an active planogram. This is the assortment management control: the planogram defines the physical range, and the listing state is the system's representation of that range.

The listing state dimension is what prevents phantom replenishment and ensures that the POS and the replenishment system agree on what is stocked at a given location. It is also the mechanism by which a range decision (remove item from small-format stores) propagates to actual sale restriction at those stores.

Dimension 4 — Operational blocks

Explicit blocks placed by authorized operational teams, each with a defined scope, reason code, and expiry protocol:

Each operational block must carry: the blocking authority (team + individual), the block scope (chain / region / site / site group), the reason code, the creation timestamp, and an expiry protocol (explicit date, event-based release, or manual review). Blocks without expiry protocols become orphaned and invisible.

The convergence failure

The traditional implementation pattern kept all four dimensions in separate systems with no unified query surface. The consequences were predictable:

The POS parameter file was the practical system of record because it was the enforcement point. Every authorization dimension had to be translated into a POS parameter update before it took effect. That translation step was where recalls were delayed, blue law schedules were misconfigured, and operational blocks were lost.

Consumers

The POS system is the primary enforcement consumer: authorization state must be available at the point of transaction, with reason codes for customer-facing messaging when a sale is denied. The Replenishment module consumes listing state from Dimension 3 — it should not be possible to generate a replenishment order for an item that is not listed at a site. The Operations Agent monitors authorization state changes and their propagation to POS — specifically the latency between a block being issued and it taking effect at the point of sale. The Merchant dashboard consumes the authorization profile for assortment health monitoring: items blocked for >N days, items with stale regulatory zone configurations, items whose listing state and replenishment state disagree.

Invariants

Platform (2030)

Agent mandate: Technical Agent owns authorization state management — it is the system that receives upstream events (planogram publication, item status change, recall issuance, regulatory zone update) and propagates them to the authorization record in real time. Operations Agent monitors authorization latency (time from block issuance to POS enforcement), stale regulatory zone configurations, and listing-replenishment disagreements as continuous signals. Business Agent receives authorization exception escalations — items blocked for extended periods without resolution, regulatory zone conflicts that require merchant-level decisions.

item_authorized as a single-call contract state query. In the Canary Go model, authorization is not a POS parameter file. It is a contract state query. item_authorized(item_id, site_id) evaluates all four dimensions against current state — item eligibility from the item master contract, regulatory zone from the site configuration, listing state from the planogram event log, operational blocks from the active block registry — and returns a boolean plus a structured reason if denied. The POS does not carry local copies of these dimensions. It calls the authorization surface at transaction time and enforces the result. This eliminates the "POS parameter update lag" failure mode entirely: there is no parameter file to update. The authorization state is live.

Recall propagation as a contract event. When a recall block is issued — by the merchant, by a supplier notification, or by a regulatory authority — it is a contract event on the item master. Technical Agent receives the event and immediately updates the authorization record across all affected site contracts. The recall is effective the moment the event is confirmed. The latency between "recall issued" and "item blocked at POS" is the contract event propagation time, not the POS parameter update cycle time. For smart-contract-native items, the supplier can issue a recall notification as a signed contract event — cryptographically attributable, timestamped on-chain, and automatically propagated to all retailer site authorizations without requiring a manual supplier communication workflow.

Regulatory zone as site configuration, not item configuration. The site configuration contract holds the complete regulatory zone profile: blue law schedule by day and hour, age verification requirements by item classification, controlled substance scheduling by state, and any local prohibitions. When a regulatory change occurs (federal minimum age increase, state scheduling change), Technical Agent updates the affected site configurations in bulk. Every item authorization query for those sites immediately reflects the updated regulatory zone — no item-by-item update required. The site regulatory profile is the single point of truth for jurisdictional compliance; it does not live in the item master and does not require per-item maintenance.

Operations Agent: authorization health as a continuous signal. Traditional authorization management is reactive: a recalled item sells, someone notices, an investigation follows. Operations Agent monitors authorization state proactively. Key signals: (1) items with active blocks where no expiry protocol is set — orphaned blocks that will never be reviewed; (2) items listed at a site but with authorization disagreement between the listing dimension and any other dimension — the item is listed but blocked, meaning replenishment is running for an item that cannot be sold; (3) sites with regulatory zone configurations that have not been reviewed since the last relevant regulatory change in their jurisdiction; (4) authorization latency metric — time from upstream event (recall issued, planogram published, status changed) to authorization state updated, monitored per event type.

MCP surface. item_authorized(item_id, site_id) returns authorization status (boolean), denial reason code and dimension if denied, and the timestamp of the last state evaluation. authorization_blocks(item_id) returns all active blocks across all four dimensions with scope, reason code, blocking authority, and expiry protocol. site_authorization_profile(site_id) returns the complete regulatory zone configuration: blue law schedule, age verification requirements by item classification code, and active ordinances. authorization_changes(site_id, period) returns items whose authorization state changed in the window with the dimension that changed and the triggering event — the change log that POS systems can pull to refresh their local cache rather than querying every item on every transaction. authorization_conflicts(site_id) returns items with inconsistent state across dimensions — listed but blocked, authorized but de-listed, recalled at item level but not propagated to site-level block — the exception queue for Technical Agent remediation.

RaaS. Authorization state changes — recall issued, block placed or lifted, regulatory zone updated, listing changed — are sequenced events. The authorization state at the time of any POS transaction must be reconstructible from the event log: a recall issued at 2pm must block transactions after 2pm; transactions before 2pm were authorized. This is the evidentiary basis for any dispute about whether an item should have been sold. item_authorized(item_id, site_id) from Valkey hot cache (sub-20ms; called at POS transaction time — high call volume at scale). authorization_changes(site_id, period) is a SQL delta feed, not a full recompute, enabling POS systems to refresh their local cache incrementally rather than pulling full state. Authorization event log in SQL append-only, indexed on (site_id, event_type, event_timestamp) for ad hoc LP investigation queries. Authorization history exportable for regulatory audit, LP investigation, and POS reconciliation.

Canary Retail Brain · GrowDirect LLC canary@growdirect.io