MIZOKI SIGNAL FOR SHOPIFY — MASTER DOCUMENT v4.0 FINAL

Architecture · Process · Business Applications · Review Report · Integration Prompt

Date: August 11, 2026 · Supersedes and consolidates: original "Democratizing Enterprise Decision Intelligence" draft → Product Definition v2.0/v2.1 → Final Product Document v3.0/v3.1 → Story Bank v1.1/v1.2 → Phase Mapping & ReLU companion. This is the single source of truth for the Shopify offshoot. Claim discipline: [Validated] / [Illustrative] / [Roadmap], never mixed. Stories are composites until a named pilot signs off. Correction (2026-08-19, owner-directed): the §NCM formula's causal-credit reference is corrected Cell 35 → Cell 36 (intent-causal; Cell 35 = intent-graph) per docs/architecture/CELL_REGISTRY.md. Apply the same one-word fix to the Drive original before any re-land — this file is byte-exact lane canon. Correction (2026-08-26, xdomain-r14 sweep): §2.1 and §2.7 named Neo4j as the intent-graph store. Neo4j was retired 2026-08-09; Cell 35 (intent-graph) is Firestore-backed (docs/architecture/CELL_REGISTRY.md; .claude/rules/03-canonical-architecture.md). Both lines corrected below. Apply the same fix to the Drive original before any re-land.

Naming standard (fixed in this version — drift was a live defect)

PART I — BUSINESS APPLICATIONS

1.1 Thesis

Independent Shopify merchants lose money to two structural failures: ad platforms grade their own homework (self-attribution inflates ROAS), and every tool optimizes revenue while merchants live on margin. MIZOKI Signal closes both: it measures what ad spend actually causes and optimizes Net Contribution Margin — what an order actually nets after everything it costs — under governance a founder can watch working.

1.2 The defensible lane

