Migration Guideline · Storefront

Dawn → Horizon: Agentic Cart Functions

Move the legacy Dawn storefront (business logic in client JS + Script Editor) to Horizon's thin, blocks-native presentation — with cart, pricing, and checkout logic re-homed to server-side Shopify Functions and the Tool Runner, driveable by an agent under an AP2 mandate.

Pillar 1 + 8 · Forward-Deploy Backlog Stack: Orthogonal (Xano / JWE / Tool Runner) API pin: 2026-04
Immovable clock. Shopify Script Editor is removed as of 2026-06-30. Any reorder/hide-payment, shipping, or line-item-discount Script still live means that checkout logic has silently stopped. Pillar 1 (checkout-touching) and Pillar 8 (all Scripts → Functions) are the urgent thread — do these before the broader theme rebuild.
Point of Difference

GraphQL + GA4 Signals — one seismic move, not two chores

Enterprises are forced through two migrations they treat as unrelated: REST → GraphQL (2026 sunset) and GA4 Consent Mode v2 signals (four signals — ad_storage, analytics_storage, ad_user_data, ad_personalization — mandatory in the EEA). The seismic recognition: they are the same migration to one thing — a consent-gated, agent-addressable data plane.

Neither migration delivers the agent-ready plane alone; the value is the fusion.
MoveDeliversMissing alone
REST → GraphQLTyped, bulk, server-resolved data — machine-addressable, no REST rotReach without permission — the agent can query but not know what it may do
GA4 Consent Mode v2Consent as a first-class signal on every eventPermission without reach — data still un-queryable at scale
FusedEvery datum machine-addressable AND consent-qualified — exactly what autonomous AI workflows need

The fusion is only safe on the trust foundation this stack already carries:

FoundationWhat it guarantees for AI workflows
Orthogonal TrustConsent ⊥ access — the axes compose without coupling; the agent carries zero trust
Hexagonal TrustGraphQL plane behind ports; every consumer (agent, GA4, ESB, CDP, storefront) crosses one consent-enforcing port
Loop EngineeringThe agent's query loop re-checks consent every iteration, fail-closed — trust re-earned per loop, never inherited
Enterprise unlock: AI workflows that are powerful (reach all the data) and safe (consent lineage for GDPR Art. 28 / CPRA, re-verified per loop) — most stacks force that trade-off; the fused plane removes it. It coexists with your ESB / CDP — the GraphQL loop feeds Adobe AEP and the ESB, it doesn't replace them.
Compliance & Permissions

Enforcement is a benefit — revenue, trust, reputation

Compliance and permissions are not a cost center or a checkbox. Enforced at the data plane — fail-closed, per-loop — they protect revenue, compound trust, and defend reputation. Lead with the benefit; the mechanism is only how it is guaranteed.

Read the benefit first (column 1); the capability and enforcement are the proof.
BenefitCapabilityEnforcement
Ad ROAS preservedConsent Mode v2 signals keep measurement + remarketing legal — lost consent = lost signal = wasted spend4 signals required, fail-closed before analytics fire
Promotions run legallyOmnibus 30-day prior-lowest price — discount in the EU without fines or "fake sale" penaltiesprice-history ledger, read-gated
Market access retainedData rights (opt-out, export, delete) — the price of selling in the EU / California at allwired to live endpoints, fail-closed
Safe delegation → new revenueScoped, revocable per-tenant tokens + capability permissions — sell to teams and agencies without exposuredata-plane; revoke = instant 401
Agentic revenue, no rogue-agent riskAP2 mandate + agent permissions — unlock autonomous purchase safelyper-loop re-check, fail-closed
Enterprise deals unlockedPII-free audit trail — provable governance is what enterprise procurement requires before it can buyaudit by construction
The reframe: permissions enforcement converts compliance from risk and cost into revenue enablement and a trust asset. The governance is the reason the data is safe to open — which is the core offer: accessibility, made safe by construction.

1 · Why Horizon fits the Orthogonal Stack

Horizon is blocks-first: a blocks/ directory, nested blocks via {% content_for 'blocks' %}, per-component {% stylesheet %}/{% javascript %}, no framework runtime. That posture — thin presentation, logic pushed out — is the native Shopify endpoint for the stack, not a fight against it.

Each row is Dawn coupling absorbed by one orthogonal layer.
Dawn coupling (what breaks)Orthogonal layer that absorbs it
Business rules in section <script> / Script EditorExecution → Tool Runner (worker) + Shopify Functions
Cart / price math recomputed in browserData plane → server-resolved (cart-transform / draft order)
Product data hardcoded in LiquidSource of truth → hydrate from Xano PIM via GraphQL
Auth & gating in theme JSIdentity → JWE claim, derived server-side, never in Liquid
Brand look re-built per surfaceLook → Design Sync theme.css keys Horizon + all surfaces

2 · Agentic Cart Functions — Guideline

Two audiences hit the same cart: a human on the Horizon storefront and an agent acting under a mandate. The rule is that both cross the same server-side boundary — no logic path exists only in the browser.

