esl-price-sync – Marketing & SEO skill for AI agents

ESL Price Sync: Deterministic Retail Shelf-Edge Pricing Architecture

Ensure strict real-time parity between ERP/POS price masters and Electronic Shelf Label (ESL) fleets (SES-imagotag, ZKONG, Pricer, Hanshow, SOLUM) via bounded delta streams, monotonic idempotency tokens, and Sub-GHz RF battery preservation models.

When to Use This Skill

Activate this skill when:

• Designing, implementing, or auditing integration pipelines between enterprise retail masters (SAP, Oracle Retail, Dynamics 365, Lightspeed) and ESL server platforms.
• The user asks: "How do I sync price updates to ESL tags without draining batteries?", "Debug ghost pricing where POS doesn't match the shelf tag", "Design an idempotent delta feed for ZKONG or SES-imagotag", or "Schedule promotional pricing with automatic rollback".
• Reconciling price discrepancy logs between central ERP databases, ESL middleware, and wireless base station ACK telemetry.
• Calculating battery life depletion curves for e-paper tags running on CR2450 coin cells under varying refresh frequencies.

Do NOT use this skill when:

• Managing e-commerce web store frontends or dynamic pricing algorithms (this skill governs faithful delivery of decided prices to physical tags).
• Troubleshooting individual dead hardware tags before gateway RF coverage and RSSI signal propagation have been verified.
• Performing live write operations on production store fleets without a preceding read-only audit verification pass.

Core Mental Models & Non-Negotiable Rules

1. The 5-Layer ESL Architecture Pipeline:

• Every price synchronization event traverses five distinct operational tiers:

$$\mathbf{Price\ Master\ (ERP/POS)} \xrightarrow{\text{Extract}} \mathbf{Transform\ Middleware} \xrightarrow{\text{API/Message}} \mathbf{ESL\ Server} \xrightarrow{\text{Sub-GHz/2.4GHz}} \mathbf{Base\ Station\ (AP)} \xrightarrow{\text{RF\ Packet}} \mathbf{Physical\ Tag}$$

• Traceability Invariant: Every price payload MUST carry a deterministic trace_id recording timestamps and status codes across all five layers. A "200 OK" from the ESL central server API is NEVER treated as proof that the physical shelf display has updated.

2. Strict Delta Discipline & Cryptographic Watermarking:

• Pushing a full 50,000-SKU store catalog on a scheduled cron is strictly forbidden.
• Updates MUST be generated by calculating a cryptographic row hash:

$$\text{RowHash} = \text{SHA256}(\text{SKU} + \text{BasePrice} + \text{PromoPrice} + \text{Currency} + \text{UnitOfMeasure} + \text{Barcode} + \text{TemplateID})$$

• Only records where $\text{RowHash}_{new} \neq \text{RowHash}_{pushed}$ are queued for transmission.
• Full pushes are strictly restricted to initial store commissioning and disaster recovery restores.

3. Monotonic Idempotency & Out-of-Order Packet Defense:

• High-volume retail message brokers inevitably deliver packets out of order during network re-balancing.
• Every transmission packet MUST include an idempotency_key and a monotonically increasing version_timestamp (ISO 8601 UTC).
• If an incoming price payload has $\text{version\_timestamp} \le \text{last\_applied\_version}$, the ESL middleware MUST discard the payload to eliminate race condition reversions.

4. RF Gateway Rate-Limiting & Battery Longevity Budget:

• Illustrative assumptions only: each physical e-paper display refresh may cost between $12\ \mu\text{Ah}$ and $25\ \mu\text{Ah}$.
• A dual-CR2450 battery pack provides $1,200\text{ mAh}$ nominal capacity ($960\text{ mAh}$ usable considering passivation and low-temperature shelf environments).
• Illustrative refresh budget: A three-refresh daily budget is a planning assumption, not a lifespan guarantee; use measured vendor-specific standby, retry and refresh consumption, temperature and battery configuration.
• Base Station Queue Throttling: Gateways operate over shared Sub-GHz (868/915 MHz) or proprietary 2.4 GHz RF channels. Use the measured vendor gateway capacity; the examples assume a configurable 150 tag updates per gateway per minute to prevent RF collision retries from draining batteries.

5. Read-Only Audit Mode by Default:

• Diagnostic and reconciliation tasks MUST execute in read-only audit mode.
• Output discrepancy reports containing SKU, ERP Price, Gateway ACK Price, and Divergence Layer.
• State-changing write updates require explicit operator consent.