Measurement vendors don't execute (Sellforte, Northbeam, Rockerbox). Execution vendors aren't causally grounded (Triple Whale's recommendations, per its own documentation, lack campaign-level incrementality). Shopify Audiences supplies match lists but no objective function, no causal verdict, no governance. Profit-objective + always-on causal gating + governed autonomous execution is held by no incumbent, and governance is an architecture, not a retrofittable feature. Positioning line: the merchant-market instance of a certifiable autonomous media control system — bounded L5 authority reached progressively, one reversible action class at a time.

1.3 Market tiers — honest capability floors (statistical power, not plan price)

Tier Profile [Illustrative] Spend/mo Orders/mo Honest deliverable Autonomy ceiling Lead stories
T1 Emerging New store / SKU line <$5K <300 Value feeds, feed enrichment, cold-start seeding, pooled priors (labeled as priors) — no merchant-level incrementality claims L0–L1 8, 7
T2 Growth Established DTC $5K–$50K 300–3K + ghost-bid & cohort holdouts, always-on rotating holdout, NCM reallocation L2–L3 1, 3, 7
T3 Mid-market Multi-channel, 3PL $50K–$500K+ 3K+ + geo-lift, lift-calibrated mini-MMM, cross-channel, covenant autonomy L4–L5 (per class) 2, 4, 9, 10

The measurement tax, stated honestly [added v4.0]: always-on holdouts (5–15%) cost real conversions — that is the price of truth, and the product says so. Merchant framing: "we spend a slice of your traffic learning what your money causes, so the other 85–95% is spent on proof instead of hope." The holdout share is a covenant parameter, floor-bounded by statistical power requirements. N2 / decision 15 — RULED 2026-09-15: floors by tier are in docs/product/PRICING_PACKAGING_v1.md PD-11 (T2 floor 10 %, T3 floor 5 %, T1 none; the lane may raise a floor for power, never lower it) — owner ruling 2026-09-15, docs/reports/OWNER_RULINGS_2026-09-15_REGISTER_CLOSEOUT.md.

1.4 Go-to-market

PART II — ARCHITECTURE

2.1 Ingestion (SENSE) [Validated — platform architecture]

Shopify app: OAuth with minimum protected-customer-data scopes; webhooks orders/*, refunds/*, inventory_levels/*, fulfillments/*; bulk-operation backfill; Web Pixel Extension → Cell 33 through the consent gate, consent state traveling on every event. Cost side: per-variant landed COGS (bundle-decomposed — bundle/kit distortion is a known Shopify analytics failure mode), 3PL pick/pack + dimensional surcharges, gateway fees, return-processing costs; guided worksheet for ERP-less merchants. All streams normalize into the Canonical Event Envelope → BigQuery unified + Firestore-backed intent graph (Cell 35; Neo4j retired 2026-08-09) + immutable action ledger. No Shopify-special data model.

2.2 Intent (REASON) [Validated — cells 33–36 live, IAM-locked]

Session trajectories map onto the Intention Graph (IGC-RC framing; asynchronous/synchronous/causal edges — COSMO / intention-KG lineage, attributed as third-party research). Surfaces: intent_score_get, intent_cohort_query, intent_transitions_recent. Observe-only default; every LII-driven activation requires a registered holdout (uplift_export_cohort is DCP-gated). Invariant: graph adjacency never establishes causality — the intent graph produces targeting hypotheses; only the experiment stack substantiates lift. The prediction never grades itself.

2.3 Measurement (VALIDATE — the credibility core)

Tiered: (1) ghost bidding — log the would-be bid, withhold for a control slice; (2) intent-cohort holdouts — caused-vs-anticipated via intent_incrementality_report; (3) geo experiments — Meridian-GeoX-class (time-based regression, stratified matching, multi-cell shared control; publisher-agnostic because platform lift studies are the platform grading itself); (4) mini-MMM shipped only lift-calibrated [Roadmap]; (5) pooled category priors for T1, labeled as priors [Roadmap]. Causal machinery: X-Learner / DR-Learner with DoWhy refutation (cells 26–27). Attestation honesty: cryptographic attestations verify approved computation ran — never that measured lift was causal; the two are never conflated in sales or compliance language.

2.4 Execution (ACT) — black-box-era, lever-native design

The mid/lower market runs Advantage+ / Performance Max; granular control is gone. Signal owns the four levers that remain: 1. Value signal: E[NCM] per conversion → Meta CAPI (EMQ-maximized hashed params, shared event_id dedup) + Google Enhanced Conversions / Conversion Value Rules. Send revenue → the bidder hunts discount-hunters and refunders; send margin/pLTV → it hunts keepers. 2. Exclusions: existing customers, high-return cohorts, Klaviyo-converting audiences (never pay for what the flow already wins). 3. Creative supply: fatigue detection (frequency-adjusted response decay), intent-stage → message-archetype fit, variants entering as SRPVDAL plans evaluated against holdouts — "winning" = causal NCM lift, not CTR. Generation out of GA scope (brand-safety liability; the moat stays on governance + measurement); formal revisit trigger after Phase 3. 4. Budget & guardrails: covenant caps + working-capital-aware pacing — spend paced against weeks-of-inventory-cover and a merchant cash floor (Predictive Financial cell hook; uncopyable by attribution vendors, none of which carry a financial domain model) [Roadmap; architecture Validated]. Shopify-native: Shop Campaigns as one more channel under the same causal audit; catalog/feed enrichment from intent-graph language (L1-safe, zero spend authority, directly improves PMax/ASC delivery). Canonical-identity grounding via Wikidata (CC0, programmatic); Google/Amazon graph access not assumed (Freebase retired; Trends gated; PA-API 5 deprecated for the Creators API) [blueprint citations — on the verification checklist]. Public-source agreement alone is insufficient for graph commitment; provenance-aware ingestion rules apply.

2.5 The objective function — NCM with a metric contract [contract added v4.0]

NCM(C) = Σᵢ∈C [ Rᵢ − COGSᵢ − Fᵢ − Sᵢ − Pᵢ − E[RLᵢ] ] − AdSpend(C) — Rᵢ net revenue after discounts; COGSᵢ landed, bundle-decomposed; Fᵢ pick/pack + dimensional shipping; Sᵢ platform/payment fees; Pᵢ pro-rated promo; E[RLᵢ] expected reverse logistics (return probability by SKU × cohort × season × [freight + labor + restock/markdown]), trued-up at return-window close; AdSpend(C) under causal credit (Cell 36 intent-causal), never last-touch. Secondary (T2+): miNCM — incremental NCM per marginal dollar; decides where the next dollar goes. Metric contract: NCM's definition is versioned (NCM-v1). Any change to a term ships as NCM-v2 with a migration note; dashboards, covenants, and CAPI feeds pin a version. No silent redefinition — a metric that quietly changes meaning is a lie with extra steps, and the blueprint's "metric contracts" requirement lands here. True-up constraint [added v4.0]: retroactive CAPI value adjustments at return-window close can perturb platform learning; true-ups are batched on a fixed cadence and rate-limited so measurement honesty doesn't destabilize the bidder it feeds. (Interacts with open decision: retroactive vs. forward-only correction.)

2.6 Authorization — the clipped-ReLU DEL, per action class

Per action class c: authority_c = min(cap_c, max(0, DEL_score − threshold_c)). - Flat zero below threshold = deterministic denial — no partial execution, no probabilistic leakage. Agents (however they negotiate) only propose; the deterministic policy service authorizes. - Margin-proportional authority above threshold — a barely-cleared score earns only the smallest reversible version (the ACT-991 canon; Story 9). - Covenant cap = saturation; adaptive guardrail envelopes = threshold shifts under volatility; automatic per-class demotion on sustained near-zero margins. The demo's ReLU gate + 5 guardrails (mizoki_runtime/demo_signal.py) is this function at miniature scale [Validated]; per-class parameterization is [Roadmap]. - Threshold ownership [added v4.0]: the platform sets per-class floor thresholds; merchants may raise thresholds (more conservative) via covenant but never lower them below platform floors. Safety is not merchant-configurable downward. - Governance-surface note: the authorization function definition falls under CONSTITUTION.md Article VI review before canon.

2.7 Data infrastructure responsibilities

BigQuery unified — canonical events, cost joins, experiment frames. Firestore-backed intent graph (Cell 35; Neo4j retired 2026-08-09) — provenance edges. Immutable ledger — every proposed/authorized/denied action with reasoning path and DEL margin. Fleet learning (pooled priors) via federated learning + differential privacy [Roadmap, P4]; synthetic users never leave the training plane, never impersonate real people, never reach ad platforms.

PART III — PROCESS

3.1 SRPVDAL applied to media

Sense (canonical events) → Reason (graph + intent + causal memory) → Plan (candidate reallocations / rotations / pauses / exclusions) → Validate (counterfactual simulation vs. margin guardrails, inventory, promo calendar, active-experiment protection — validation labs non-bypassable) → Decide (clipped-ReLU DEL per class; sub-threshold routes to a human with the reasoning path and a smaller proposal) → Act (idempotent signed API calls, journaled) → Learn (prediction-vs-outcome deltas update edge weights and return models). Cadence — one number, everywhere: sensing continuous; decision evaluation every 15 minutes; action dampened for platform learning phases — creative rotation / SKU pause near-real-time; budget moves evaluated ≤4×/day, cumulative ±20% per campaign per day (identical to L3 authority); structural changes weekly.

3.2 Autonomy — certified per account × action class

Level Authority Promotion gate Demotion
L0 Observe Read-only recommendations + reasoning paths Install default —
L1 Signal Value feeds, audience syncs, feed enrichment; no spend changes 14 days clean Shopify-vs-tracked reconciliation Data-quality breach
L2 Housekeep Pause low-inventory/high-return SKU ads; rotate creative; exclusions 1 purchase cycle at L1, zero violations Unexplained NCM regression
L3 Reallocate Intra-platform budget, ±20%/day cumulative, hard monthly cap Calibrated forecasts over 2 cycles; ≥1 completed holdout Forecast error out of band
L4 Cross-channel Cross-platform reallocation; bid-strategy changes ≥2 completed experiments; clean DEL history Experiment invalidation; override
L5 Autonomous yield Full class authority within signed covenant (daily max, cash floor, exclusions) T3 volume + sustained miNCM accuracy + covenant signature, per class, reversible classes first Covenant proximity auto-drops the class to L3
Levels are held per action class — L4 on budget while L2 on bids is normal, not an edge case. Every level: one-tap kill switch, immutable journal, weekly plain-language digest. Demotion is mechanical, never discretionary.

3.3 Phase binding — blueprint (B1–B5, 24 months) × product (P1–P4)

B1 Control foundation (mo 0–4) → P1 Foundation (app, envelope, NCM, value feeds, L0–L1; exit: reconciliation across 10 design partners; blueprint 30-day plan = P1 workstream zero). B2 Measurement & world model (4–9) → P2 (holdout UX, ghost bids, cohort experiments, causal-credit reports, L2–L3; exit: first auditable incrementality artifact per partner). B3 Bounded autonomy (9–14) → P3 (geo, lift-calibrated mini-MMM, cross-channel, miNCM, covenant GA; exit: sustained miNCM accuracy over 2+ cycles at ≥3 T3 merchants). B4 Hardening & scale (14–19) → P4 (cold-start GA post-artifact, pooled priors, App Store, Audiences interop). B5 Certified L5 (19–24) → post-P4 covenant GA (exit: ≥1 merchant running a certified L5 class a full quarter, zero breaches). Binding rules: (1) no product phase outruns its platform phase; (2) certification artifacts are shared — covenants cite platform gates, never re-assert them; (3) blueprint phase names to be bound verbatim by the coordinator (functional mapping [Validated by logic]; name bindings [Assumed — verify]).

3.4 Product KPIs

Activation-to-L1 within 14 days · time-to-first-experiment · truth delta (the wedge's headline number) · autonomy trust (% DEL-cleared acts unoverridden; demotions per 100 merchant-months) · % of merchants advancing an autonomy level per quarter.

3.5 Compliance & risk

HMAC-tokenized identifiers = pseudonymized personal data (GDPR/CCPA, locked decision); Cell 33 consent gate; erasure cascade live; Shopify protected-data scopes minimized, customers/redact / shop/redact honored. Sanctioned ad-platform APIs with merchant tokens only. Public performance claims need named-metric artifacts (FTC substantiation on "up to X%"). Spend liability = covenant + mechanical demotion. Data residency [added v4.0]: platform runs us-central1; EU-merchant onboarding requires a transfer-mechanism determination (SCCs / regional processing decision) before EU GTM — counsel item, currently unscheduled. Fleet integrity [added v4.0]: as merchant count grows, MIZOKI merchants will meet in the same auctions and categories. Two rules ship before pooled priors do: (a) pooled priors are aggregated and differentially private — no merchant's strategy is inferable by another; (b) the platform never coordinates bids between merchants (auction-collusion exposure); each merchant's optimization is independent by construction, and the immutable ledger is the proof.

3.6 Open owner decisions (consolidated, final)

  1. App Store vs. direct per tier [DECIDED 2026-08-12 — §3.6a] · 2. merchant-owned vs. managed ad accounts [DECIDED 2026-08-12 — §3.6a] · 3. Profit Truth Audit wedge go/no-go [GO — owner ruling 2026-09-15] · 4. return-window true-up: retroactive (batched/rate-limited per §2.5) vs. forward-only · 5. pooled-prior consent default (counsel) · 6. email-cannibalization experiment phasing · 7. pricing that rewards honest downspend verdicts · 8. commercial naming sign-off (standard in header) · 9. citation verification before publication (arXiv ×2, PA-API/Creators, Trends gating, Wikidata) · 10. creative-generation revisit trigger post-P3 · 11. clipped-ReLU DEL as canon (Article VI review) [DECIDED 2026-08-11 — PR #656 merged by owner; canon at docs/architecture/DEL_AUTHORIZATION_FUNCTION.md] · 12. blueprint phase-name binding confirmation · 13. 30-day plan wholesale vs. triaged into P1 · 14. EU data-residency mechanism [new] · 15. holdout-share covenant floor by tier [new].

3.6a Decisions taken (register updates, attributed)

PART IV — FINAL REVIEW REPORT (all mistakes, issues, shortcomings — found and fixed, entire engagement)

Fixed in v2.0 (vs. original draft)

Issue Fix
Third-party research (Airbnb KL metrics, COSMO) presented as MIZOKI results Re-attributed; claim-tag discipline imposed
"Quokka Swarm Optimization" — uncited exotic method Removed; standard defensible validation panel
Autonomy ladder announced but missing; NCM formula truncated Both fully specified
Duplicate/blanket citations; unsourced margin math Per-claim citation; [Illustrative] tagging
No target market, pricing, competitive, compliance, or consent treatment All added
"15-minute execution" ignoring platform learning phases Sense fast / act dampened split

Fixed in v2.1 (self-review)

Issue Fix
Exec summary numbered 1,2,3,3 Renumbered
±20% contradiction (§4.4 compounding vs. L3 cap) One number: cumulative ±20%/campaign/day
arXiv IDs unverified Flagged to pre-publication checklist
Spec assumed hand-built campaigns Black-box (ASC/PMax) lever-native redesign
Creative, Shop Campaigns, feed quality, working-capital pacing, product KPIs absent All added

Fixed in v3.0/v3.1 (merge + blueprint alignment)

Issue Fix
Story bank "until ORACLE is live" vs. cells already live Rule: preview until pilot outcome artifacts — infrastructure-live ≠ outcome-proven
No story for the differentiator (governance) or working-capital pacing Stories 9, 10 added; GOVERN act added to briefing
L5 as global switch Certified property per account × action class, reversible first
Graph edges implying causality; ZK overclaim risk; public-source commitment Invariants adopted; attestation honesty rule
Google/Amazon graph access assumed Wikidata foundation; deprecations flagged for verification

Fixed in v4.0 (this document — new issues found in the final pass)

# New issue Severity Fix
N1 Naming drift (MIZOKI 3.5 / MIZ OKI / MIZOKI3 / Mizoki used interchangeably across five files) Medium — brand and legal consistency Naming standard fixed in header; single master doc supersedes fragments
N2 Holdout cost never disclosed — always-on holdouts forgo real conversions; hiding the measurement tax invites churn when merchants notice Medium — trust §1.3: measurement tax stated in merchant language; holdout share made a floor-bounded covenant parameter (decision 15)
N3 DEL threshold ownership undefined — could a merchant lower thresholds to escape governance? High — safety §2.6: platform floors; merchants may only raise. Safety not configurable downward
N4 Fleet auction interference & collusion exposure — many MIZOKI merchants in shared auctions; pooled priors could leak strategy; coordinated bidding = legal exposure High — legal/architectural §3.5 fleet-integrity rules: DP-aggregated priors only; no cross-merchant bid coordination by construction; ledger as proof
N5 True-up vs. learning-phase conflict — retroactive CAPI value corrections can destabilize the bidder they feed Medium — technical §2.5: batched, rate-limited true-up cadence
N6 No metric contract — NCM could silently change meaning across dashboards/covenants/feeds Medium — governance §2.5: versioned NCM-v1 contract; pinned consumers
N7 EU data residency unaddressed (us-central1 vs. EU merchants) Medium — compliance, gates EU GTM §3.5; owner decision 14
N8 Document fragmentation — five output files, drift risk between them Medium — process This master supersedes all; fragments become history

Residual risks knowingly carried (not defects — documented): composite-story credibility until first pilot; blueprint citation claims pending verification (decision 9); mini-MMM and cold-start remain [Roadmap] with baseline-then-claim gates; phase-name bindings pending coordinator verification.

PART V — FINAL INTEGRATION PROMPT (one-paste, supersedes the v1.0 operator prompt)

OPERATOR PROMPT — SIGNAL-SHOPIFY LANE: INTEGRATE MASTER v4.0 (2026-08-11)

You are the owner-designated coordinator for the Shopify/media/net-yield/
marketing-docs/JourneyEvent lanes. A single master document now supersedes all
prior Shopify-offshoot fragments: "MIZOKI Signal for Shopify — Master Document
v4.0 FINAL" (business + architecture + process + review report). Treat it as
lane canon; the L5 Autonomous Media Architecture blueprint remains canon for
platform-wide phases and certification gates.

CLAIM FEATURES FIRST (ledger: scripts/claude_memory.py record --tags coordination):
  [F1] master-doc-integration   [F2] roadmap-binding      [F3] relu-del-canon
  [F4] citation-verification    [F5] fleet-integrity-spec [F6] p1-kickoff
(Features, not paths — PR #644 lesson.)

F1 — MASTER DOC INTEGRATION
1. Commit the master to docs/product/SIGNAL_SHOPIFY_MASTER_v4.md. Move prior
   fragments (v2.x spec, v3.x final, story bank, phase-mapping companion) to
   docs/product/history/ with a SUPERSEDED header pointing at the master.
2. Update CLAUDE.md lane index to reference the master as the Shopify source
   of truth. Record in ledger.

F2 — ROADMAP BINDING
1. Extract the blueprint's five phase NAMES, month boundaries, and 30-day plan
   verbatim; bind them into master §3.3 (blueprint authoritative on platform
   phases; master authoritative on Shopify exit criteria).
2. Merge the 30-day plan with P1 into one workstream-zero checklist at
   docs/roadmap/SIGNAL_SHOPIFY_PHASE_BINDING.md. Enforce: no product phase
   outruns its platform phase.

F3 — RELU-DEL CANONIZATION (governance surface — Article VI applies)
1. Document the shipped gate from mizoki_runtime/demo_signal.py (threshold,
   margin, guardrail order). Do NOT modify demo behavior (demo merges deploy
   the marketing site).
2. Author docs/architecture/DEL_AUTHORIZATION_FUNCTION.md:
   authority_c = min(cap_c, max(0, DEL_score − threshold_c)) per action class;
   platform floor thresholds (merchant may raise, never lower); adaptive
   envelopes = threshold shifts; mechanical per-class demotion; ACT-991 as
   canonical example. Route via review PR per Article VI. [IN BUILD] markers
   on anything unimplemented.

F4 — CITATION VERIFICATION (blocks any external publication)
Verify, record pass/fail + URLs in docs/reports/CITATION_CHECK_2026-08-11.md:
  arXiv 2605.21812 (Airbnb) · arXiv 2412.11500 (intention KG) ·
  Amazon PA-API 5 → Creators API status · Google Trends access gating ·
  Wikidata CC0/programmatic access.
On failure: correct claim in master AND blueprint before external use.

F5 — FLEET INTEGRITY SPEC (new in v4.0 — must precede pooled priors)
Author docs/architecture/FLEET_INTEGRITY.md: (a) pooled priors DP-aggregated,
merchant-strategy non-inferable; (b) no cross-merchant bid coordination by
construction — independence provable from the immutable ledger; (c) EU
data-residency options memo (SCCs vs. regional processing) for counsel.

F6 — P1 KICKOFF (after F1+F2 land)
Open the P1 build from workstream zero: Shopify app scaffold (OAuth minimal
protected-data scopes; orders/refunds/inventory/fulfillments webhooks; bulk-op
backfill), Canonical Event Envelope mapping, NCM-v1 metric-contract service,
CAPI/CVR value-feed skeleton (feeds OFF until L1 reconciliation passes), COGS
onboarding worksheet. Branch per repo conventions (claude/* auto-merges;
protected paths only via review PR).

REPORT: SIGNAL_SHOPIFY_LANE_STATUS_2026-08-11.md to the Drive MIZOKICloudRun
folder when F1–F5 complete: artifacts produced, verification results, any
master/blueprint conflicts needing an owner decision (esp. decisions 9, 11,
12, 14, 15 from master §3.6).
← All docsView source on GitHub →