2.1 · Script → Function replacement map

Legacy Script (removed 2026-06-30)Shopify FunctionRuns at
Reorder / hide payment methodspayment_customizationcheckout
Reorder / hide / rename shippingdelivery_customizationcheckout
Line-item / order discountproduct_discount / order_discountcart + checkout
Bundle / merge / expand linescart_transformcart
Block invalid cartscart_checkout_validationcart + checkout

Functions are Wasm, run server-side on Shopify's infra, and are deterministic + input-bounded — which is exactly why an agent can be allowed to trigger them: the merchant's rules hold regardless of who or what filled the cart.

2.2 · The agentic cart path

JWE claimAP2 mandate (consent-to-purchase)Tool Runner
add_to_cartcart_transform + discountagentic_checkoutFunctions enforce

The agent never asserts price, discount, or identity. It calls a tool; the tool decrypts the JWE claim, checks caps at the data plane, and submits a cart. Merchant Functions then apply pricing, payment, and shipping rules on the server — the same rules a human would hit. The AP2 mandate is the user's scoped, revocable authorization for the agent to transact, re-checked on each loop (fail-closed).

2.3 · Rules

  1. No money math in the browser. Price, tax, discount, and shipping totals are server-resolved (Function or draft order). Liquid renders the resolved number; it never computes it.
  2. One cart boundary for human and agent. The Tool Runner's add_to_cart/checkout tools hit the same Cart/Checkout as the storefront — never a private, unguarded path.
  3. Agent authority = mandate, not session. Authorization comes from the decrypted AP2 mandate + caps, re-verified every tool call. A prior grant is never inherited across the loop.
  4. Deterministic rules live in Functions. Anything that must hold for every cart (discounts, payment/shipping gating, bundle logic) is a Wasm Function — not worker code, not theme JS.
  5. Orchestration lives in the Tool Runner. Multi-step, stateful, or cross-system logic (PIM lookup, consent, settlement rail choice) is a worker tool — not a Function (Functions are input-bounded and side-effect-free).
  6. Catalog from PIM, not Liquid. PDP/collection hydrate from Xano via GraphQL; no product data hardcoded in templates.
  7. Consent gates the cart, not just analytics. The AP2 mandate + Consent Mode v2 signals must be present before an agent transacts; absent consent = fail-closed.
  8. Present as Horizon blocks. Cart, upsell, and PDP UI are theme blocks with per-component CSS/JS — thin presentation over the server-resolved state, themed by Design Sync tokens.

3 · Migration Checklist

Work top-to-bottom. Groups A–B are the hard-dated urgent thread; C–F are the Q3 spine.

A · Step-0 Audit Do first
Inventory Script Editor scripts
Every payment / shipping / discount Script → one checklist row in group B.
Grep theme for inline <script> business logic
Cart math, gating, price recompute, eligibility rules living in section/asset JS.
Find REST calls & hardcoded catalog data
Mark each for GraphQL + PIM hydration (group E).
List per-locale theme forks
Route to edge-translate instead of forked templates.
B · Scripts → Functions 2026-06-30
Payment Script → payment_customization
Reorder / hide / rename methods, moved server-side.
Shipping Script → delivery_customization
Discount Script → product_discount / order_discount
Bundle / merge logic → cart_transform
Cart guards → cart_checkout_validation
Deploy Functions + confirm active on live checkout
Verify each merchant rule fires with a real test cart, not just unit input.
C · Agentic cart wiring
Tool Runner add_to_cart / checkout hit the same Cart API
No private agent-only cart path.
AP2 mandate created + scoped + revocable
create_mandate → consent-to-purchase, bound to the JWE actor.
Caps re-checked every tool call (fail-closed)
Loop Engineering: trust re-earned per iteration, never inherited.
Redact tokens/mandates from tool-call logs
D · Horizon theme rebuild
Rebuild sections as Horizon blocks
blocks/ + content_for 'blocks'; per-component {% stylesheet %}/{% javascript %}.
Presentation is thin — no business logic in blocks
Wire Design Sync theme.css / tokens into the theme
One primary color keys the surface; UIkit BEM overlay for semantic/AEO structure.
Validate all Liquid
validate_theme — strip hallucinated syntax before deploy.
E · Data & identity spine Q3 2026
Hydrate PDP / collection from Xano PIM via GraphQL
Edge-cache inventory/price reads (search_products)
GID + portable UUID on every funnel entity
Server-side consent events keyed by UUID (CPRA / CMv2)
EU Omnibus 30-day prior-lowest price ledger
F · Security & verify
Managed install + token exchange (no pasted custom-app token)
Secrets in worker only; key-rotation cadence live
E2E: human checkout + agent checkout both pass the same Functions
Same discounts, same payment/shipping gating, same totals.
Pin API 2026-04; CI bump + version watch
Theme this in Brand Studio
One primary color + tokens key the Horizon theme and every other surface.