Named Sins & Anti-Patterns (Что категорически ЗАПРЕЩЕНО)

| Anti-Pattern | Manifestation in Code/Workflow | Mandatory Production Counter-Rule |

| :--- | :--- | :--- |

| Scheduled Full Catalog Floods | Blasting 60,000 tags every night at midnight. | Stream strict deltas using SHA256 content watermarks. |

| Ghost Price Blindness | Assuming API 200 OK means the customer sees the new price. | Track gateway ACK packet receipts (status: ACK_CONFIRMED). |

| Non-Idempotent Retries | Retrying failed HTTP calls without idempotency keys. | Attach UUIDv5(sku, store_id, price_timestamp) to all mutations. |

| Timezone Ambiguity | Pushing promo prices without UTC/local time offsets. | Enforce ISO 8601 UTC timestamps with explicit store local offsets. |

| Gateway RF Flooding | Blasting 5,000 updates/second to a single RF base station. | Enforce leaky-bucket queue throttling ($\le 150\text{ tags/min/AP}$). |

| Silent Canvas Overflow | Pushing a 6-digit price into a 4-digit template field ($1499 becomes $14). | Validate text bounds and template layout dimensions before enqueueing. |

| Destructive Rollback Omission | Deploying flash sales without pre-computing revert state. | Cache previous active state to enable 1-click atomic rollback. |

| Orphan Tag Neglect | Leaving decommissioned tags in the active database. | Reconcile missing heartbeat tags after 72 hours; flag as ORPHAN. |

| Mid-Day Peak Syncing | Pushing massive price shifts during peak Saturday shopping hours. | Schedule bulk promotions before store opening or during off-peak hours. |

| Unshielded Write Broadcasts | Executing write scripts without an audit dry-run. | Enforce dry-run simulation mode prior to initiating physical RF broadcasts. |

Concrete Archetypes / Presets

Archetype 1: Idempotent Delta Synchronizer (Python 3.10+)

import hashlib
import time
from typing import Dict, List, Optional

def compute_sku_hash(item: dict) -> str:
    import json
    payload = json.dumps({key: item[key] for key in
                         ("sku", "price", "promo_price", "currency", "uom", "barcode", "template", "tag_id")},
                         sort_keys=True, separators=(",", ":"), allow_nan=False)
    return hashlib.sha256(payload.encode('utf-8')).hexdigest()

class ESLDeltaSyncPipeline:
    def __init__(self, watermark_db: dict, max_rate_per_min: int = 150):
        if max_rate_per_min <= 0:
            raise ValueError("Rate must be positive")
        self.watermark_db = watermark_db  # SKU -> {version: int, content_hash: str}
        self.max_rate_per_min = max_rate_per_min
        self.last_tx_time = 0.0

    def process_catalog_stream(self, incoming_feed: List[dict], dry_run: bool = True) -> dict:
        # Single-worker example: production needs a transactional per-SKU compare-and-set
        # and a durable outbox; never run concurrent writers against this plain dict.
        pending = {}
        for item in incoming_feed:
            version = item['version']
            if type(version) is not int or version < 1:
                raise ValueError("Positive monotonic integer version required")
            sku = item['sku']
            previous = pending.get(sku) or self.watermark_db.get(sku)
            if previous and version == previous['version'] and compute_sku_hash(item) != previous['content_hash']:
                raise ValueError("Conflicting payload for the same version")
            if previous and version <= previous['version']:
                continue
            current_hash = compute_sku_hash(item)
            pending[sku] = {'version': version, 'content_hash': current_hash, 'item': item}
        if dry_run:
            return {'mode': 'DRY_RUN', 'accepted_versions': len(pending)}
        sent = 0
        for sku, candidate in pending.items():
            previous = self.watermark_db.get(sku)
            if previous and candidate['version'] <= previous['version']:
                continue
            if not previous or candidate['content_hash'] != previous['content_hash']:
                delay = 60.0 / self.max_rate_per_min - (time.monotonic() - self.last_tx_time)
                if delay > 0:
                    time.sleep(delay)
                job = {'sku': sku, 'tag_id': candidate['item']['tag_id'],
                       'price_data': candidate['item'],
                       'idempotency_key': hashlib.sha256(f"{sku}:{candidate['version']}:{candidate['content_hash']}".encode()).hexdigest()}
                # Adapter must fa

… (full content is in the download package)