From 5578350756fb07a29a01b2c6a07731014d030d91 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:12:52 -0700
Subject: [PATCH 01/20] feat(analytics): add consent + event-tier columns
 (additive migration)

---
 202-config/Database/Tables/CoreTables.php |  3 ++
 202-config/Database/Tables/UserTables.php |  7 ++++
 202-config/functions-upgrade.php          | 51 ++++++++++++++++++++++-
 202-config/version.php                    |  2 +-
 tests/Messaging/MigrationColumnsTest.php  | 26 ++++++++++++
 5 files changed, 86 insertions(+), 3 deletions(-)
 create mode 100644 tests/Messaging/MigrationColumnsTest.php

diff --git a/202-config/Database/Tables/CoreTables.php b/202-config/Database/Tables/CoreTables.php
index 64dd684e..b90c3975 100644
--- a/202-config/Database/Tables/CoreTables.php
+++ b/202-config/Database/Tables/CoreTables.php
@@ -176,6 +176,8 @@ public static function messagingSync(): SchemaDefinition
         );
     }
 
+    // 202_messaging_events: queued behavioural events; `tier` marks
+    // essential (always sent) vs analytics (consent-gated) events.
     public static function messagingEvents(): SchemaDefinition
     {
         return SchemaBuilder::fromRawSql(
@@ -187,6 +189,7 @@ public static function messagingEvents(): SchemaDefinition
                 `metadata` json DEFAULT NULL,
                 `occurred_at` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
                 `client_token` varchar(64) NOT NULL,
+                `tier` enum('essential','analytics') NOT NULL DEFAULT 'analytics',
                 `delivery_status` enum('pending','sent','failed') NOT NULL DEFAULT 'pending',
                 `sync_attempts` int(11) NOT NULL DEFAULT '0',
                 PRIMARY KEY (`id`),
diff --git a/202-config/Database/Tables/UserTables.php b/202-config/Database/Tables/UserTables.php
index c7ee1be2..ca7f7ca5 100644
--- a/202-config/Database/Tables/UserTables.php
+++ b/202-config/Database/Tables/UserTables.php
@@ -140,6 +140,13 @@ public static function usersPref(): SchemaDefinition
                 `lpo_status` varchar(16) NOT NULL DEFAULT '',
                 `lpo_bridge_config` text DEFAULT NULL,
                 `lpo_ctx_kw` tinyint(1) NOT NULL DEFAULT '1',
+                `analytics_consent` enum('granted','denied','unset') NOT NULL DEFAULT 'unset',
+                `analytics_consent_at` datetime DEFAULT NULL,
+                `analytics_consent_source` varchar(32) DEFAULT NULL,
+                `email_marketing_consent` enum('granted','denied','unset') NOT NULL DEFAULT 'unset',
+                `email_marketing_consent_at` datetime DEFAULT NULL,
+                `eu_consent_prompt_seen` tinyint(1) NOT NULL DEFAULT '0',
+                `analytics_geo_is_eu` tinyint(1) DEFAULT NULL,
                 PRIMARY KEY (`user_id`)
             ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci"
         );
diff --git a/202-config/functions-upgrade.php b/202-config/functions-upgrade.php
index d9d541dc..65064492 100755
--- a/202-config/functions-upgrade.php
+++ b/202-config/functions-upgrade.php
@@ -3883,10 +3883,57 @@ public static function upgrade_databases($time_from)
             }
         }
 
+        if ($prosper202_version == '1.9.74') {
+
+            // Consent + product-analytics columns (additive, idempotent): two
+            // independent account-holder consent flags (analytics, email
+            // marketing) with audit metadata, the one-time EU prompt marker,
+            // the persisted EU geo flag for cron use, and the
+            // essential/analytics tier marker on queued messaging events.
+            // Guarded ALTERs so a partial failure retries cleanly on the
+            // next run.
+            $consent_ok = true;
+            foreach ([
+                ['202_users_pref', 'analytics_consent',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `analytics_consent` enum('granted','denied','unset') NOT NULL DEFAULT 'unset'"],
+                ['202_users_pref', 'analytics_consent_at',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `analytics_consent_at` datetime DEFAULT NULL"],
+                ['202_users_pref', 'analytics_consent_source',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `analytics_consent_source` varchar(32) DEFAULT NULL"],
+                ['202_users_pref', 'email_marketing_consent',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `email_marketing_consent` enum('granted','denied','unset') NOT NULL DEFAULT 'unset'"],
+                ['202_users_pref', 'email_marketing_consent_at',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `email_marketing_consent_at` datetime DEFAULT NULL"],
+                ['202_users_pref', 'eu_consent_prompt_seen',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `eu_consent_prompt_seen` tinyint(1) NOT NULL DEFAULT '0'"],
+                ['202_users_pref', 'analytics_geo_is_eu',
+                    "ALTER TABLE `202_users_pref` ADD COLUMN `analytics_geo_is_eu` tinyint(1) DEFAULT NULL"],
+                ['202_messaging_events', 'tier',
+                    "ALTER TABLE `202_messaging_events` ADD COLUMN `tier` enum('essential','analytics') NOT NULL DEFAULT 'analytics' AFTER `client_token`"],
+            ] as [$consent_table, $consent_column, $consent_sql]) {
+                $check = _upgrade_query("SHOW COLUMNS FROM `{$consent_table}` LIKE '{$consent_column}'");
+                $exists = ($check instanceof mysqli_result) && $check->num_rows > 0;
+                if (!$exists && _upgrade_query($consent_sql) === false) {
+                    $consent_ok = false;
+                    error_log("Prosper202 upgrade: failed consent/analytics alter on {$consent_table}.{$consent_column}");
+                }
+            }
+
+            if ($consent_ok) {
+                if (_upgrade_query("UPDATE 202_version SET version='1.9.75'") !== false) {
+                    $prosper202_version = '1.9.75';
+                } else {
+                    error_log('Prosper202 upgrade: added consent/analytics columns but failed to persist version 1.9.75; leaving version at 1.9.74 so the next run retries.');
+                }
+            } else {
+                error_log('Prosper202 upgrade: consent/analytics column migration incomplete; leaving version at 1.9.74 so the next run retries.');
+            }
+        }
+
         //This will enable p202 to downgrade to this version if installed over a newer version
-        if (version_compare((string) $prosper202_version, '1.9.74', '>')) {
+        if (version_compare((string) $prosper202_version, '1.9.75', '>')) {
 
-            $prosper202_version = '1.9.74';
+            $prosper202_version = '1.9.75';
             $sql = "UPDATE 202_version SET version='" . $prosper202_version . "'";
             $result = _upgrade_query($sql);
         }
diff --git a/202-config/version.php b/202-config/version.php
index dd02f0a6..a6cd5a13 100644
--- a/202-config/version.php
+++ b/202-config/version.php
@@ -6,7 +6,7 @@
 declare(strict_types=1);
 
 // Validate version format before defining
-$version_string = '1.9.74';
+$version_string = '1.9.75';
 if (!preg_match('/^\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?$/', $version_string)) {
     throw new Exception('Invalid version format: ' . $version_string);
 }
diff --git a/tests/Messaging/MigrationColumnsTest.php b/tests/Messaging/MigrationColumnsTest.php
new file mode 100644
index 00000000..7ca13eb8
--- /dev/null
+++ b/tests/Messaging/MigrationColumnsTest.php
@@ -0,0 +1,26 @@
+<?php
+// tests/Messaging/MigrationColumnsTest.php
+use PHPUnit\Framework\TestCase;
+
+final class MigrationColumnsTest extends TestCase
+{
+    public function test_upgrade_sql_adds_all_consent_columns(): void
+    {
+        $sql = file_get_contents(__DIR__ . '/../../202-config/functions-upgrade.php');
+        foreach ([
+            'analytics_consent', 'analytics_consent_at', 'analytics_consent_source',
+            'email_marketing_consent', 'email_marketing_consent_at',
+            'eu_consent_prompt_seen', 'analytics_geo_is_eu',
+        ] as $col) {
+            $this->assertStringContainsString($col, $sql, "upgrade missing column $col");
+        }
+    }
+
+    public function test_event_table_has_tier_column(): void
+    {
+        $files = glob(__DIR__ . '/../../202-config/Database/Tables/*.php');
+        $all = '';
+        foreach ($files as $f) { $all .= file_get_contents($f); }
+        $this->assertMatchesRegularExpression('/202_messaging_events.*tier/s', $all);
+    }
+}

From e4a5841da29cdc9512765d1263b12b038738f0a2 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:21:11 -0700
Subject: [PATCH 02/20] feat(analytics): add ConsentPolicy single-chokepoint
 gate

---
 202-config/Messaging/ConsentPolicy.class.php | 106 +++++++++++++++++++
 tests/Messaging/ConsentPolicyTest.php        |  39 +++++++
 2 files changed, 145 insertions(+)
 create mode 100644 202-config/Messaging/ConsentPolicy.class.php
 create mode 100644 tests/Messaging/ConsentPolicyTest.php

diff --git a/202-config/Messaging/ConsentPolicy.class.php b/202-config/Messaging/ConsentPolicy.class.php
new file mode 100644
index 00000000..5ff8caa5
--- /dev/null
+++ b/202-config/Messaging/ConsentPolicy.class.php
@@ -0,0 +1,106 @@
+<?php
+// 202-config/Messaging/ConsentPolicy.class.php
+// The single source of truth for whether analytics/marketing may proceed.
+// Nothing else reads the raw consent columns or EU status.
+
+final class ConsentPolicy
+{
+    /** Pure decision. No I/O. */
+    public static function decide(string $stored, bool $isEu, string $tier): bool
+    {
+        if ($tier === 'essential') {
+            return true;
+        }
+        // analytics tier
+        if ($stored === 'granted') { return true; }
+        if ($stored === 'denied')  { return false; }
+        // unset → on-by-default for non-EU, held for EU
+        return !$isEu;
+    }
+
+    public static function analyticsAllowed(mysqli $db, int $userId): bool
+    {
+        $row = self::loadPref($db, $userId);
+        return self::decide($row['analytics_consent'], $row['is_eu'], 'analytics');
+    }
+
+    public static function emailMarketingAllowed(mysqli $db, int $userId): bool
+    {
+        $row = self::loadPref($db, $userId);
+        // Marketing email never goes out on a bare default — require explicit grant.
+        return $row['email_marketing_consent'] === 'granted';
+    }
+
+    public static function needsEuPrompt(mysqli $db, int $userId): bool
+    {
+        $row = self::loadPref($db, $userId);
+        return $row['is_eu'] === true
+            && $row['analytics_consent'] === 'unset'
+            && $row['prompt_seen'] === false;
+    }
+
+    public static function record(mysqli $db, int $userId, string $flag, string $state, string $source): bool
+    {
+        if (!in_array($flag, ['analytics','email_marketing'], true)) { return false; }
+        if (!in_array($state, ['granted','denied'], true)) { return false; }
+        if ($flag === 'analytics') {
+            $sql = "UPDATE `202_users_pref`
+                       SET `analytics_consent` = ?, `analytics_consent_at` = NOW(),
+                           `analytics_consent_source` = ?, `eu_consent_prompt_seen` = 1
+                     WHERE `user_id` = ?";
+            $stmt = $db->prepare($sql);
+            if ($stmt === false) { return false; }
+            $stmt->bind_param('ssi', $state, $source, $userId);
+        } else {
+            $sql = "UPDATE `202_users_pref`
+                       SET `email_marketing_consent` = ?, `email_marketing_consent_at` = NOW()
+                     WHERE `user_id` = ?";
+            $stmt = $db->prepare($sql);
+            if ($stmt === false) { return false; }
+            $stmt->bind_param('si', $state, $userId);
+        }
+        $ok = $stmt->execute();
+        $stmt->close();
+        return (bool) $ok;
+    }
+
+    public static function rememberGeo(mysqli $db, int $userId, bool $isEu): bool
+    {
+        $stmt = $db->prepare("UPDATE `202_users_pref` SET `analytics_geo_is_eu` = ? WHERE `user_id` = ?");
+        if ($stmt === false) { return false; }
+        $v = $isEu ? 1 : 0;
+        $stmt->bind_param('ii', $v, $userId);
+        $ok = $stmt->execute();
+        $stmt->close();
+        return (bool) $ok;
+    }
+
+    /** @return array{analytics_consent:string,email_marketing_consent:string,is_eu:bool,prompt_seen:bool} */
+    private static function loadPref(mysqli $db, int $userId): array
+    {
+        $default = [
+            'analytics_consent' => 'unset',
+            'email_marketing_consent' => 'unset',
+            'is_eu' => false,          // unknown geo → treat as non-EU (Global Constraints)
+            'prompt_seen' => false,
+        ];
+        $stmt = $db->prepare(
+            "SELECT `analytics_consent`, `email_marketing_consent`, `analytics_geo_is_eu`, `eu_consent_prompt_seen`
+               FROM `202_users_pref` WHERE `user_id` = ? LIMIT 1"
+        );
+        if ($stmt === false) { return $default; }
+        $stmt->bind_param('i', $userId);
+        if (!$stmt->execute()) { $stmt->close(); return $default; }
+        $res = $stmt->get_result();
+        $row = $res ? $res->fetch_assoc() : null;
+        $stmt->close();
+        if (!$row) { return $default; }
+        return [
+            'analytics_consent' => $row['analytics_consent'] ?? 'unset',
+            'email_marketing_consent' => $row['email_marketing_consent'] ?? 'unset',
+            // NULL geo (unknown) → false per Global Constraints
+            'is_eu' => ((int) ($row['analytics_geo_is_eu'] ?? 0)) === 1,
+            'prompt_seen' => ((int) ($row['eu_consent_prompt_seen'] ?? 0)) === 1,
+        ];
+    }
+}
diff --git a/tests/Messaging/ConsentPolicyTest.php b/tests/Messaging/ConsentPolicyTest.php
new file mode 100644
index 00000000..d49c686f
--- /dev/null
+++ b/tests/Messaging/ConsentPolicyTest.php
@@ -0,0 +1,39 @@
+<?php
+// tests/Messaging/ConsentPolicyTest.php
+use PHPUnit\Framework\TestCase;
+require_once __DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php';
+
+final class ConsentPolicyTest extends TestCase
+{
+    // essential always flows regardless of consent/geo
+    public function test_essential_always_true(): void
+    {
+        foreach (['granted','denied','unset'] as $s) {
+            foreach ([true,false] as $eu) {
+                $this->assertTrue(ConsentPolicy::decide($s, $eu, 'essential'));
+            }
+        }
+    }
+
+    public function test_analytics_granted_always_true(): void
+    {
+        $this->assertTrue(ConsentPolicy::decide('granted', true, 'analytics'));
+        $this->assertTrue(ConsentPolicy::decide('granted', false, 'analytics'));
+    }
+
+    public function test_analytics_denied_always_false(): void
+    {
+        $this->assertFalse(ConsentPolicy::decide('denied', true, 'analytics'));
+        $this->assertFalse(ConsentPolicy::decide('denied', false, 'analytics'));
+    }
+
+    public function test_analytics_unset_non_eu_true(): void
+    {
+        $this->assertTrue(ConsentPolicy::decide('unset', false, 'analytics'));
+    }
+
+    public function test_analytics_unset_eu_false(): void
+    {
+        $this->assertFalse(ConsentPolicy::decide('unset', true, 'analytics'));
+    }
+}

From cf10b4817ca37cb304663d8fd6cde8681e013c65 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:26:02 -0700
Subject: [PATCH 03/20] feat(analytics): add UrlScrubber PII safety net for
 offer URLs

---
 202-config/Messaging/UrlScrubber.class.php | 37 ++++++++++++++++++++++
 tests/Messaging/UrlScrubberTest.php        | 33 +++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 202-config/Messaging/UrlScrubber.class.php
 create mode 100644 tests/Messaging/UrlScrubberTest.php

diff --git a/202-config/Messaging/UrlScrubber.class.php b/202-config/Messaging/UrlScrubber.class.php
new file mode 100644
index 00000000..7b409578
--- /dev/null
+++ b/202-config/Messaging/UrlScrubber.class.php
@@ -0,0 +1,37 @@
+<?php
+// 202-config/Messaging/UrlScrubber.class.php
+// Cheap belt-and-suspenders: offer URLs are templates and rarely hold PII,
+// but redact any hardcoded email/phone param VALUES before sync just in case.
+
+final class UrlScrubber
+{
+    private const EMAIL = '/^[^@\s]+@[^@\s]+\.[^@\s]+$/';
+    private const PHONE = '/^\+?[0-9][0-9\-\.\s\(\)]{6,}$/';
+
+    public static function scrub(string $url): string
+    {
+        $q = parse_url($url, PHP_URL_QUERY);
+        if ($q === null || $q === false || $q === '') {
+            return $url;
+        }
+        parse_str($q, $params);
+        $changed = false;
+        foreach ($params as $k => $v) {
+            if (!is_string($v)) { continue; }
+            // parse_str already urldecodes ('+' becomes a space); trim so a
+            // leading space from an encoded '+' doesn't defeat the anchors.
+            $decoded = trim(rawurldecode($v));
+            if (preg_match(self::EMAIL, $decoded) || preg_match(self::PHONE, $decoded)) {
+                $params[$k] = '[redacted]';
+                $changed = true;
+            }
+        }
+        if (!$changed) { return $url; }
+        // http_build_query urlencodes {macros}; only touch params if we actually redacted,
+        // and rebuild only the query portion to preserve the rest of the URL.
+        $rebuilt = http_build_query($params);
+        $base = strtok($url, '?');
+        $frag = parse_url($url, PHP_URL_FRAGMENT);
+        return $base . '?' . $rebuilt . ($frag !== null && $frag !== false ? '#' . $frag : '');
+    }
+}
diff --git a/tests/Messaging/UrlScrubberTest.php b/tests/Messaging/UrlScrubberTest.php
new file mode 100644
index 00000000..944128f4
--- /dev/null
+++ b/tests/Messaging/UrlScrubberTest.php
@@ -0,0 +1,33 @@
+<?php
+// tests/Messaging/UrlScrubberTest.php
+use PHPUnit\Framework\TestCase;
+require_once __DIR__ . '/../../202-config/Messaging/UrlScrubber.class.php';
+
+final class UrlScrubberTest extends TestCase
+{
+    public function test_redacts_email_value(): void
+    {
+        $out = UrlScrubber::scrub('https://x.com/o?s2=foo%40bar.com&c=1');
+        $this->assertStringNotContainsString('bar.com', $out);
+        $this->assertStringContainsString('s2=%5Bredacted%5D', $out); // [redacted] urlencoded
+        $this->assertStringContainsString('c=1', $out);
+    }
+
+    public function test_redacts_phone_value(): void
+    {
+        $out = UrlScrubber::scrub('https://x.com/o?p=+14155551234');
+        $this->assertStringNotContainsString('4155551234', $out);
+    }
+
+    public function test_leaves_macro_token_untouched(): void
+    {
+        $url = 'https://x.com/o?s1={clickid}&aff=42';
+        $this->assertSame($url, UrlScrubber::scrub($url));
+    }
+
+    public function test_no_query_returned_unchanged(): void
+    {
+        $url = 'https://x.com/landing';
+        $this->assertSame($url, UrlScrubber::scrub($url));
+    }
+}

From 50984302fc795446c3f90880e514958567317fcc Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:33:49 -0700
Subject: [PATCH 04/20] feat(analytics): add gated Analytics facade over
 MessagingService

---
 202-config/Messaging/Analytics.class.php      | 60 +++++++++++++++++++
 .../Messaging/MessagingService.class.php      | 14 +++--
 tests/Messaging/AnalyticsGateTest.php         | 22 +++++++
 3 files changed, 92 insertions(+), 4 deletions(-)
 create mode 100644 202-config/Messaging/Analytics.class.php
 create mode 100644 tests/Messaging/AnalyticsGateTest.php

diff --git a/202-config/Messaging/Analytics.class.php b/202-config/Messaging/Analytics.class.php
new file mode 100644
index 00000000..ce62d05b
--- /dev/null
+++ b/202-config/Messaging/Analytics.class.php
@@ -0,0 +1,60 @@
+<?php
+// 202-config/Messaging/Analytics.class.php
+require_once __DIR__ . '/ConsentPolicy.class.php';
+require_once __DIR__ . '/MessagingService.class.php';
+
+final class Analytics
+{
+    /** Pure gate, delegates to ConsentPolicy. Exposed for testing. */
+    public static function gate(string $stored, bool $isEu, string $tier): bool
+    {
+        return ConsentPolicy::decide($stored, $isEu, $tier);
+    }
+
+    public static function event(string $name, array $meta = [], string $tier = 'analytics'): void
+    {
+        self::guarded(function (mysqli $db, int $uid) use ($name, $meta, $tier) {
+            if ($tier === 'analytics' && !ConsentPolicy::analyticsAllowed($db, $uid)) {
+                return;
+            }
+            $service = new MessagingService($db, $uid, []);
+            // MessagingService::recordEvent persists to 202_messaging_events; pass tier through.
+            $service->recordEvent($name, $meta, $tier);
+        });
+    }
+
+    public static function attr(array $attributes, string $tier = 'analytics'): void
+    {
+        self::guarded(function (mysqli $db, int $uid) use ($attributes, $tier) {
+            if ($tier === 'analytics' && !ConsentPolicy::analyticsAllowed($db, $uid)) {
+                return;
+            }
+            $service = new MessagingService($db, $uid, []);
+            $service->updateAttributes($attributes);
+        });
+    }
+
+    /** Thin testable wrapper: would a write of this tier be recorded for this user? */
+    public static function wouldRecord(mysqli $db, int $userId, string $tier): bool
+    {
+        if ($tier !== 'analytics') {
+            return true;
+        }
+        return ConsentPolicy::analyticsAllowed($db, $userId);
+    }
+
+    private static function guarded(callable $fn): void
+    {
+        try {
+            $db = $GLOBALS['db'] ?? null;
+            $uid = (int) ($_SESSION['user_id'] ?? 0);
+            if (!($db instanceof mysqli) || $uid <= 0) { return; }
+            $fn($db, $uid);
+        } catch (\Throwable $e) {
+            // Never let tracking break a host page. Log if a logger exists; otherwise swallow.
+            if (function_exists('error_log')) {
+                error_log('[Analytics] ' . $e->getMessage());
+            }
+        }
+    }
+}
diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index 7ea978ce..43d7b148 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -790,14 +790,20 @@ public function updateAttributes(array $attributes): void
      * Record a behavioural event for later delivery to the central server.
      *
      * @param array<string,mixed>|null $metadata
+     * @param string                   $tier     'essential' or 'analytics' (202_messaging_events.tier).
      */
-    public function recordEvent(string $name, ?array $metadata = null): void
+    public function recordEvent(string $name, ?array $metadata = null, string $tier = 'analytics'): void
     {
         $name = trim($name);
         if ($name === '') {
             return;
         }
 
+        // Guard the ENUM: an unknown tier would fail the INSERT under strict mode.
+        if (!in_array($tier, ['essential', 'analytics'], true)) {
+            $tier = 'analytics';
+        }
+
         $metaJson = null;
         if ($metadata !== null && $metadata !== []) {
             $encoded = json_encode($metadata);
@@ -811,14 +817,14 @@ public function recordEvent(string $name, ?array $metadata = null): void
         $token = $this->generateToken();
         $now   = date('Y-m-d H:i:s');
         $sql   = "INSERT INTO 202_messaging_events
-                    (user_id, event_name, metadata, occurred_at, client_token, delivery_status)
-                  VALUES (?, ?, ?, ?, ?, 'pending')";
+                    (user_id, event_name, metadata, occurred_at, client_token, delivery_status, tier)
+                  VALUES (?, ?, ?, ?, ?, 'pending', ?)";
         $stmt = $this->db->prepare($sql);
         if (!$stmt) {
             error_log('MessagingService: prepare recordEvent failed');
             return;
         }
-        $stmt->bind_param('issss', $this->userId, $name, $metaJson, $now, $token);
+        $stmt->bind_param('isssss', $this->userId, $name, $metaJson, $now, $token, $tier);
         if (!$stmt->execute()) {
             error_log('MessagingService: recordEvent failed');
         }
diff --git a/tests/Messaging/AnalyticsGateTest.php b/tests/Messaging/AnalyticsGateTest.php
new file mode 100644
index 00000000..e726e9fd
--- /dev/null
+++ b/tests/Messaging/AnalyticsGateTest.php
@@ -0,0 +1,22 @@
+<?php
+// tests/Messaging/AnalyticsGateTest.php
+use PHPUnit\Framework\TestCase;
+require_once __DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/Analytics.class.php';
+
+final class AnalyticsGateTest extends TestCase
+{
+    // The gate Analytics applies must equal ConsentPolicy::decide for the tier.
+    public function test_gate_matches_policy_for_analytics_unset_eu(): void
+    {
+        $this->assertFalse(Analytics::gate('unset', true, 'analytics'));
+    }
+    public function test_gate_essential_always_true(): void
+    {
+        $this->assertTrue(Analytics::gate('denied', true, 'essential'));
+    }
+    public function test_gate_analytics_granted(): void
+    {
+        $this->assertTrue(Analytics::gate('granted', true, 'analytics'));
+    }
+}

From 3a53b045cc3ce6f60e6bcde2dc072d0369bfef3c Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:41:40 -0700
Subject: [PATCH 05/20] fix(analytics): close unknown-tier consent bypass in
 Analytics facade

Normalize tiers in Analytics with ConsentPolicy::decide semantics
(anything not 'essential' is 'analytics' and consent-gated), route
event()/attr() gating through wouldRecord(), and make
MessagingService::recordEvent() reject unknown tiers with a log
instead of silently coercing them to 'analytics'.
---
 202-config/Messaging/Analytics.class.php       | 18 +++++++++++++++---
 .../Messaging/MessagingService.class.php       |  7 +++++--
 tests/Messaging/AnalyticsGateTest.php          | 17 +++++++++++++++++
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/202-config/Messaging/Analytics.class.php b/202-config/Messaging/Analytics.class.php
index ce62d05b..ef4be3af 100644
--- a/202-config/Messaging/Analytics.class.php
+++ b/202-config/Messaging/Analytics.class.php
@@ -11,10 +11,22 @@ public static function gate(string $stored, bool $isEu, string $tier): bool
         return ConsentPolicy::decide($stored, $isEu, $tier);
     }
 
+    /**
+     * Normalize a tier with the same semantics as ConsentPolicy::decide:
+     * anything that is not exactly 'essential' is treated as 'analytics'
+     * and therefore consent-gated. Never fail open on a typo or a future
+     * tier name. Exposed for testing.
+     */
+    public static function normalizeTier(string $tier): string
+    {
+        return $tier === 'essential' ? 'essential' : 'analytics';
+    }
+
     public static function event(string $name, array $meta = [], string $tier = 'analytics'): void
     {
         self::guarded(function (mysqli $db, int $uid) use ($name, $meta, $tier) {
-            if ($tier === 'analytics' && !ConsentPolicy::analyticsAllowed($db, $uid)) {
+            $tier = self::normalizeTier($tier);
+            if (!self::wouldRecord($db, $uid, $tier)) {
                 return;
             }
             $service = new MessagingService($db, $uid, []);
@@ -26,7 +38,7 @@ public static function event(string $name, array $meta = [], string $tier = 'ana
     public static function attr(array $attributes, string $tier = 'analytics'): void
     {
         self::guarded(function (mysqli $db, int $uid) use ($attributes, $tier) {
-            if ($tier === 'analytics' && !ConsentPolicy::analyticsAllowed($db, $uid)) {
+            if (!self::wouldRecord($db, $uid, self::normalizeTier($tier))) {
                 return;
             }
             $service = new MessagingService($db, $uid, []);
@@ -37,7 +49,7 @@ public static function attr(array $attributes, string $tier = 'analytics'): void
     /** Thin testable wrapper: would a write of this tier be recorded for this user? */
     public static function wouldRecord(mysqli $db, int $userId, string $tier): bool
     {
-        if ($tier !== 'analytics') {
+        if (self::normalizeTier($tier) === 'essential') {
             return true;
         }
         return ConsentPolicy::analyticsAllowed($db, $userId);
diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index 43d7b148..b9ebccac 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -799,9 +799,12 @@ public function recordEvent(string $name, ?array $metadata = null, string $tier
             return;
         }
 
-        // Guard the ENUM: an unknown tier would fail the INSERT under strict mode.
+        // Reject unknown tiers loudly: silently coercing would persist data
+        // as consent-gated 'analytics' without ConsentPolicy ever being
+        // consulted. Callers must normalize (see Analytics::normalizeTier).
         if (!in_array($tier, ['essential', 'analytics'], true)) {
-            $tier = 'analytics';
+            error_log("MessagingService: recordEvent rejected unknown tier '{$tier}' for event '{$name}'");
+            return;
         }
 
         $metaJson = null;
diff --git a/tests/Messaging/AnalyticsGateTest.php b/tests/Messaging/AnalyticsGateTest.php
index e726e9fd..f62a3c08 100644
--- a/tests/Messaging/AnalyticsGateTest.php
+++ b/tests/Messaging/AnalyticsGateTest.php
@@ -19,4 +19,21 @@ public function test_gate_analytics_granted(): void
     {
         $this->assertTrue(Analytics::gate('granted', true, 'analytics'));
     }
+    // Unknown tiers must not bypass the gate: anything not 'essential'
+    // normalizes to 'analytics' and is consent-gated (matches decide()).
+    public function test_normalize_tier_treats_unknown_as_analytics(): void
+    {
+        $this->assertSame('analytics', Analytics::normalizeTier('analytic'));
+        $this->assertSame('analytics', Analytics::normalizeTier('marketing'));
+        $this->assertSame('analytics', Analytics::normalizeTier(''));
+        $this->assertSame('analytics', Analytics::normalizeTier('Essential'));
+        $this->assertSame('essential', Analytics::normalizeTier('essential'));
+        $this->assertSame('analytics', Analytics::normalizeTier('analytics'));
+    }
+    public function test_gate_unknown_tier_is_gated_like_analytics(): void
+    {
+        $this->assertFalse(Analytics::gate('denied', false, Analytics::normalizeTier('marketing')));
+        $this->assertFalse(Analytics::gate('unset', true, Analytics::normalizeTier('analytic')));
+        $this->assertTrue(Analytics::gate('granted', true, Analytics::normalizeTier('marketing')));
+    }
 }

From da844726c2ae4c12e3a34f88a232422cfb5583ea Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:49:19 -0700
Subject: [PATCH 06/20] fix(analytics): gate client track.php through
 ConsentPolicy, reject bad JSON

---
 202-account/ajax/messaging/track.php       | 29 +++++++++++-----------
 tests/Messaging/TrackEndpointGuardTest.php | 20 +++++++++++++++
 2 files changed, 34 insertions(+), 15 deletions(-)
 create mode 100644 tests/Messaging/TrackEndpointGuardTest.php

diff --git a/202-account/ajax/messaging/track.php b/202-account/ajax/messaging/track.php
index d810a663..12b75ec5 100644
--- a/202-account/ajax/messaging/track.php
+++ b/202-account/ajax/messaging/track.php
@@ -5,6 +5,7 @@
 include_once(str_repeat('../', 3) . '202-config/connect.php');
 
 require __DIR__ . '/_auth.php';
+require_once dirname(__DIR__, 3) . '/202-config/Messaging/Analytics.class.php';
 
 header('Content-Type: application/json');
 
@@ -15,12 +16,10 @@
     exit;
 }
 
-$userId  = $messagingUserId;
-$service = MessagingService::forUser($userId);
-
-if ($service === null) {
-    http_response_code(409);
-    echo json_encode(['ok' => false, 'error' => 'messaging unavailable for this account']);
+// --- analytics consent gate: client events are analytics-tier ---
+require_once dirname(__DIR__, 3) . '/202-config/Messaging/ConsentPolicy.class.php';
+if (!ConsentPolicy::analyticsAllowed($db, $messagingUserId)) {
+    echo json_encode(['ok' => true, 'recorded' => false, 'reason' => 'analytics_not_consented']);
     exit;
 }
 
@@ -28,29 +27,29 @@
 
 // 1. Custom attributes for segmentation: Prosper202Messenger('update', {...})
 if (isset($_POST['update']) && $_POST['update'] !== '') {
-    $attributes = json_decode((string) $_POST['update'], true);
+    $decoded = json_decode((string) $_POST['update'], true);
     // Reject malformed input explicitly rather than silently ignoring it (CLAUDE.md #4).
-    if (json_last_error() !== JSON_ERROR_NONE || !is_array($attributes)) {
+    if (json_last_error() !== JSON_ERROR_NONE || !is_array($decoded)) {
         http_response_code(400);
-        echo json_encode(['ok' => false, 'error' => 'update must be a JSON object']);
+        echo json_encode(['ok' => false, 'error' => 'invalid_update_json']);
         exit;
     }
-    $service->updateAttributes($attributes);
+    Analytics::attr($decoded, 'analytics');
     $handled = true;
 }
 
 // 2. Behavioural event: Prosper202Messenger('trackEvent', name, metadata)
 if (isset($_POST['event_name']) && trim((string) $_POST['event_name']) !== '') {
-    $metadata = null;
+    $meta = [];
     if (isset($_POST['metadata']) && $_POST['metadata'] !== '') {
-        $metadata = json_decode((string) $_POST['metadata'], true);
-        if (json_last_error() !== JSON_ERROR_NONE || !is_array($metadata)) {
+        $meta = json_decode((string) $_POST['metadata'], true);
+        if (json_last_error() !== JSON_ERROR_NONE || !is_array($meta)) {
             http_response_code(400);
-            echo json_encode(['ok' => false, 'error' => 'metadata must be a JSON object']);
+            echo json_encode(['ok' => false, 'error' => 'invalid_metadata_json']);
             exit;
         }
     }
-    $service->recordEvent((string) $_POST['event_name'], $metadata);
+    Analytics::event((string) $_POST['event_name'], $meta, 'analytics');
     $handled = true;
 }
 
diff --git a/tests/Messaging/TrackEndpointGuardTest.php b/tests/Messaging/TrackEndpointGuardTest.php
new file mode 100644
index 00000000..4bec5dde
--- /dev/null
+++ b/tests/Messaging/TrackEndpointGuardTest.php
@@ -0,0 +1,20 @@
+<?php
+// tests/Messaging/TrackEndpointGuardTest.php
+use PHPUnit\Framework\TestCase;
+
+final class TrackEndpointGuardTest extends TestCase
+{
+    public function test_track_php_consults_consent_policy(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-account/ajax/messaging/track.php');
+        $this->assertStringContainsString('ConsentPolicy::analyticsAllowed', $src,
+            'track.php must gate analytics writes through ConsentPolicy');
+    }
+
+    public function test_track_php_rejects_malformed_json_explicitly(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-account/ajax/messaging/track.php');
+        // must NOT silently swallow bad JSON with "?? []"
+        $this->assertDoesNotMatchRegularExpression('/json_decode\([^;]*\)\s*\?\?\s*\[\]/', $src);
+    }
+}

From 52b71e8b3b5e08447f4208a15b6408f4d2bb6704 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 22:59:59 -0700
Subject: [PATCH 07/20] feat(analytics): server-side page_viewed + persist
 account EU geo at login

---
 202-config/functions-auth.php          | 14 ++++++++++++++
 202-config/template.php                |  6 ++++++
 tests/Messaging/PageViewWiringTest.php | 17 +++++++++++++++++
 3 files changed, 37 insertions(+)
 create mode 100644 tests/Messaging/PageViewWiringTest.php

diff --git a/202-config/functions-auth.php b/202-config/functions-auth.php
index d9290b89..7aa55c55 100755
--- a/202-config/functions-auth.php
+++ b/202-config/functions-auth.php
@@ -266,6 +266,20 @@ public static function begin_user_session(array $user_row): void
         }
 
         self::$sessionHeartbeatRefreshed = true;
+
+        // Persist the account holder's EU status once known (unknown → non-EU).
+        // Tracking must never break login: guard the connection and swallow failures.
+        try {
+            require_once __DIR__ . '/Messaging/ConsentPolicy.class.php';
+            $db = $GLOBALS['db'] ?? null;
+            if (isset($db) && $db instanceof \mysqli && !empty($_SESSION['user_id'])) {
+                if (!ConsentPolicy::rememberGeo($db, (int) $_SESSION['user_id'], !empty($_SESSION['is_european_union']))) {
+                    error_log('[ConsentPolicy] rememberGeo at login failed for user ' . (int) $_SESSION['user_id']);
+                }
+            }
+        } catch (\Throwable $e) {
+            error_log('[ConsentPolicy] rememberGeo at login failed: ' . $e->getMessage());
+        }
     }
 
     /**
diff --git a/202-config/template.php b/202-config/template.php
index 59d2c0b0..e7830e2d 100755
--- a/202-config/template.php
+++ b/202-config/template.php
@@ -501,6 +501,12 @@ function template_bottom()
 			});
 		</script>
 		<?php if (!empty($_SESSION['user_id'])) { ?>
+			<?php
+			// Server-side page-view (analytics tier → self-gates on consent).
+			require_once __DIR__ . '/Messaging/Analytics.class.php';
+			$p202_route = parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH) ?: 'unknown';
+			Analytics::event('page_viewed', ['path' => $p202_route], 'analytics');
+			?>
 			<!-- Prosper202 Messenger: config + command-queue stub + widget -->
 			<script type="text/javascript">
 				window.P202M_CONFIG = {
diff --git a/tests/Messaging/PageViewWiringTest.php b/tests/Messaging/PageViewWiringTest.php
new file mode 100644
index 00000000..47432aa7
--- /dev/null
+++ b/tests/Messaging/PageViewWiringTest.php
@@ -0,0 +1,17 @@
+<?php
+// tests/Messaging/PageViewWiringTest.php
+use PHPUnit\Framework\TestCase;
+
+final class PageViewWiringTest extends TestCase
+{
+    public function test_template_records_page_view(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-config/template.php');
+        $this->assertStringContainsString("Analytics::event('page_viewed'", $src);
+    }
+    public function test_login_persists_eu_geo(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-config/functions-auth.php');
+        $this->assertStringContainsString('ConsentPolicy::rememberGeo', $src);
+    }
+}

From c278a311b011f13154d1310d93b15539fd69398c Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 23:11:42 -0700
Subject: [PATCH 08/20] fix(analytics): compute EU geo from client IP at login
 instead of dead session flag

$_SESSION['is_european_union'] is never assigned anywhere, so rememberGeo
always persisted analytics_geo_is_eu = 0 and the EU consent prompt could
never fire. Look the status up via the GeoIp2 reader on AUTH::client_ip()
(getGeoData lives in connect2.php, which the login bootstrap never loads),
and only persist a definitive result so an unknown lookup never flattens a
previously known value.
---
 202-config/functions-auth.php          | 51 ++++++++++++++++++++++++--
 tests/Messaging/PageViewWiringTest.php | 17 +++++++++
 2 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/202-config/functions-auth.php b/202-config/functions-auth.php
index 7aa55c55..af3f1573 100755
--- a/202-config/functions-auth.php
+++ b/202-config/functions-auth.php
@@ -267,13 +267,17 @@ public static function begin_user_session(array $user_row): void
 
         self::$sessionHeartbeatRefreshed = true;
 
-        // Persist the account holder's EU status once known (unknown → non-EU).
-        // Tracking must never break login: guard the connection and swallow failures.
+        // Persist the account holder's EU status, looked up from the client IP
+        // (no session flag carries this — it must be computed here). Only a
+        // definitive lookup is persisted so an unknown result never flattens a
+        // previously known value. Tracking must never break login: guard the
+        // connection and swallow failures.
         try {
             require_once __DIR__ . '/Messaging/ConsentPolicy.class.php';
             $db = $GLOBALS['db'] ?? null;
-            if (isset($db) && $db instanceof \mysqli && !empty($_SESSION['user_id'])) {
-                if (!ConsentPolicy::rememberGeo($db, (int) $_SESSION['user_id'], !empty($_SESSION['is_european_union']))) {
+            if ($db instanceof \mysqli && !empty($_SESSION['user_id'])) {
+                $is_eu = self::detect_client_is_eu();
+                if ($is_eu !== null && !ConsentPolicy::rememberGeo($db, (int) $_SESSION['user_id'], $is_eu)) {
                     error_log('[ConsentPolicy] rememberGeo at login failed for user ' . (int) $_SESSION['user_id']);
                 }
             }
@@ -282,6 +286,45 @@ public static function begin_user_session(array $user_row): void
         }
     }
 
+    /**
+     * Whether the current request's client IP is inside the European Union,
+     * per the bundled GeoLite2 database. Uses the GeoIp2 reader directly:
+     * getGeoData() lives in connect2.php, which the UI/login bootstrap
+     * (connect.php) never includes, so it does not exist on this path.
+     * Returns true/false only when the lookup succeeded and resolved a
+     * country; null when geo data is unavailable or inconclusive so callers
+     * can skip persisting instead of overwriting a known value.
+     */
+    private static function detect_client_is_eu(): ?bool
+    {
+        if (!class_exists(\GeoIp2\Database\Reader::class)) {
+            return null;
+        }
+
+        $mmdb = __DIR__ . '/geo/GeoLite2-City.mmdb';
+        if (!is_readable($mmdb)) {
+            return null;
+        }
+
+        $reader = null;
+        try {
+            $reader = new \GeoIp2\Database\Reader($mmdb);
+            $record = $reader->city(self::client_ip());
+            // Only trust the EU flag when the country actually resolved;
+            // isInEuropeanUnion defaults to false on absent data.
+            if (($record->country->isoCode ?? null) === null) {
+                return null;
+            }
+            return (bool) $record->country->isInEuropeanUnion;
+        } catch (\Throwable) {
+            return null; // Private/unroutable IP, bad DB, etc. → inconclusive.
+        } finally {
+            if ($reader !== null) {
+                $reader->close();
+            }
+        }
+    }
+
     /**
      * True if the request has an authenticated user, restoring a session from a
      * valid remember-me cookie if needed. This is the single source of truth for
diff --git a/tests/Messaging/PageViewWiringTest.php b/tests/Messaging/PageViewWiringTest.php
index 47432aa7..71eff6fb 100644
--- a/tests/Messaging/PageViewWiringTest.php
+++ b/tests/Messaging/PageViewWiringTest.php
@@ -13,5 +13,22 @@ public function test_login_persists_eu_geo(): void
     {
         $src = file_get_contents(__DIR__ . '/../../202-config/functions-auth.php');
         $this->assertStringContainsString('ConsentPolicy::rememberGeo', $src);
+        // EU status must be computed from the client IP via the GeoIP reader.
+        // $_SESSION['is_european_union'] is never assigned anywhere, so reading
+        // it would persist analytics_geo_is_eu = 0 for every account; and
+        // getGeoData() (connect2.php) is not loaded by the login bootstrap.
+        $this->assertStringContainsString('GeoIp2\Database\Reader', $src);
+        $this->assertStringContainsString('self::client_ip()', $src);
+        $this->assertStringNotContainsString("\$_SESSION['is_european_union']", $src);
+    }
+
+    public function test_eu_detection_skips_persist_when_geo_is_inconclusive(): void
+    {
+        // rememberGeo must only run on a definitive lookup: detect_client_is_eu()
+        // returns ?bool and the caller skips null, so an unknown result never
+        // overwrites a previously known analytics_geo_is_eu value.
+        $src = file_get_contents(__DIR__ . '/../../202-config/functions-auth.php');
+        $this->assertStringContainsString('private static function detect_client_is_eu(): ?bool', $src);
+        $this->assertStringContainsString('$is_eu !== null && !ConsentPolicy::rememberGeo', $src);
     }
 }

From 5774cbd85cb01fe03fab25912411df657b04f8a8 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 23:23:53 -0700
Subject: [PATCH 09/20] feat(analytics): emit milestone events incl. LTV/LPO
 activation

---
 202-account/api-integrations.php              |  7 +++
 202-config/Ltv/MysqlIntegrationRepository.php | 10 +++-
 tests/Messaging/MilestoneWiringTest.php       | 47 +++++++++++++++++++
 tracking202/ajax/generate_tracking_link.php   |  7 +++
 tracking202/setup/aff_campaigns.php           |  6 +++
 tracking202/setup/aff_networks.php            |  7 +++
 tracking202/setup/ppc_accounts.php            |  5 ++
 7 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 tests/Messaging/MilestoneWiringTest.php

diff --git a/202-account/api-integrations.php b/202-account/api-integrations.php
index 3436bbca..ca75e1de 100755
--- a/202-account/api-integrations.php
+++ b/202-account/api-integrations.php
@@ -339,6 +339,13 @@ function lpo_ctx_pref_cache_bust($userId)
 				// status and config writes could otherwise cache active-with-
 				// stale-config for 3 minutes (no t202ctx until TTL expiry)
 				lpo_ctx_pref_cache_bust($lpo_user_id);
+
+				// Milestone event after pairComplete() succeeded and pairing state
+				// is persisted. Analytics tier → self-gates on consent; Analytics
+				// swallows its own failures — never blocks the redirect.
+				require_once dirname(__DIR__) . '/202-config/Messaging/Analytics.class.php';
+				Analytics::event('lpo_paired', [], 'analytics');
+
 				header('Location: ' . get_absolute_url() . '202-account/api-integrations.php?lpo=connected#lpo');
 				die();
 			}
diff --git a/202-config/Ltv/MysqlIntegrationRepository.php b/202-config/Ltv/MysqlIntegrationRepository.php
index 5a5b2c64..69fd0632 100644
--- a/202-config/Ltv/MysqlIntegrationRepository.php
+++ b/202-config/Ltv/MysqlIntegrationRepository.php
@@ -80,7 +80,15 @@ public function create(int $userId, string $provider, string $name = '', ?array
         );
         $this->conn->bind($stmt, 'isssii', [$userId, $provider, $name, $encodedConfig, $now, $now]);
 
-        return $this->conn->executeInsert($stmt);
+        $integrationId = $this->conn->executeInsert($stmt);
+
+        // Milestone event after the INSERT succeeded (executeInsert throws on
+        // failure). Provider name is config, not customer data. Analytics tier
+        // → self-gates on consent; Analytics swallows its own failures.
+        require_once dirname(__DIR__) . '/Messaging/Analytics.class.php';
+        \Analytics::event('ltv_integration_connected', ['provider' => (string) $provider], 'analytics');
+
+        return $integrationId;
     }
 
     public function delete(int $userId, int $integrationId): void
diff --git a/tests/Messaging/MilestoneWiringTest.php b/tests/Messaging/MilestoneWiringTest.php
new file mode 100644
index 00000000..e53d554c
--- /dev/null
+++ b/tests/Messaging/MilestoneWiringTest.php
@@ -0,0 +1,47 @@
+<?php
+// tests/Messaging/MilestoneWiringTest.php
+use PHPUnit\Framework\TestCase;
+
+final class MilestoneWiringTest extends TestCase
+{
+    private function src(string $rel): string
+    {
+        return file_get_contents(__DIR__ . '/../../' . $rel);
+    }
+
+    // NOTE: the tracking202/ajax/{aff_networks,ppc_networks,aff_campaigns}.php
+    // files are dropdown loaders with no INSERTs; the create handlers (the
+    // "INSERT INTO <table>" anchor) live in tracking202/setup/, so the
+    // milestone events are wired — and asserted — there.
+    public function test_aff_network_event(): void
+    {
+        $this->assertStringContainsString("Analytics::event('aff_network_added'",
+            $this->src('tracking202/setup/aff_networks.php'));
+    }
+    public function test_traffic_source_event(): void
+    {
+        $this->assertStringContainsString("Analytics::event('traffic_source_added'",
+            $this->src('tracking202/setup/ppc_accounts.php'));
+    }
+    public function test_campaign_event(): void
+    {
+        $this->assertStringContainsString("Analytics::event('aff_campaign_added'",
+            $this->src('tracking202/setup/aff_campaigns.php'));
+    }
+    public function test_tracker_event(): void
+    {
+        $this->assertStringContainsString("Analytics::event('tracker_created'",
+            $this->src('tracking202/ajax/generate_tracking_link.php'));
+    }
+    public function test_ltv_and_lpo_events_wired_somewhere(): void
+    {
+        // Handlers are located by grep during implementation; assert the events
+        // exist anywhere outside tests/ and Messaging/ (the emitting call sites).
+        $hits = shell_exec('grep -rl "Analytics::event(\'ltv_integration_connected\'" '
+            . escapeshellarg(dirname(__DIR__, 2)) . ' --include="*.php" | grep -v /tests/');
+        $this->assertNotEmpty(trim((string) $hits), 'ltv_integration_connected not wired');
+        $hits = shell_exec('grep -rl "Analytics::event(\'lpo_paired\'" '
+            . escapeshellarg(dirname(__DIR__, 2)) . ' --include="*.php" | grep -v /tests/');
+        $this->assertNotEmpty(trim((string) $hits), 'lpo_paired not wired');
+    }
+}
diff --git a/tracking202/ajax/generate_tracking_link.php b/tracking202/ajax/generate_tracking_link.php
index 84324ef0..736934f6 100755
--- a/tracking202/ajax/generate_tracking_link.php
+++ b/tracking202/ajax/generate_tracking_link.php
@@ -185,6 +185,13 @@
 
 	$db->commit();
 
+	// Milestone event on create only (edits delete + re-insert; must not emit).
+	// Analytics tier → self-gates on consent; failures log + swallow.
+	if (empty($_POST['edit_tracker'])) {
+		require_once dirname(__DIR__, 2) . '/202-config/Messaging/Analytics.class.php';
+		Analytics::event('tracker_created', [], 'analytics');
+	}
+
 	$parsed_url = [];
 	if (!empty($landing_page_row['landing_page_url'])) {
 		$parsed_url = parse_url((string) $landing_page_row['landing_page_url']);
diff --git a/tracking202/setup/aff_campaigns.php b/tracking202/setup/aff_campaigns.php
index 98291858..205a1c0b 100755
--- a/tracking202/setup/aff_campaigns.php
+++ b/tracking202/setup/aff_campaigns.php
@@ -229,6 +229,12 @@
 
 			if ($slack)
 				$slack->push('campaign_created', ['name' => $_POST['aff_campaign_name'], 'user' => $user_row['username']]);
+
+			// Milestone event on create only (edits must not emit *_added).
+			// Analytics tier → self-gates on consent; failures log + swallow.
+			// Uses the id captured above — $db->insert_id is reset by later queries.
+			require_once dirname(__DIR__, 2) . '/202-config/Messaging/Analytics.class.php';
+			Analytics::event('aff_campaign_added', ['aff_campaign_id' => (int) $aff_campaign_row['aff_campaign_id']], 'analytics');
 		}
 
 		// Landing Page Optimizer (segments-v2 G10): flag this user's dimension
diff --git a/tracking202/setup/aff_networks.php b/tracking202/setup/aff_networks.php
index 2befc03a..3a50df57 100755
--- a/tracking202/setup/aff_networks.php
+++ b/tracking202/setup/aff_networks.php
@@ -82,6 +82,13 @@
 		// snapshot dirty; the hourly cron pushes it. DB-only — no HTTP here.
 		\Prosper202\Lpo\DimensionSync::markDirty($db, (int) ($_SESSION['user_id'] ?? 0));
 
+		// Milestone event on create only (edits must not emit *_added).
+		// Analytics tier → self-gates on consent; failures log + swallow.
+		if ($editing != true) {
+			require_once dirname(__DIR__, 2) . '/202-config/Messaging/Analytics.class.php';
+			Analytics::event('aff_network_added', [], 'analytics');
+		}
+
 		if ($slack) {
 			if ($editing == true) {
 				$slack->push('campaign_category_name_changed', ['old_name' => $aff_network_row['aff_network_name'], 'new_name' => $_POST['aff_network_name'], 'user' => $user_row['username']]);
diff --git a/tracking202/setup/ppc_accounts.php b/tracking202/setup/ppc_accounts.php
index 9aa69261..33f6c9a8 100644
--- a/tracking202/setup/ppc_accounts.php
+++ b/tracking202/setup/ppc_accounts.php
@@ -88,6 +88,11 @@
 			} else {
 				if ($slack)
 					$slack->push('traffic_source_created', ['name' => $_POST['ppc_network_name'], 'user' => $user_row['username']]);
+
+				// Milestone event on create only (edits must not emit *_added).
+				// Analytics tier → self-gates on consent; failures log + swallow.
+				require_once dirname(__DIR__, 2) . '/202-config/Messaging/Analytics.class.php';
+				Analytics::event('traffic_source_added', [], 'analytics');
 			}
 
 			tagUserByNetwork($user_row['install_hash'], 'traffic-sources', $_POST['ppc_network_name']);

From c25aab58142a0c75fded1c1c82e1a72fe6e83d68 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 23:38:37 -0700
Subject: [PATCH 10/20] feat(analytics): add OfferProfile volume +
 offer-matching + LTV/LPO signals

---
 202-config/Messaging/OfferProfile.class.php | 226 ++++++++++++++++++++
 tests/Messaging/OfferProfileTest.php        |  48 +++++
 2 files changed, 274 insertions(+)
 create mode 100644 202-config/Messaging/OfferProfile.class.php
 create mode 100644 tests/Messaging/OfferProfileTest.php

diff --git a/202-config/Messaging/OfferProfile.class.php b/202-config/Messaging/OfferProfile.class.php
new file mode 100644
index 00000000..01d73877
--- /dev/null
+++ b/202-config/Messaging/OfferProfile.class.php
@@ -0,0 +1,226 @@
+<?php
+// 202-config/Messaging/OfferProfile.class.php
+require_once __DIR__ . '/UrlScrubber.class.php';
+
+final class OfferProfile
+{
+    private const NEAR_LIMIT_PCT = 80;
+
+    /** device_type values assigned by connect2.php device detection. */
+    private const DEVICE_TYPE_DESKTOP = 1;
+    private const DEVICE_TYPE_MOBILE = 2;
+    private const DEVICE_TYPE_TABLET = 3;
+
+    /** Pure: assemble one offer entry from a raw joined DB row. */
+    public static function buildOfferRow(array $r): array
+    {
+        $url = UrlScrubber::scrub((string) ($r['aff_campaign_url'] ?? ''));
+        $clicks = (float) ($r['clicks'] ?? 0);
+        $income = (float) ($r['income'] ?? 0);
+        $leads  = (float) ($r['leads'] ?? 0);
+        return [
+            'name'      => (string) ($r['aff_campaign_name'] ?? ''),
+            'url'       => $url,
+            'domain'    => self::domain($url),
+            'network'   => (string) ($r['aff_network_name'] ?? ''),
+            'payout'    => (float) ($r['aff_campaign_payout'] ?? 0),
+            'currency'  => (string) ($r['aff_campaign_currency'] ?? ''),
+            'epc'       => $clicks > 0 ? round($income / $clicks, 4) : 0.0,
+            'conv_rate' => $clicks > 0 ? round($leads / $clicks, 4) : 0.0,
+            'clicks_30d'=> (int) $clicks,
+        ];
+    }
+
+    public static function planLimitPct(int $used, int $limit): int
+    {
+        if ($limit <= 0) { return 0; }
+        return (int) floor($used / $limit * 100);
+    }
+
+    public static function nearPlanLimit(int $pct): bool
+    {
+        return $pct >= self::NEAR_LIMIT_PCT;
+    }
+
+    private static function domain(string $url): string
+    {
+        $h = parse_url($url, PHP_URL_HOST);
+        return is_string($h) ? $h : '';
+    }
+
+    /**
+     * Full profile. $now is the upper time bound (unix); window is 30 days.
+     * Each query checks its return value; on any failure the partial-safe
+     * defaults are returned (never throws).
+     */
+    public static function compute(mysqli $db, int $userId, int $now): array
+    {
+        $since = $now - 30 * 86400;
+        $out = [
+            'clicks_30d'=>0,'conversions_30d'=>0,'income_30d'=>0.0,'cost_30d'=>0.0,'net_30d'=>0.0,
+            'active_campaigns'=>0,'active_trackers'=>0,'plan_limit_pct'=>0,'near_plan_limit'=>false,
+            'networks'=>[],'traffic_source_types'=>[],'top_geos'=>[],
+            'device_mix'=>['mobile'=>0,'desktop'=>0,'tablet'=>0],'offers'=>[],
+        ];
+
+        // --- 30d totals from the report cube ---
+        $stmt = $db->prepare(
+            "SELECT COALESCE(SUM(clicks),0) c, COALESCE(SUM(leads),0) l,
+                    COALESCE(SUM(income),0) inc, COALESCE(SUM(cost),0) cost
+               FROM `202_dataengine`
+              WHERE user_id = ? AND click_time >= ? AND click_time <= ?"
+        );
+        if ($stmt !== false) {
+            $stmt->bind_param('iii', $userId, $since, $now);
+            if ($stmt->execute()) {
+                $row = $stmt->get_result()->fetch_assoc() ?: [];
+                $out['clicks_30d'] = (int) ($row['c'] ?? 0);
+                $out['conversions_30d'] = (int) ($row['l'] ?? 0);
+                $out['income_30d'] = (float) ($row['inc'] ?? 0);
+                $out['cost_30d'] = (float) ($row['cost'] ?? 0);
+                $out['net_30d'] = $out['income_30d'] - $out['cost_30d'];
+            }
+            $stmt->close();
+        }
+
+        // --- networks ---
+        $out['networks'] = self::col($db,
+            "SELECT aff_network_name FROM `202_aff_networks`
+              WHERE user_id = ? AND aff_network_deleted = 0", $userId);
+
+        // --- traffic source types ---
+        $out['traffic_source_types'] = self::col($db,
+            "SELECT ppc_network_name FROM `202_ppc_networks`
+              WHERE user_id = ? AND ppc_network_deleted = 0", $userId);
+
+        // --- active campaigns ---
+        $out['active_campaigns'] = count(self::col($db,
+            "SELECT aff_campaign_id FROM `202_aff_campaigns`
+              WHERE user_id = ? AND aff_campaign_deleted = 0", $userId));
+
+        // --- active trackers (tracking links whose campaign is not deleted) ---
+        $out['active_trackers'] = count(self::col($db,
+            "SELECT t.tracker_id FROM `202_trackers` t
+               JOIN `202_aff_campaigns` cmp ON cmp.aff_campaign_id = t.aff_campaign_id
+                AND cmp.aff_campaign_deleted = 0
+              WHERE t.user_id = ?", $userId));
+
+        // --- top geos (top 5 countries by clicks, 30d) ---
+        $out['top_geos'] = self::col($db,
+            "SELECT c.country_code
+               FROM `202_dataengine` d
+               JOIN `202_locations_country` c ON c.country_id = d.country_id
+              WHERE d.user_id = ? AND d.click_time >= ?
+              GROUP BY c.country_code
+              ORDER BY SUM(d.clicks) DESC
+              LIMIT 5", $userId, $since);
+
+        // --- device mix (clicks by device_type, 30d; 1=desktop 2=mobile 3=tablet) ---
+        $stmt = $db->prepare(
+            "SELECT m.device_type, COALESCE(SUM(d.clicks),0) clicks
+               FROM `202_dataengine` d
+               JOIN `202_device_models` m ON m.device_id = d.device_id
+              WHERE d.user_id = ? AND d.click_time >= ?
+              GROUP BY m.device_type"
+        );
+        if ($stmt !== false) {
+            $stmt->bind_param('ii', $userId, $since);
+            if ($stmt->execute()) {
+                $res = $stmt->get_result();
+                while ($r = $res->fetch_assoc()) {
+                    $clicks = (int) $r['clicks'];
+                    switch ((int) $r['device_type']) {
+                        case self::DEVICE_TYPE_DESKTOP: $out['device_mix']['desktop'] = $clicks; break;
+                        case self::DEVICE_TYPE_MOBILE:  $out['device_mix']['mobile'] = $clicks; break;
+                        case self::DEVICE_TYPE_TABLET:  $out['device_mix']['tablet'] = $clicks; break;
+                        // other types (bots) intentionally excluded from the mix
+                    }
+                }
+            }
+            $stmt->close();
+        }
+
+        // --- offers (full detail, 30d aggregates per campaign) ---
+        $sql = "SELECT cmp.aff_campaign_name, cmp.aff_campaign_url, cmp.aff_campaign_payout,
+                       cmp.aff_campaign_currency, net.aff_network_name,
+                       COALESCE(SUM(d.clicks),0) clicks, COALESCE(SUM(d.income),0) income,
+                       COALESCE(SUM(d.leads),0) leads
+                  FROM `202_aff_campaigns` cmp
+                  LEFT JOIN `202_aff_networks` net ON net.aff_network_id = cmp.aff_network_id
+                  LEFT JOIN `202_dataengine` d
+                         ON d.aff_campaign_id = cmp.aff_campaign_id AND d.click_time >= ?
+                 WHERE cmp.user_id = ? AND cmp.aff_campaign_deleted = 0
+                 GROUP BY cmp.aff_campaign_id";
+        $stmt = $db->prepare($sql);
+        if ($stmt !== false) {
+            $stmt->bind_param('ii', $since, $userId);
+            if ($stmt->execute()) {
+                $res = $stmt->get_result();
+                while ($r = $res->fetch_assoc()) {
+                    $out['offers'][] = self::buildOfferRow($r);
+                }
+            }
+            $stmt->close();
+        }
+
+        // --- LTV account-level aggregates (privacy boundary: aggregates ONLY,
+        //     never per-customer rows/names/aliases — see Global Constraints) ---
+        $out['ltv'] = ['total_revenue'=>0.0,'mrr'=>0.0,'arr'=>0.0,'customers'=>0,
+                       'avg_ltv'=>0.0,'active_subscriptions'=>0,'uses_ltv'=>false];
+        try {
+            // MysqlLtvRepository::summary() returns customers, total_revenue,
+            // avg_ltv, mrr, active_subscriptions; mrr() returns mrr/arr/churn.
+            // Constructed the way existing LTV callers do (Connection wrapper,
+            // all-time LtvQuery with no time bounds).
+            $repo = new \Prosper202\Ltv\MysqlLtvRepository(new \Prosper202\Database\Connection($db));
+            $summary = $repo->summary(new \Prosper202\Ltv\LtvQuery($userId));
+            $mrr = $repo->mrr($userId);
+            $out['ltv'] = [
+                'total_revenue'        => (float) ($summary['total_revenue'] ?? 0),
+                'mrr'                  => (float) ($mrr['mrr'] ?? 0),
+                'arr'                  => (float) ($mrr['arr'] ?? 0),
+                'customers'            => (int) ($summary['customers'] ?? 0),
+                'avg_ltv'              => (float) ($summary['avg_ltv'] ?? 0),
+                'active_subscriptions' => (int) ($summary['active_subscriptions'] ?? 0),
+                'uses_ltv'             => ((int) ($summary['customers'] ?? 0)) > 0,
+            ];
+        } catch (\Throwable $e) {
+            error_log('[OfferProfile] ltv aggregates unavailable: ' . $e->getMessage());
+        }
+
+        // --- LPO activation flag ---
+        $stmt = $db->prepare("SELECT lpo_status, lpo_site_key FROM `202_users_pref` WHERE user_id = ? LIMIT 1");
+        $out['lpo_active'] = false;
+        if ($stmt !== false) {
+            $stmt->bind_param('i', $userId);
+            if ($stmt->execute()) {
+                $r = $stmt->get_result()->fetch_assoc() ?: [];
+                $out['lpo_active'] = (($r['lpo_status'] ?? '') === 'active') && (($r['lpo_site_key'] ?? '') !== '');
+            }
+            $stmt->close();
+        }
+
+        // plan_limit_pct / near_plan_limit: this self-hosted schema has no
+        // plan/click-allowance record to compare against, so these stay at
+        // their defaults (0 / false) rather than inventing a column. Logged
+        // so the defaults aren't mistaken for a computed "0% of limit".
+        error_log('[OfferProfile] plan_limit_pct/near_plan_limit left at defaults: no plan allowance source in schema');
+
+        return $out;
+    }
+
+    /** @return string[] first column of a (user_id[, since]) query */
+    private static function col(mysqli $db, string $sql, int $userId, ?int $since = null): array
+    {
+        $stmt = $db->prepare($sql);
+        if ($stmt === false) { return []; }
+        if ($since === null) { $stmt->bind_param('i', $userId); }
+        else { $stmt->bind_param('ii', $userId, $since); }
+        if (!$stmt->execute()) { $stmt->close(); return []; }
+        $res = $stmt->get_result();
+        $vals = [];
+        while ($row = $res->fetch_row()) { $vals[] = (string) $row[0]; }
+        $stmt->close();
+        return $vals;
+    }
+}
diff --git a/tests/Messaging/OfferProfileTest.php b/tests/Messaging/OfferProfileTest.php
new file mode 100644
index 00000000..a914dbd3
--- /dev/null
+++ b/tests/Messaging/OfferProfileTest.php
@@ -0,0 +1,48 @@
+<?php
+// tests/Messaging/OfferProfileTest.php
+use PHPUnit\Framework\TestCase;
+require_once __DIR__ . '/../../202-config/Messaging/UrlScrubber.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/OfferProfile.class.php';
+
+final class OfferProfileTest extends TestCase
+{
+    public function test_offer_row_url_is_scrubbed(): void
+    {
+        // OfferProfile::buildOfferRow is a pure helper that assembles one offer
+        // entry from a raw DB row; it must run the url through UrlScrubber and
+        // derive the domain from the scrubbed url.
+        $raw = [
+            'aff_campaign_name' => 'Keto - US',
+            'aff_campaign_url'  => 'https://getfit-keto.com/o?s2=foo%40bar.com',
+            'aff_network_name'  => 'MaxBounty',
+            'aff_campaign_payout' => '42.00',
+            'aff_campaign_currency' => 'USD',
+            'income' => '210.0', 'clicks' => '100', 'leads' => '5',
+        ];
+        $row = OfferProfile::buildOfferRow($raw);
+        $this->assertStringNotContainsString('bar.com', $row['url']);
+        $this->assertSame('getfit-keto.com', $row['domain']);
+        $this->assertSame('MaxBounty', $row['network']);
+        $this->assertEqualsWithDelta(2.10, $row['epc'], 0.001);     // income/clicks
+        $this->assertEqualsWithDelta(0.05, $row['conv_rate'], 0.001); // leads/clicks
+    }
+
+    public function test_plan_limit_pct_buckets(): void
+    {
+        $this->assertSame(88, OfferProfile::planLimitPct(44000, 50000));
+        $this->assertTrue(OfferProfile::nearPlanLimit(88));
+        $this->assertFalse(OfferProfile::nearPlanLimit(40));
+    }
+
+    public function test_ltv_privacy_boundary_no_per_customer_surfaces(): void
+    {
+        // The profile may use ONLY account-level LTV aggregates. Guard against
+        // anyone later joining per-customer tables into the synced profile.
+        $src = file_get_contents(__DIR__ . '/../../202-config/Messaging/OfferProfile.class.php');
+        foreach (['202_customers', '202_customer_aliases', '202_customer_fields',
+                  '202_customer_field_values', '202_revenue_events', 'first_name'] as $forbidden) {
+            $this->assertStringNotContainsString($forbidden, $src,
+                "OfferProfile must not touch per-customer surface: $forbidden");
+        }
+    }
+}

From 36a5f5e05c1952b3699ce7dafd233d18994fe4e0 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 23:47:34 -0700
Subject: [PATCH 11/20] feat(analytics): compute + sync offer profile in cron,
 consent-gated

---
 202-cronjobs/sync-messaging.php  | 18 ++++++++++++++++++
 tests/Messaging/CronGateTest.php | 13 +++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 tests/Messaging/CronGateTest.php

diff --git a/202-cronjobs/sync-messaging.php b/202-cronjobs/sync-messaging.php
index a518b04f..91ab5bcc 100644
--- a/202-cronjobs/sync-messaging.php
+++ b/202-cronjobs/sync-messaging.php
@@ -18,6 +18,10 @@
 
 include_once(__DIR__ . '/../202-config/connect.php');
 
+require_once __DIR__ . '/../202-config/Messaging/ConsentPolicy.class.php';
+require_once __DIR__ . '/../202-config/Messaging/OfferProfile.class.php';
+require_once __DIR__ . '/../202-config/Messaging/MessagingService.class.php';
+
 // Prevent overlapping runs.
 $lockFile   = __DIR__ . '/messaging-sync.lock';
 $maxLockAge = 600; // 10 minutes
@@ -49,6 +53,9 @@
         throw new RuntimeException('failed to list users');
     }
 
+    // One timestamp for the whole run so every user shares the same window bound.
+    $now = time();
+
     $synced = 0;
     $failed = 0;
     while ($row = $result->fetch_assoc()) {
@@ -58,6 +65,17 @@
             continue;
         }
 
+        // Consent-gated offer profile: skip entirely (no compute, no write)
+        // when analytics consent is not granted. Never let this break the sync.
+        try {
+            if (ConsentPolicy::analyticsAllowed($db, $userId)) {
+                $profile = OfferProfile::compute($db, $userId, $now);
+                $service->updateAttributes($profile);
+            }
+        } catch (Throwable $e) {
+            error_log("Messaging sync: profile update failed for user {$userId}: " . $e->getMessage());
+        }
+
         // Force past the per-request throttle; the cron cadence is the throttle here.
         if ($service->sync(true)) {
             $synced++;
diff --git a/tests/Messaging/CronGateTest.php b/tests/Messaging/CronGateTest.php
new file mode 100644
index 00000000..3d3a36e3
--- /dev/null
+++ b/tests/Messaging/CronGateTest.php
@@ -0,0 +1,13 @@
+<?php
+// tests/Messaging/CronGateTest.php
+use PHPUnit\Framework\TestCase;
+
+final class CronGateTest extends TestCase
+{
+    public function test_cron_gates_profile_on_consent(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-cronjobs/sync-messaging.php');
+        $this->assertStringContainsString('ConsentPolicy::analyticsAllowed', $src);
+        $this->assertStringContainsString('OfferProfile::compute', $src);
+    }
+}

From 42e65d33b0666c5a967960cec93353e02dbf2c6d Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Wed, 15 Jul 2026 23:58:14 -0700
Subject: [PATCH 12/20] fix(analytics): persist nested offer-profile
 attributes, reject non-JSON loudly

updateAttributes() kept only scalar values, silently dropping the offer
profile's core payload (networks[], traffic_source_types[], top_geos[],
device_mix{}, offers[], ltv{}) before it reached
202_messaging_attributes.data. Accept JSON-encodable arrays (the whole
snapshot is json_encode'd with the failure checked), and log any
still-rejected value (objects/resources) instead of dropping it
silently. Covered by a DB-less unit test on the extracted
isPersistableAttributeValue() helper, plus manual cron verification:
consented user's profile lands with nested keys and scrubbed offer
URLs; denied user's row is untouched on rerun.
---
 .../Messaging/MessagingService.class.php      | 25 +++++++++++++--
 tests/Messaging/CronGateTest.php              | 32 +++++++++++++++++++
 2 files changed, 55 insertions(+), 2 deletions(-)

diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index b9ebccac..5634b280 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -742,9 +742,27 @@ private function reportReadReceipts(): void
     // Events & attributes (segmentation)
     // ---------------------------------------------------------------------
 
+    /**
+     * Can this value be persisted as an attribute? Scalars, null, and
+     * JSON-encodable arrays are accepted — the offer profile carries nested
+     * structures (networks[], top_geos[], device_mix{}, offers[], ltv{}).
+     * Objects and resources are rejected (and the rejection is logged by
+     * updateAttributes — never silently dropped, CLAUDE.md #4).
+     *
+     * @param mixed $value
+     */
+    public static function isPersistableAttributeValue($value): bool
+    {
+        return is_scalar($value) || $value === null || is_array($value);
+    }
+
     /**
      * Merge custom attributes into the stored snapshot and mark it for delivery.
      *
+     * Values may be scalars, null, or nested arrays (see
+     * isPersistableAttributeValue); everything is serialized as one JSON
+     * document into 202_messaging_attributes.data.
+     *
      * @param array<string,mixed> $attributes
      */
     public function updateAttributes(array $attributes): void
@@ -754,10 +772,13 @@ public function updateAttributes(array $attributes): void
         }
 
         $current = $this->getAttributes();
-        // Scalars only — nested structures are not part of the contract.
         foreach ($attributes as $key => $value) {
-            if (is_scalar($value) || $value === null) {
+            if (self::isPersistableAttributeValue($value)) {
                 $current[(string) $key] = $value;
+            } else {
+                // Loud rejection: silently dropping a key would be invisible
+                // data loss for the caller.
+                error_log("MessagingService: updateAttributes rejected non-persistable value for key '{$key}' (" . gettype($value) . ')');
             }
         }
 
diff --git a/tests/Messaging/CronGateTest.php b/tests/Messaging/CronGateTest.php
index 3d3a36e3..a9cb7469 100644
--- a/tests/Messaging/CronGateTest.php
+++ b/tests/Messaging/CronGateTest.php
@@ -2,6 +2,8 @@
 // tests/Messaging/CronGateTest.php
 use PHPUnit\Framework\TestCase;
 
+require_once __DIR__ . '/../../202-config/Messaging/MessagingService.class.php';
+
 final class CronGateTest extends TestCase
 {
     public function test_cron_gates_profile_on_consent(): void
@@ -10,4 +12,34 @@ public function test_cron_gates_profile_on_consent(): void
         $this->assertStringContainsString('ConsentPolicy::analyticsAllowed', $src);
         $this->assertStringContainsString('OfferProfile::compute', $src);
     }
+
+    /**
+     * The offer profile is mostly nested data (networks[], traffic_source_types[],
+     * top_geos[], device_mix{}, offers[], ltv{}). updateAttributes must accept
+     * those arrays — a scalars-only filter would silently drop the feature's
+     * core payload before it ever reached 202_messaging_attributes.data.
+     */
+    public function test_update_attributes_accepts_nested_profile_values(): void
+    {
+        $profileShapedValues = [
+            'clicks_30d'           => 123,
+            'income_30d'           => 45.6,
+            'near_plan_limit'      => false,
+            'networks'             => ['MaxBounty', 'ClickBank'],
+            'traffic_source_types' => ['Facebook Ads'],
+            'top_geos'             => ['US', 'GB'],
+            'device_mix'           => ['mobile' => 60, 'desktop' => 35, 'tablet' => 5],
+            'offers'               => [['name' => 'Keto - US', 'url' => 'https://x.example/o', 'epc' => 2.1]],
+            'ltv'                  => ['customers' => 10, 'avg_ltv' => 99.0],
+        ];
+        foreach ($profileShapedValues as $key => $value) {
+            $this->assertTrue(
+                MessagingService::isPersistableAttributeValue($value),
+                "profile key '{$key}' must be persistable by updateAttributes"
+            );
+        }
+
+        // Objects/resources stay out of the attribute contract.
+        $this->assertFalse(MessagingService::isPersistableAttributeValue(new stdClass()));
+    }
 }

From c772a4c2637626f4917b0cc5f843c0663ecc3ef9 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 00:16:22 -0700
Subject: [PATCH 13/20] feat(analytics): consent settings toggles, recording
 endpoint, one-time EU prompt

---
 202-account/account.php                 | 37 ++++++++++
 202-account/ajax/messaging/consent.php  | 33 +++++++++
 202-config/template.php                 | 18 +++++
 202-js/consent-prompt.js                | 94 +++++++++++++++++++++++++
 tests/Messaging/ConsentEndpointTest.php | 23 ++++++
 5 files changed, 205 insertions(+)
 create mode 100644 202-account/ajax/messaging/consent.php
 create mode 100644 202-js/consent-prompt.js
 create mode 100644 tests/Messaging/ConsentEndpointTest.php

diff --git a/202-account/account.php b/202-account/account.php
index 5c3b4071..fed3872b 100755
--- a/202-account/account.php
+++ b/202-account/account.php
@@ -2,6 +2,7 @@
 
 declare(strict_types=1);
 include_once(str_repeat("../", 1) . '202-config/connect.php');
+require_once dirname(__DIR__) . '/202-config/Messaging/ConsentPolicy.class.php';
 
 AUTH::require_user();
 
@@ -263,6 +264,17 @@
 				$_SESSION['user_pref_ad_settings'] = $mysql['user_pref_ad_settings'];
 				registerDailyEmail($mysql['user_daily_email'], $mysql['user_timezone'], $html['install_hash']);
 
+				// Consent toggles — always route through ConsentPolicy (the single
+				// chokepoint); never write the raw consent columns here. A failure
+				// must not break the settings save, so log and continue.
+				$consentUserId = (int) $_SESSION['user_id'];
+				if (!ConsentPolicy::record($db, $consentUserId, 'analytics', !empty($_POST['analytics_consent']) ? 'granted' : 'denied', 'settings')) {
+					error_log('[Consent] failed to record analytics consent for user ' . $consentUserId);
+				}
+				if (!ConsentPolicy::record($db, $consentUserId, 'email_marketing', !empty($_POST['email_marketing_consent']) ? 'granted' : 'denied', 'settings')) {
+					error_log('[Consent] failed to record email marketing consent for user ' . $consentUserId);
+				}
+
 				//try to set non expiring cache for values that are used in redirects
 				if (!empty($memcacheWorking)) {
 					$tid = $mysql['user_id'];
@@ -821,6 +833,31 @@
 						</select>
 					</div>
 				</div>
+				<?php
+				// Checkbox state comes from ConsentPolicy (the only consent reader)
+				// so 'unset' reflects the effective default rather than the raw column.
+				$analyticsChecked = ConsentPolicy::analyticsAllowed($db, (int) $_SESSION['user_id']) ? 'checked' : '';
+				$emailChecked = ConsentPolicy::emailMarketingAllowed($db, (int) $_SESSION['user_id']) ? 'checked' : '';
+				?>
+				<div class="form-group">
+					<label class="col-xs-4 control-label">Data &amp; Communication:</label>
+					<div class="col-xs-8">
+						<div class="checkbox-modern">
+							<label><input type="checkbox" name="analytics_consent" value="1" <?php echo $analyticsChecked; ?>>
+								<span><strong>Product analytics &amp; personalized help</strong> — lets us surface workflow tips and match
+								you with specially-sourced, higher-paying offers relevant to what you promote. Your usage data —
+								including traffic stats, revenue numbers, and campaign names + destination links — is sent to
+								Prosper202. We never share it with third parties. <a href="/disclosure" target="_blank">Learn more</a>.</span>
+							</label>
+						</div>
+						<div class="checkbox-modern">
+							<label><input type="checkbox" name="email_marketing_consent" value="1" <?php echo $emailChecked; ?>>
+								<span><strong>Money-making offers &amp; tips by email</strong> — occasional emails about higher-paying
+								offers and workflow improvements. You can unsubscribe anytime.</span>
+							</label>
+						</div>
+					</div>
+				</div>
 				<div class="form-group">
 					<label for="cloak_referer" class="col-xs-4 control-label">* Cloaked Referer:</label>
 					<div class="col-xs-8">
diff --git a/202-account/ajax/messaging/consent.php b/202-account/ajax/messaging/consent.php
new file mode 100644
index 00000000..10f42f7e
--- /dev/null
+++ b/202-account/ajax/messaging/consent.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+include_once(str_repeat('../', 3) . '202-config/connect.php');
+
+require __DIR__ . '/_auth.php';
+require_once dirname(__DIR__, 3) . '/202-config/Messaging/ConsentPolicy.class.php';
+
+header('Content-Type: application/json');
+
+// Shared guarded helper: fails closed when either token side is empty.
+if (!AUTH::check_csrf_token()) {
+    http_response_code(403);
+    echo json_encode(['ok' => false, 'error' => 'invalid token']);
+    exit;
+}
+
+$flag   = isset($_POST['flag']) ? (string) $_POST['flag'] : '';
+$state  = isset($_POST['state']) ? (string) $_POST['state'] : '';
+// Column is varchar(32) — clamp instead of relying on silent truncation.
+$source = substr(isset($_POST['source']) ? (string) $_POST['source'] : 'settings', 0, 32);
+
+if (!in_array($flag, ['analytics', 'email_marketing'], true)
+    || !in_array($state, ['granted', 'denied'], true)) {
+    http_response_code(400);
+    echo json_encode(['ok' => false, 'error' => 'bad_args']);
+    exit;
+}
+
+// Single chokepoint — ConsentPolicy owns every raw consent-column write.
+$ok = ConsentPolicy::record($db, (int) $messagingUserId, $flag, $state, $source);
+echo json_encode(['ok' => (bool) $ok]);
diff --git a/202-config/template.php b/202-config/template.php
index e7830e2d..5b9e5f51 100755
--- a/202-config/template.php
+++ b/202-config/template.php
@@ -506,7 +506,25 @@ function template_bottom()
 			require_once __DIR__ . '/Messaging/Analytics.class.php';
 			$p202_route = parse_url($_SERVER['REQUEST_URI'] ?? '', PHP_URL_PATH) ?: 'unknown';
 			Analytics::event('page_viewed', ['path' => $p202_route], 'analytics');
+
+			// One-time EU consent prompt. ConsentPolicy is the only consent
+			// reader; a consent lookup failure must never break the page.
+			require_once __DIR__ . '/Messaging/ConsentPolicy.class.php';
+			try {
+				$p202_consent_db = $GLOBALS['db'] ?? null;
+				$p202_needs_prompt = ($p202_consent_db instanceof mysqli)
+					&& ConsentPolicy::needsEuPrompt($p202_consent_db, (int) $_SESSION['user_id']);
+			} catch (\Throwable $p202_consent_e) {
+				$p202_needs_prompt = false;
+				error_log('[Consent] ' . $p202_consent_e->getMessage());
+			}
 			?>
+			<?php if ($p202_needs_prompt) { ?>
+				<div id="p202-consent-banner"
+					data-base="<?php echo htmlspecialchars(get_absolute_url(), ENT_QUOTES); ?>"
+					data-token="<?php echo htmlspecialchars((string) ($_SESSION['token'] ?? ''), ENT_QUOTES); ?>"></div>
+				<script type="text/javascript" src="<?php echo get_absolute_url(); ?>202-js/consent-prompt.js"></script>
+			<?php } ?>
 			<!-- Prosper202 Messenger: config + command-queue stub + widget -->
 			<script type="text/javascript">
 				window.P202M_CONFIG = {
diff --git a/202-js/consent-prompt.js b/202-js/consent-prompt.js
new file mode 100644
index 00000000..9c40b4bd
--- /dev/null
+++ b/202-js/consent-prompt.js
@@ -0,0 +1,94 @@
+/**
+ * Prosper202 one-time EU consent prompt.
+ *
+ * Mounted by 202-config/template.php only when ConsentPolicy::needsEuPrompt()
+ * says so (EU user, analytics consent unset, prompt not yet seen). Posts the
+ * choice to 202-account/ajax/messaging/consent.php with source=eu_prompt and
+ * removes itself. Styled with the global design system (.card-modern,
+ * .btn-modern) on p202-ui.css tokens — no bespoke palette.
+ */
+(function () {
+    'use strict';
+
+    var mount = document.getElementById('p202-consent-banner');
+    if (!mount) { return; }
+
+    var base = mount.getAttribute('data-base') || '/';
+    var token = mount.getAttribute('data-token') || '';
+
+    var card = document.createElement('div');
+    card.className = 'card-modern';
+    card.setAttribute('role', 'dialog');
+    card.setAttribute('aria-label', 'Data preferences');
+    // Fixed positioning is the one pattern the kit lacks; everything else
+    // (surface, radius, shadow) comes from p202-ui.css tokens.
+    card.style.position = 'fixed';
+    card.style.right = '24px';
+    card.style.bottom = '24px';
+    card.style.maxWidth = '420px';
+    card.style.zIndex = '10050';
+    card.style.borderRadius = 'var(--p202-r-xl)';
+    card.style.boxShadow = 'var(--p202-sh-pop)';
+
+    var headline = document.createElement('h4');
+    headline.textContent = 'Get workflow tips & higher-paying offers';
+    headline.style.marginTop = '0';
+
+    var body = document.createElement('p');
+    body.style.fontSize = '13px';
+    body.textContent = 'Allow product analytics so we can surface workflow tips and ' +
+        'match you with specially-sourced, higher-paying offers relevant to what you ' +
+        'promote. Your usage data — including traffic stats, revenue numbers, and ' +
+        'campaign names + destination links — is sent to Prosper202. We never share ' +
+        'it with third parties.';
+
+    var actions = document.createElement('div');
+    actions.style.display = 'flex';
+    actions.style.gap = '12px';
+    actions.style.alignItems = 'center';
+
+    var accept = document.createElement('button');
+    accept.type = 'button';
+    accept.className = 'btn-modern';
+    accept.textContent = 'Accept';
+
+    var decline = document.createElement('button');
+    decline.type = 'button';
+    decline.textContent = 'No thanks';
+    decline.style.background = 'none';
+    decline.style.border = 'none';
+    decline.style.cursor = 'pointer';
+    decline.style.fontSize = '14px';
+    decline.style.color = 'var(--p202-accent)';
+
+    function remove() {
+        if (mount.parentNode) { mount.parentNode.removeChild(mount); }
+    }
+
+    function send(state) {
+        var params = new URLSearchParams();
+        params.append('flag', 'analytics');
+        params.append('state', state);
+        params.append('source', 'eu_prompt');
+        params.append('token', token);
+        fetch(base + '202-account/ajax/messaging/consent.php', {
+            method: 'POST',
+            credentials: 'same-origin',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString()
+        }).catch(function () {
+            /* Never break the host page; the prompt simply reappears next load. */
+        });
+        remove();
+    }
+
+    accept.addEventListener('click', function () { send('granted'); });
+    decline.addEventListener('click', function () { send('denied'); });
+
+    actions.appendChild(accept);
+    actions.appendChild(decline);
+    card.appendChild(headline);
+    card.appendChild(body);
+    card.appendChild(actions);
+    mount.appendChild(card);
+})();
diff --git a/tests/Messaging/ConsentEndpointTest.php b/tests/Messaging/ConsentEndpointTest.php
new file mode 100644
index 00000000..096c17dc
--- /dev/null
+++ b/tests/Messaging/ConsentEndpointTest.php
@@ -0,0 +1,23 @@
+<?php
+// tests/Messaging/ConsentEndpointTest.php
+use PHPUnit\Framework\TestCase;
+
+final class ConsentEndpointTest extends TestCase
+{
+    public function test_endpoint_exists_and_records(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-account/ajax/messaging/consent.php');
+        $this->assertStringContainsString('ConsentPolicy::record', $src);
+    }
+    public function test_account_page_has_toggles(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-account/account.php');
+        $this->assertStringContainsString('analytics_consent', $src);
+        $this->assertStringContainsString('email_marketing_consent', $src);
+    }
+    public function test_template_mounts_eu_prompt_conditionally(): void
+    {
+        $src = file_get_contents(__DIR__ . '/../../202-config/template.php');
+        $this->assertStringContainsString('needsEuPrompt', $src);
+    }
+}

From 931739747678fdaeda54b9359c6d880ef72124ba Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 01:11:02 -0700
Subject: [PATCH 14/20] fix(analytics): enforce consent at the sync boundary,
 fail closed on lookup failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spec $9 was unimplemented at the transport layer: flushEvents() ignored
the tier column entirely and the identity payload re-transmitted the full
attribute snapshot (offer profile: revenue, campaign names, destination
URLs) on every pull/send/track — indefinitely, even after revocation.

- flushEvents() now reads tier, restricts non-consented flushes to
  essential rows, sends the tier in the payload so the server can keep
  the tiers separable, and withholds the analytics snapshot (its dirty
  flag survives so a later re-grant delivers a fresh one).
- Every client() call site transmits outboundIdentity(), which strips
  the analytics-tier attribute snapshot for non-consented users.
- ConsentPolicy::record('analytics','denied') purges the undelivered
  analytics events and the snapshot via MessagingService::purgeAnalyticsData,
  so revocation stops previously collected data from ever leaving.
- ConsentPolicy now fails CLOSED on lookup failure (spec $6): loadPref
  distinguishes a query failure (null -> deny) from a genuine missing row
  (documented non-EU default), and every failure path logs.
---
 202-config/Messaging/ConsentPolicy.class.php  | 153 +++++++++++++-----
 .../Messaging/MessagingService.class.php      | 153 +++++++++++++++++-
 tests/Messaging/ConsentPolicyTest.php         |  40 +++++
 tests/Messaging/SyncConsentBoundaryTest.php   |  65 ++++++++
 4 files changed, 364 insertions(+), 47 deletions(-)
 create mode 100644 tests/Messaging/SyncConsentBoundaryTest.php

diff --git a/202-config/Messaging/ConsentPolicy.class.php b/202-config/Messaging/ConsentPolicy.class.php
index 5ff8caa5..520568d4 100644
--- a/202-config/Messaging/ConsentPolicy.class.php
+++ b/202-config/Messaging/ConsentPolicy.class.php
@@ -21,20 +21,30 @@ public static function decide(string $stored, bool $isEu, string $tier): bool
     public static function analyticsAllowed(mysqli $db, int $userId): bool
     {
         $row = self::loadPref($db, $userId);
+        if ($row === null) {
+            // Fail CLOSED (spec §6): a lookup FAILURE must never resolve to
+            // "granted" — the stored state we could not read might be EU or an
+            // explicit denial. Only a genuine no-row/unknown-geo state gets the
+            // non-EU on-by-default treatment (handled inside loadPref).
+            return false;
+        }
         return self::decide($row['analytics_consent'], $row['is_eu'], 'analytics');
     }
 
     public static function emailMarketingAllowed(mysqli $db, int $userId): bool
     {
         $row = self::loadPref($db, $userId);
-        // Marketing email never goes out on a bare default — require explicit grant.
-        return $row['email_marketing_consent'] === 'granted';
+        // Marketing email never goes out on a bare default — require explicit
+        // grant. A lookup failure ($row === null) therefore also denies.
+        return $row !== null && $row['email_marketing_consent'] === 'granted';
     }
 
     public static function needsEuPrompt(mysqli $db, int $userId): bool
     {
         $row = self::loadPref($db, $userId);
-        return $row['is_eu'] === true
+        // Lookup failure → no prompt (fail closed; analytics is held anyway).
+        return $row !== null
+            && $row['is_eu'] === true
             && $row['analytics_consent'] === 'unset'
             && $row['prompt_seen'] === false;
     }
@@ -43,40 +53,88 @@ public static function record(mysqli $db, int $userId, string $flag, string $sta
     {
         if (!in_array($flag, ['analytics','email_marketing'], true)) { return false; }
         if (!in_array($state, ['granted','denied'], true)) { return false; }
-        if ($flag === 'analytics') {
-            $sql = "UPDATE `202_users_pref`
-                       SET `analytics_consent` = ?, `analytics_consent_at` = NOW(),
-                           `analytics_consent_source` = ?, `eu_consent_prompt_seen` = 1
-                     WHERE `user_id` = ?";
-            $stmt = $db->prepare($sql);
-            if ($stmt === false) { return false; }
-            $stmt->bind_param('ssi', $state, $source, $userId);
-        } else {
-            $sql = "UPDATE `202_users_pref`
-                       SET `email_marketing_consent` = ?, `email_marketing_consent_at` = NOW()
-                     WHERE `user_id` = ?";
-            $stmt = $db->prepare($sql);
-            if ($stmt === false) { return false; }
-            $stmt->bind_param('si', $state, $userId);
+        try {
+            if ($flag === 'analytics') {
+                $sql = "UPDATE `202_users_pref`
+                           SET `analytics_consent` = ?, `analytics_consent_at` = NOW(),
+                               `analytics_consent_source` = ?, `eu_consent_prompt_seen` = 1
+                         WHERE `user_id` = ?";
+                $stmt = $db->prepare($sql);
+                if ($stmt === false) {
+                    error_log('[ConsentPolicy] record prepare failed: ' . $db->error);
+                    return false;
+                }
+                $stmt->bind_param('ssi', $state, $source, $userId);
+            } else {
+                $sql = "UPDATE `202_users_pref`
+                           SET `email_marketing_consent` = ?, `email_marketing_consent_at` = NOW()
+                         WHERE `user_id` = ?";
+                $stmt = $db->prepare($sql);
+                if ($stmt === false) {
+                    error_log('[ConsentPolicy] record prepare failed: ' . $db->error);
+                    return false;
+                }
+                $stmt->bind_param('si', $state, $userId);
+            }
+            $ok = $stmt->execute();
+            if (!$ok) {
+                error_log('[ConsentPolicy] record execute failed: ' . $stmt->error);
+            }
+            $stmt->close();
+        } catch (\Throwable $e) {
+            error_log('[ConsentPolicy] record failed: ' . $e->getMessage());
+            return false;
+        }
+
+        if ($ok && $flag === 'analytics' && $state === 'denied') {
+            // Revocation must also stop previously collected analytics data
+            // from ever leaving the install (spec §9): purge undelivered
+            // analytics-tier events and the attribute snapshot. Best-effort —
+            // the transport boundary re-checks consent regardless.
+            try {
+                require_once __DIR__ . '/MessagingService.class.php';
+                if (!MessagingService::purgeAnalyticsData($db, $userId)) {
+                    error_log('[ConsentPolicy] analytics purge on denial incomplete for user ' . $userId);
+                }
+            } catch (\Throwable $e) {
+                error_log('[ConsentPolicy] analytics purge on denial failed: ' . $e->getMessage());
+            }
         }
-        $ok = $stmt->execute();
-        $stmt->close();
+
         return (bool) $ok;
     }
 
     public static function rememberGeo(mysqli $db, int $userId, bool $isEu): bool
     {
-        $stmt = $db->prepare("UPDATE `202_users_pref` SET `analytics_geo_is_eu` = ? WHERE `user_id` = ?");
-        if ($stmt === false) { return false; }
-        $v = $isEu ? 1 : 0;
-        $stmt->bind_param('ii', $v, $userId);
-        $ok = $stmt->execute();
-        $stmt->close();
-        return (bool) $ok;
+        try {
+            $stmt = $db->prepare("UPDATE `202_users_pref` SET `analytics_geo_is_eu` = ? WHERE `user_id` = ?");
+            if ($stmt === false) {
+                error_log('[ConsentPolicy] rememberGeo prepare failed: ' . $db->error);
+                return false;
+            }
+            $v = $isEu ? 1 : 0;
+            $stmt->bind_param('ii', $v, $userId);
+            $ok = $stmt->execute();
+            if (!$ok) {
+                error_log('[ConsentPolicy] rememberGeo execute failed: ' . $stmt->error);
+            }
+            $stmt->close();
+            return (bool) $ok;
+        } catch (\Throwable $e) {
+            error_log('[ConsentPolicy] rememberGeo failed: ' . $e->getMessage());
+            return false;
+        }
     }
 
-    /** @return array{analytics_consent:string,email_marketing_consent:string,is_eu:bool,prompt_seen:bool} */
-    private static function loadPref(mysqli $db, int $userId): array
+    /**
+     * Load the stored consent state. Returns NULL on any lookup failure so
+     * callers fail CLOSED (spec §6: failure is never an accidental "granted").
+     * A genuine missing row is NOT a failure: it returns the documented
+     * defaults (consent unset, unknown geo → non-EU).
+     *
+     * @return array{analytics_consent:string,email_marketing_consent:string,is_eu:bool,prompt_seen:bool}|null
+     */
+    private static function loadPref(mysqli $db, int $userId): ?array
     {
         $default = [
             'analytics_consent' => 'unset',
@@ -84,16 +142,33 @@ private static function loadPref(mysqli $db, int $userId): array
             'is_eu' => false,          // unknown geo → treat as non-EU (Global Constraints)
             'prompt_seen' => false,
         ];
-        $stmt = $db->prepare(
-            "SELECT `analytics_consent`, `email_marketing_consent`, `analytics_geo_is_eu`, `eu_consent_prompt_seen`
-               FROM `202_users_pref` WHERE `user_id` = ? LIMIT 1"
-        );
-        if ($stmt === false) { return $default; }
-        $stmt->bind_param('i', $userId);
-        if (!$stmt->execute()) { $stmt->close(); return $default; }
-        $res = $stmt->get_result();
-        $row = $res ? $res->fetch_assoc() : null;
-        $stmt->close();
+        try {
+            $stmt = $db->prepare(
+                "SELECT `analytics_consent`, `email_marketing_consent`, `analytics_geo_is_eu`, `eu_consent_prompt_seen`
+                   FROM `202_users_pref` WHERE `user_id` = ? LIMIT 1"
+            );
+            if ($stmt === false) {
+                error_log('[ConsentPolicy] loadPref prepare failed: ' . $db->error);
+                return null;
+            }
+            $stmt->bind_param('i', $userId);
+            if (!$stmt->execute()) {
+                error_log('[ConsentPolicy] loadPref execute failed: ' . $stmt->error);
+                $stmt->close();
+                return null;
+            }
+            $res = $stmt->get_result();
+            if ($res === false) {
+                error_log('[ConsentPolicy] loadPref get_result failed: ' . $stmt->error);
+                $stmt->close();
+                return null;
+            }
+            $row = $res->fetch_assoc();
+            $stmt->close();
+        } catch (\Throwable $e) {
+            error_log('[ConsentPolicy] loadPref failed: ' . $e->getMessage());
+            return null;
+        }
         if (!$row) { return $default; }
         return [
             'analytics_consent' => $row['analytics_consent'] ?? 'unset',
diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index 5634b280..2a345439 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 include_once(__DIR__ . '/MessagingClient.class.php');
+include_once(__DIR__ . '/ConsentPolicy.class.php');
 
 /**
  * MessagingService
@@ -30,6 +31,8 @@ class MessagingService
     /** @var array<string,mixed> */
     private array $identity;
     private ?MessagingClient $client = null;
+    /** Cached consent decision for this instance (one lookup per sync run). */
+    private ?bool $analyticsSyncAllowed = null;
 
     /**
      * @param array<string,mixed> $identity Identity payload for the central API.
@@ -114,6 +117,45 @@ private function client(): MessagingClient
         return $this->client ??= new MessagingClient();
     }
 
+    /**
+     * Whether analytics-tier data may leave this install for this user
+     * (spec §9). Checked at the TRANSPORT boundary — not just at enqueue
+     * time — so revoking consent stops data that was collected earlier.
+     * Fails CLOSED: ConsentPolicy already resolves lookup failures to false,
+     * and any unexpected throw here must never become an accidental "granted".
+     * Cached per instance so a sync run performs one consent read.
+     */
+    private function analyticsSyncAllowed(): bool
+    {
+        if ($this->analyticsSyncAllowed === null) {
+            try {
+                $this->analyticsSyncAllowed = ConsentPolicy::analyticsAllowed($this->db, $this->userId);
+            } catch (Throwable $e) {
+                error_log('MessagingService: consent lookup failed, failing closed: ' . $e->getMessage());
+                $this->analyticsSyncAllowed = false;
+            }
+        }
+        return $this->analyticsSyncAllowed;
+    }
+
+    /**
+     * Identity payload as sent over the wire. The stored attribute snapshot
+     * is analytics-tier data (the offer profile + client custom attributes),
+     * so it is stripped for non-consented users — only essential identity
+     * fields (install hash, email, registration date) may leave the install
+     * (spec §9). Every client() call site must use this, never raw identity.
+     *
+     * @return array<string,mixed>
+     */
+    private function outboundIdentity(): array
+    {
+        $identity = $this->identity;
+        if (!$this->analyticsSyncAllowed()) {
+            unset($identity['attributes']);
+        }
+        return $identity;
+    }
+
     // ---------------------------------------------------------------------
     // Sync orchestration
     // ---------------------------------------------------------------------
@@ -142,7 +184,7 @@ public function sync(bool $force = false): bool
         $this->reportReadReceipts();
 
         $cursor   = $this->getCursor();
-        $response = $this->client()->pull($this->identity, $cursor);
+        $response = $this->client()->pull($this->outboundIdentity(), $cursor);
 
         if ($response === null) {
             $this->recordSyncError('pull failed');
@@ -556,7 +598,7 @@ private function pushMessage(int $messageId): bool
             : $this->getConversationExternalId($conversationId);
 
         $response = $this->client()->send(
-            $this->identity,
+            $this->outboundIdentity(),
             $sendConvId,
             (string) $message['body'],
             (string) $message['client_token']
@@ -721,7 +763,7 @@ private function reportReadReceipts(): void
             return;
         }
 
-        $response = $this->client()->markRead($this->identity, array_values($rows));
+        $response = $this->client()->markRead($this->outboundIdentity(), array_values($rows));
         if ($response === null) {
             return; // try again next sync
         }
@@ -857,15 +899,29 @@ public function recordEvent(string $name, ?array $metadata = null, string $tier
 
     /**
      * Deliver the attribute snapshot (if changed) plus any pending events.
+     *
+     * Consent boundary (spec §9): only essential-tier rows sync for
+     * non-consented users; analytics rows (events + the attribute/offer
+     * snapshot) sync only when analyticsAllowed. Enforced HERE — at flush
+     * time, not just enqueue time — so a user who revokes consent stops
+     * analytics rows queued while consent was still in effect.
      */
     private function flushEvents(): void
     {
+        $analyticsAllowed = $this->analyticsSyncAllowed();
+
         $events = [];
-        $sql = "SELECT id, event_name, metadata, occurred_at, client_token
+        $sql = "SELECT id, event_name, metadata, occurred_at, client_token, tier
                   FROM 202_messaging_events
                  WHERE user_id = ? AND delivery_status = 'pending'
-                   AND sync_attempts < ?
-                 ORDER BY id ASC
+                   AND sync_attempts < ?";
+        if (!$analyticsAllowed) {
+            // Analytics rows stay local; if consent is later granted again
+            // they are still 'pending' and flush then. Denial purges them
+            // outright (ConsentPolicy::record → purgeAnalyticsData).
+            $sql .= " AND tier = 'essential'";
+        }
+        $sql .= " ORDER BY id ASC
                  LIMIT 100";
         $stmt = $this->db->prepare($sql);
         if ($stmt) {
@@ -885,13 +941,19 @@ private function flushEvents(): void
                         'metadata'     => $metadata,
                         'occurred_at'  => $row['occurred_at'],
                         'client_token' => $row['client_token'],
+                        // Propagate the tier so the central server can keep
+                        // essential and analytics rows separable (spec §5/§13).
+                        'tier'         => (string) $row['tier'],
                     ];
                 }
             }
             $stmt->close();
         }
 
-        $attributesDirty = $this->areAttributesDirty();
+        // The attribute snapshot is analytics-tier; for non-consented users it
+        // is neither counted as pending work nor transmitted. The dirty flag
+        // survives so a later re-grant delivers a fresh snapshot.
+        $attributesDirty = $analyticsAllowed && $this->areAttributesDirty();
 
         if ($events === [] && !$attributesDirty) {
             return; // nothing to flush
@@ -903,7 +965,8 @@ private function flushEvents(): void
             return $e;
         }, $events);
 
-        $response = $this->client()->track($this->identity, $this->getAttributes(), $payloadEvents);
+        $attributes = $analyticsAllowed ? $this->getAttributes() : [];
+        $response = $this->client()->track($this->outboundIdentity(), $attributes, $payloadEvents);
 
         if ($response === null) {
             // Bump attempts so poison events eventually stop being retried.
@@ -922,6 +985,80 @@ private function flushEvents(): void
         }
     }
 
+    /**
+     * Has an event with this name ever been recorded for this user?
+     * Used for one-shot lifecycle events (e.g. first_click_received).
+     */
+    public function hasEvent(string $name): bool
+    {
+        $sql  = "SELECT id FROM 202_messaging_events WHERE user_id = ? AND event_name = ? LIMIT 1";
+        $stmt = $this->db->prepare($sql);
+        if (!$stmt) {
+            error_log('MessagingService: prepare hasEvent failed');
+            // Err on "already recorded" so a DB failure can never cause a
+            // duplicate one-shot event.
+            return true;
+        }
+        $stmt->bind_param('is', $this->userId, $name);
+        if (!$stmt->execute()) {
+            error_log('MessagingService: hasEvent failed');
+            $stmt->close();
+            return true;
+        }
+        $exists = (bool) $stmt->get_result()->fetch_assoc();
+        $stmt->close();
+        return $exists;
+    }
+
+    /**
+     * Remove analytics-tier data that has not yet left the install. Called by
+     * ConsentPolicy::record() when a user denies analytics consent, so
+     * revocation stops previously collected data from ever syncing (spec §9).
+     *
+     * The whole attribute snapshot is analytics-tier (the offer profile plus
+     * client custom attributes — essential identity lives on 202_users, not
+     * here), so the snapshot row is deleted outright. Undelivered analytics
+     * events (pending or failed) are deleted; already-'sent' rows are only a
+     * local delivery log and cannot transmit again.
+     *
+     * @return bool False when any delete failed (caller logs).
+     */
+    public static function purgeAnalyticsData(mysqli $db, int $userId): bool
+    {
+        $ok = true;
+
+        $stmt = $db->prepare(
+            "DELETE FROM 202_messaging_events
+              WHERE user_id = ? AND tier = 'analytics' AND delivery_status != 'sent'"
+        );
+        if (!$stmt) {
+            error_log('MessagingService: purge events prepare failed: ' . $db->error);
+            $ok = false;
+        } else {
+            $stmt->bind_param('i', $userId);
+            if (!$stmt->execute()) {
+                error_log('MessagingService: purge events failed: ' . $stmt->error);
+                $ok = false;
+            }
+            $stmt->close();
+        }
+
+        $stmt = $db->prepare("DELETE FROM 202_messaging_attributes WHERE user_id = ?");
+        if (!$stmt) {
+            error_log('MessagingService: purge attributes prepare failed: ' . $db->error);
+            $ok = false;
+        } else {
+            $stmt->bind_param('i', $userId);
+            if (!$stmt->execute()) {
+                error_log('MessagingService: purge attributes failed: ' . $stmt->error);
+                $ok = false;
+            }
+            $stmt->close();
+        }
+
+        return $ok;
+    }
+
     private function incrementEventAttempts(int $eventId): void
     {
         $sql  = "UPDATE 202_messaging_events
diff --git a/tests/Messaging/ConsentPolicyTest.php b/tests/Messaging/ConsentPolicyTest.php
index d49c686f..142823af 100644
--- a/tests/Messaging/ConsentPolicyTest.php
+++ b/tests/Messaging/ConsentPolicyTest.php
@@ -36,4 +36,44 @@ public function test_analytics_unset_eu_false(): void
     {
         $this->assertFalse(ConsentPolicy::decide('unset', true, 'analytics'));
     }
+
+    // ------------------------------------------------------------------
+    // Failure semantics (spec §6): a consent LOOKUP FAILURE must never
+    // resolve to "granted" — the unreadable stored state might be EU or an
+    // explicit denial. Simulated with a mysqli whose prepare() fails, the
+    // exact shape of a mid-retry migration (consent columns missing) under
+    // the UI path's non-throwing mysqli report mode.
+    // ------------------------------------------------------------------
+
+    /** @return mysqli A mysqli double whose prepare() always fails. */
+    private function failingDb(): mysqli
+    {
+        $db = $this->createMock(mysqli::class);
+        $db->method('prepare')->willReturn(false);
+        return $db;
+    }
+
+    public function test_reads_fail_closed_on_db_failure(): void
+    {
+        $db = $this->failingDb();
+        $this->assertFalse(ConsentPolicy::analyticsAllowed($db, 7),
+            'analyticsAllowed must fail CLOSED on lookup failure, not fall back to the non-EU default');
+        $this->assertFalse(ConsentPolicy::emailMarketingAllowed($db, 7));
+        $this->assertFalse(ConsentPolicy::needsEuPrompt($db, 7));
+    }
+
+    public function test_writes_report_failure_on_db_failure(): void
+    {
+        $db = $this->failingDb();
+        $this->assertFalse(ConsentPolicy::record($db, 7, 'analytics', 'denied', 'settings'));
+        $this->assertFalse(ConsentPolicy::rememberGeo($db, 7, true));
+    }
+
+    public function test_record_rejects_invalid_args_without_touching_db(): void
+    {
+        $db = $this->createMock(mysqli::class);
+        $db->expects($this->never())->method('prepare');
+        $this->assertFalse(ConsentPolicy::record($db, 7, 'bogus_flag', 'granted', 'settings'));
+        $this->assertFalse(ConsentPolicy::record($db, 7, 'analytics', 'maybe', 'settings'));
+    }
 }
diff --git a/tests/Messaging/SyncConsentBoundaryTest.php b/tests/Messaging/SyncConsentBoundaryTest.php
new file mode 100644
index 00000000..b962e540
--- /dev/null
+++ b/tests/Messaging/SyncConsentBoundaryTest.php
@@ -0,0 +1,65 @@
+<?php
+// tests/Messaging/SyncConsentBoundaryTest.php
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Source-level guards for the spec §9 transport boundary: only essential rows
+ * sync for non-consented users; the attribute snapshot and analytics-tier
+ * events sync only when analyticsAllowed. Behavioral proof lives in
+ * ConsentSyncIntegrationTest (DB-gated).
+ */
+final class SyncConsentBoundaryTest extends TestCase
+{
+    private function serviceSrc(): string
+    {
+        return file_get_contents(__DIR__ . '/../../202-config/Messaging/MessagingService.class.php');
+    }
+
+    public function test_flush_reads_tier_and_filters_non_consented_to_essential(): void
+    {
+        $src = $this->serviceSrc();
+        $this->assertStringContainsString('client_token, tier', $src,
+            'flushEvents must SELECT the tier column (it was write-only dead data)');
+        $this->assertStringContainsString("AND tier = 'essential'", $src,
+            'flushEvents must restrict non-consented flushes to essential rows');
+        $this->assertMatchesRegularExpression("/'tier'\\s*=>\\s*\\(string\\) \\\$row\\['tier'\\]/", $src,
+            'the event payload must propagate tier so the server can separate the tiers');
+    }
+
+    public function test_every_wire_call_uses_the_consent_filtered_identity(): void
+    {
+        $src = $this->serviceSrc();
+        // The raw identity embeds the full attribute snapshot (offer profile:
+        // revenue, campaign names, destination URLs). No client() call may
+        // transmit it unfiltered.
+        $this->assertDoesNotMatchRegularExpression(
+            '/client\(\)->(pull|send|markRead|track)\(\s*\$this->identity\b/',
+            $src,
+            'a client() call transmits the unfiltered identity payload'
+        );
+        foreach (['pull', 'send', 'markRead', 'track'] as $method) {
+            $this->assertMatchesRegularExpression(
+                '/client\(\)->' . $method . '\(\s*\$this->outboundIdentity\(\)/',
+                $src,
+                "client()->{$method}() must use outboundIdentity()"
+            );
+        }
+        $this->assertStringContainsString("unset(\$identity['attributes'])", $src);
+    }
+
+    public function test_denial_purges_undelivered_analytics_data(): void
+    {
+        $this->assertStringContainsString('public static function purgeAnalyticsData', $this->serviceSrc());
+        $policy = file_get_contents(__DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php');
+        $this->assertStringContainsString('MessagingService::purgeAnalyticsData', $policy,
+            'ConsentPolicy::record must purge undelivered analytics data on denial');
+    }
+
+    public function test_consent_lookup_failure_fails_closed(): void
+    {
+        $policy = file_get_contents(__DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php');
+        // loadPref must distinguish lookup failure (null → deny) from a
+        // genuine missing row (documented non-EU default).
+        $this->assertMatchesRegularExpression('/private static function loadPref\(mysqli \$db, int \$userId\): \?array/', $policy);
+    }
+}

From 7bcc1b5f088bb9e83a0200585496357cd9870dae Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 01:11:11 -0700
Subject: [PATCH 15/20] fix(analytics): ship a real disclosure page; fix the
 dead Learn-more link
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The settings copy linked href="/disclosure", which 404s on every install
(no such route exists) and escapes the install root on subdirectory
installs. The disclosure is load-bearing for the on-by-default posture
(spec D2/D3, $10.1), so it now ships as a local page:

- 202-account/disclosure.php: what is sent, what never leaves the
  install (visitors' PII, per-customer LTV data), consent + off switch,
  the bounded marketing promise. Login required, license NOT (a privacy
  disclosure must stay reachable when the license check fails).
- account.php links it via get_absolute_url() like every other page.
- The EU consent banner gains the same Learn-more link — it previously
  had no disclosure surface at all.
---
 202-account/account.php                 |  2 +-
 202-account/disclosure.php              | 85 +++++++++++++++++++++++++
 202-js/consent-prompt.js                | 10 ++-
 tests/Messaging/ConsentEndpointTest.php | 18 ++++++
 4 files changed, 113 insertions(+), 2 deletions(-)
 create mode 100644 202-account/disclosure.php

diff --git a/202-account/account.php b/202-account/account.php
index fed3872b..331b4d9d 100755
--- a/202-account/account.php
+++ b/202-account/account.php
@@ -847,7 +847,7 @@
 								<span><strong>Product analytics &amp; personalized help</strong> — lets us surface workflow tips and match
 								you with specially-sourced, higher-paying offers relevant to what you promote. Your usage data —
 								including traffic stats, revenue numbers, and campaign names + destination links — is sent to
-								Prosper202. We never share it with third parties. <a href="/disclosure" target="_blank">Learn more</a>.</span>
+								Prosper202. We never share it with third parties. <a href="<?php echo get_absolute_url(); ?>202-account/disclosure.php" target="_blank" rel="noopener">Learn more</a>.</span>
 							</label>
 						</div>
 						<div class="checkbox-modern">
diff --git a/202-account/disclosure.php b/202-account/disclosure.php
new file mode 100644
index 00000000..dc8dcd73
--- /dev/null
+++ b/202-account/disclosure.php
@@ -0,0 +1,85 @@
+<?php
+
+/**
+ * Product analytics & communication disclosure.
+ *
+ * The "Learn more" target for the consent surfaces (account settings toggles,
+ * EU consent prompt). Copy must stay truthful to the spec's D6/D7 bounds:
+ * analytics sends usage including traffic stats, revenue numbers, and campaign
+ * names + destination template URLs; marketing is money/workflow/offer-matching
+ * only; visitors' PII and per-customer LTV data never leave the install.
+ *
+ * Login is required, but NOT a valid license (like the messaging endpoints):
+ * a privacy disclosure must stay reachable even when the license check fails.
+ */
+
+declare(strict_types=1);
+include_once(str_repeat("../", 1) . '202-config/connect.php');
+
+AUTH::require_user('', false);
+
+template_top('Product Analytics Disclosure');
+
+?>
+
+<div style="max-width: 860px; margin: 24px auto 48px; padding: 0 16px;">
+	<div class="page-header">
+		<h4>Product analytics &amp; personalized help</h4>
+		<p>What leaves your install, what never does, and how to switch it off.</p>
+	</div>
+
+	<div class="card-modern" style="padding: 24px 28px; margin-bottom: 16px;">
+		<h5>Why we collect this</h5>
+		<p>When product analytics is on, we use your Prosper202 usage to help you <strong>earn more</strong> —
+			surfacing workflow tips and matching you with specially-sourced, higher-paying offers relevant to
+			what you actually promote. Everything we send you based on this data is bounded to
+			money-making, workflow, and offer-matching. Never generic promotion.</p>
+	</div>
+
+	<div class="card-modern" style="padding: 24px 28px; margin-bottom: 16px;">
+		<h5>What is sent to Prosper202</h5>
+		<ul>
+			<li><strong>Traffic and results:</strong> clicks, conversions, income, cost, and net over the last
+				30 days; top countries and device mix.</li>
+			<li><strong>Your campaign setup:</strong> affiliate network names, traffic source names, campaign
+				names, and the campaign destination (template) URLs you entered at setup — with any email or
+				phone values redacted before sending.</li>
+			<li><strong>Offer performance:</strong> per-campaign payout, currency, EPC, conversion rate, and
+				clicks.</li>
+			<li><strong>Account-level revenue aggregates:</strong> if you use Customer LTV, only account totals
+				(total revenue, MRR/ARR, customer count, average LTV, active subscriptions).</li>
+			<li><strong>Product usage:</strong> pages viewed inside Prosper202 and setup milestones (e.g.
+				campaign created, tracking link generated, integration connected).</li>
+		</ul>
+		<p>We never share this data with third parties.</p>
+	</div>
+
+	<div class="card-modern" style="padding: 24px 28px; margin-bottom: 16px;">
+		<h5>What never leaves your install</h5>
+		<ul>
+			<li><strong>Your visitors' data.</strong> We track your product usage as the account holder — never
+				your traffic's personal data. (Your visitors' click-data privacy is governed separately by the
+				Privacy Option above it in Settings.)</li>
+			<li><strong>Your customers' data.</strong> Customer LTV records — names, aliases, emails,
+				per-customer revenue, custom fields — never sync. Only the account-level aggregates listed
+				above do.</li>
+		</ul>
+	</div>
+
+	<div class="card-modern" style="padding: 24px 28px; margin-bottom: 16px;">
+		<h5>Consent and the off switch</h5>
+		<ul>
+			<li>Product analytics is on by default outside the EU/UK, and held behind a one-time consent
+				prompt for EU/UK account holders. You can turn it off (or back on) anytime in
+				<a href="<?php echo get_absolute_url(); ?>202-account/account.php">Account Settings</a>.</li>
+			<li>Switching it off stops collection and syncing immediately, and deletes the analytics data on
+				your install that has not yet been delivered (queued events and the computed usage profile).</li>
+			<li>A small <strong>essential</strong> tier stays on for operational use (account lifecycle, login,
+				and support messaging delivery) — it carries no campaign or revenue analytics.</li>
+			<li><strong>Money-making offers &amp; tips by email</strong> is a separate, opt-in consent. It is
+				never inferred from the analytics setting, and you can unsubscribe anytime.</li>
+		</ul>
+	</div>
+</div>
+
+<?php template_bottom(); ?>
diff --git a/202-js/consent-prompt.js b/202-js/consent-prompt.js
index 9c40b4bd..7bf4f20a 100644
--- a/202-js/consent-prompt.js
+++ b/202-js/consent-prompt.js
@@ -40,7 +40,15 @@
         'match you with specially-sourced, higher-paying offers relevant to what you ' +
         'promote. Your usage data — including traffic stats, revenue numbers, and ' +
         'campaign names + destination links — is sent to Prosper202. We never share ' +
-        'it with third parties.';
+        'it with third parties. ';
+
+    // The full disclosure page (what is sent, what never leaves the install).
+    var learnMore = document.createElement('a');
+    learnMore.href = base + '202-account/disclosure.php';
+    learnMore.target = '_blank';
+    learnMore.rel = 'noopener';
+    learnMore.textContent = 'Learn more';
+    body.appendChild(learnMore);
 
     var actions = document.createElement('div');
     actions.style.display = 'flex';
diff --git a/tests/Messaging/ConsentEndpointTest.php b/tests/Messaging/ConsentEndpointTest.php
index 096c17dc..861570f8 100644
--- a/tests/Messaging/ConsentEndpointTest.php
+++ b/tests/Messaging/ConsentEndpointTest.php
@@ -20,4 +20,22 @@ public function test_template_mounts_eu_prompt_conditionally(): void
         $src = file_get_contents(__DIR__ . '/../../202-config/template.php');
         $this->assertStringContainsString('needsEuPrompt', $src);
     }
+
+    public function test_disclosure_page_exists_and_links_are_live(): void
+    {
+        // The disclosure is load-bearing for the privacy posture (spec §10.1,
+        // D2/D3): the "Learn more" link must resolve on every install — a
+        // local page, reached via get_absolute_url() (never a root-absolute
+        // path, which 404s on subdirectory installs).
+        $this->assertFileExists(__DIR__ . '/../../202-account/disclosure.php');
+
+        $account = file_get_contents(__DIR__ . '/../../202-account/account.php');
+        $this->assertStringNotContainsString('href="/disclosure"', $account,
+            'account.php must not link a nonexistent root-absolute /disclosure route');
+        $this->assertStringContainsString('202-account/disclosure.php', $account);
+
+        // The EU prompt is a consent surface too — it must carry the same link.
+        $prompt = file_get_contents(__DIR__ . '/../../202-js/consent-prompt.js');
+        $this->assertStringContainsString('202-account/disclosure.php', $prompt);
+    }
 }

From 06f5201fc56248af065704d5b2292d77c1547b37 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 01:11:22 -0700
Subject: [PATCH 16/20] feat(analytics): implement the essential tier + missing
 spec-8 lifecycle attributes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The essential tier was entirely unimplemented (the enum value was dead
outside the gate logic) and three spec-8 attributes were absent:

- login (essential) recorded in begin_user_session — also gives
  login_cadence a data source, since no historical login log exists.
- account_created (essential) recorded for the NEW user at the
  user-management create handler (via MessagingService directly; the
  Analytics facade would attach it to the creating admin).
- OfferProfile::compute adds first_click_at (MIN click_time from
  202_dataengine), days_since_signup (202_users.user_time_register) and
  login_cadence (bucketed 30d count of essential login events).
- first_click_received (analytics) derived one-shot in the cron inside
  the existing consent gate, guarded by MessagingService::hasEvent.

Still unwired, needs a plan-owner call (no handler exists / entry points
too diffuse): upgraded/downgraded (no plan-change handler in the
self-hosted codebase), report_viewed / feature_used call sites,
account_created at the installer and V3 users API.
---
 202-account/user-management.php             | 15 ++++++
 202-config/Messaging/OfferProfile.class.php | 57 +++++++++++++++++++++
 202-config/functions-auth.php               | 11 ++++
 202-cronjobs/sync-messaging.php             | 11 ++++
 tests/Messaging/OfferProfileTest.php        | 23 +++++++++
 5 files changed, 117 insertions(+)

diff --git a/202-account/user-management.php b/202-account/user-management.php
index 290db42e..94f1592c 100755
--- a/202-account/user-management.php
+++ b/202-account/user-management.php
@@ -217,6 +217,21 @@
 		// Only run pref_sql when creating a new user (not editing)
 		if (!$editing) {
 			$pref_result = _mysqli_query($pref_sql);
+
+			// Essential-tier lifecycle event (spec §7.3) for the NEW account —
+			// recorded via MessagingService directly because the Analytics
+			// facade would attach it to the creating admin's session user.
+			// Essential tier needs no consent; failures log + swallow.
+			// $user_id is $db->insert_id: 0 when the user INSERT failed, so
+			// guard against recording an event for a user that was never made.
+			if ((int) $user_id > 0) {
+				try {
+					require_once dirname(__DIR__) . '/202-config/Messaging/MessagingService.class.php';
+					(new MessagingService($db, (int) $user_id, []))->recordEvent('account_created', [], 'essential');
+				} catch (Throwable $analytics_e) {
+					error_log('[Analytics] account_created event failed: ' . $analytics_e->getMessage());
+				}
+			}
 		}
 
 		$add_success = true;
diff --git a/202-config/Messaging/OfferProfile.class.php b/202-config/Messaging/OfferProfile.class.php
index 01d73877..44267252 100644
--- a/202-config/Messaging/OfferProfile.class.php
+++ b/202-config/Messaging/OfferProfile.class.php
@@ -42,6 +42,19 @@ public static function nearPlanLimit(int $pct): bool
         return $pct >= self::NEAR_LIMIT_PCT;
     }
 
+    /**
+     * Pure: bucket a 30-day login count into a cadence label (spec §8).
+     * Derived from the essential-tier 'login' events this install records,
+     * so fresh installs read 'dormant' until logins accumulate.
+     */
+    public static function loginCadence(int $logins30d): string
+    {
+        if ($logins30d <= 0) { return 'dormant'; }
+        if ($logins30d >= 20) { return 'daily'; }
+        if ($logins30d >= 4) { return 'weekly'; }
+        return 'occasional';
+    }
+
     private static function domain(string $url): string
     {
         $h = parse_url($url, PHP_URL_HOST);
@@ -59,6 +72,7 @@ public static function compute(mysqli $db, int $userId, int $now): array
         $out = [
             'clicks_30d'=>0,'conversions_30d'=>0,'income_30d'=>0.0,'cost_30d'=>0.0,'net_30d'=>0.0,
             'active_campaigns'=>0,'active_trackers'=>0,'plan_limit_pct'=>0,'near_plan_limit'=>false,
+            'first_click_at'=>null,'days_since_signup'=>0,'login_cadence'=>'unknown',
             'networks'=>[],'traffic_source_types'=>[],'top_geos'=>[],
             'device_mix'=>['mobile'=>0,'desktop'=>0,'tablet'=>0],'offers'=>[],
         ];
@@ -83,6 +97,49 @@ public static function compute(mysqli $db, int $userId, int $now): array
             $stmt->close();
         }
 
+        // --- lifecycle (spec §8): first click ever, signup age, login cadence ---
+        $stmt = $db->prepare(
+            "SELECT MIN(click_time) fc FROM `202_dataengine` WHERE user_id = ? AND clicks > 0"
+        );
+        if ($stmt !== false) {
+            $stmt->bind_param('i', $userId);
+            if ($stmt->execute()) {
+                $row = $stmt->get_result()->fetch_assoc() ?: [];
+                // MIN() is NULL when the user has no clicks yet (isset() excludes it).
+                $out['first_click_at'] = isset($row['fc']) ? (int) $row['fc'] : null;
+            }
+            $stmt->close();
+        }
+
+        $stmt = $db->prepare("SELECT user_time_register FROM `202_users` WHERE user_id = ? LIMIT 1");
+        if ($stmt !== false) {
+            $stmt->bind_param('i', $userId);
+            if ($stmt->execute()) {
+                $row = $stmt->get_result()->fetch_assoc() ?: [];
+                if ((int) ($row['user_time_register'] ?? 0) > 0) {
+                    $out['days_since_signup'] = max(0, (int) floor(($now - (int) $row['user_time_register']) / 86400));
+                }
+            }
+            $stmt->close();
+        }
+
+        // Cadence from the essential-tier login events this install records
+        // (202_messaging_events). No historical login log exists, so this
+        // reads 'dormant' until logins accumulate post-upgrade.
+        $stmt = $db->prepare(
+            "SELECT COUNT(*) c FROM `202_messaging_events`
+              WHERE user_id = ? AND event_name = 'login' AND tier = 'essential' AND occurred_at >= ?"
+        );
+        if ($stmt !== false) {
+            $sinceDt = date('Y-m-d H:i:s', $since);
+            $stmt->bind_param('is', $userId, $sinceDt);
+            if ($stmt->execute()) {
+                $row = $stmt->get_result()->fetch_assoc() ?: [];
+                $out['login_cadence'] = self::loginCadence((int) ($row['c'] ?? 0));
+            }
+            $stmt->close();
+        }
+
         // --- networks ---
         $out['networks'] = self::col($db,
             "SELECT aff_network_name FROM `202_aff_networks`
diff --git a/202-config/functions-auth.php b/202-config/functions-auth.php
index af3f1573..650f4bd8 100755
--- a/202-config/functions-auth.php
+++ b/202-config/functions-auth.php
@@ -284,6 +284,17 @@ public static function begin_user_session(array $user_row): void
         } catch (\Throwable $e) {
             error_log('[ConsentPolicy] rememberGeo at login failed: ' . $e->getMessage());
         }
+
+        // Essential-tier lifecycle event (spec §7.3): login always flows, no
+        // consent gate. Analytics resolves $db/$_SESSION (established above),
+        // never throws, and logs + swallows its own failures — a tracking
+        // problem must never break login.
+        try {
+            require_once __DIR__ . '/Messaging/Analytics.class.php';
+            \Analytics::event('login', [], 'essential');
+        } catch (\Throwable $e) {
+            error_log('[Analytics] login event failed: ' . $e->getMessage());
+        }
     }
 
     /**
diff --git a/202-cronjobs/sync-messaging.php b/202-cronjobs/sync-messaging.php
index 91ab5bcc..f39db8be 100644
--- a/202-cronjobs/sync-messaging.php
+++ b/202-cronjobs/sync-messaging.php
@@ -71,6 +71,17 @@
             if (ConsentPolicy::analyticsAllowed($db, $userId)) {
                 $profile = OfferProfile::compute($db, $userId, $now);
                 $service->updateAttributes($profile);
+
+                // One-shot analytics-tier milestone (spec §7.3), derived here
+                // because no click-path handler may carry tracking overhead.
+                // Guarded by the same consent gate as the profile above.
+                if ($profile['first_click_at'] !== null && !$service->hasEvent('first_click_received')) {
+                    $service->recordEvent(
+                        'first_click_received',
+                        ['first_click_at' => (int) $profile['first_click_at']],
+                        'analytics'
+                    );
+                }
             }
         } catch (Throwable $e) {
             error_log("Messaging sync: profile update failed for user {$userId}: " . $e->getMessage());
diff --git a/tests/Messaging/OfferProfileTest.php b/tests/Messaging/OfferProfileTest.php
index a914dbd3..000d76d0 100644
--- a/tests/Messaging/OfferProfileTest.php
+++ b/tests/Messaging/OfferProfileTest.php
@@ -34,6 +34,29 @@ public function test_plan_limit_pct_buckets(): void
         $this->assertFalse(OfferProfile::nearPlanLimit(40));
     }
 
+    public function test_login_cadence_buckets(): void
+    {
+        // Spec §8: login_cadence (daily/weekly/dormant), derived from the
+        // essential-tier login events recorded on this install.
+        $this->assertSame('dormant', OfferProfile::loginCadence(0));
+        $this->assertSame('occasional', OfferProfile::loginCadence(1));
+        $this->assertSame('occasional', OfferProfile::loginCadence(3));
+        $this->assertSame('weekly', OfferProfile::loginCadence(4));
+        $this->assertSame('weekly', OfferProfile::loginCadence(19));
+        $this->assertSame('daily', OfferProfile::loginCadence(20));
+        $this->assertSame('daily', OfferProfile::loginCadence(90));
+    }
+
+    public function test_compute_covers_spec8_lifecycle_attributes(): void
+    {
+        // first_click_at / days_since_signup / login_cadence must be part of
+        // the computed profile (spec §8 rows previously missing).
+        $src = file_get_contents(__DIR__ . '/../../202-config/Messaging/OfferProfile.class.php');
+        foreach (['first_click_at', 'days_since_signup', 'login_cadence'] as $key) {
+            $this->assertStringContainsString("'$key'", $src, "OfferProfile missing spec §8 attribute $key");
+        }
+    }
+
     public function test_ltv_privacy_boundary_no_per_customer_surfaces(): void
     {
         // The profile may use ONLY account-level LTV aggregates. Guard against

From f6cf6519d9db242fc92badaf7ae96b4aa2e38b58 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 01:11:31 -0700
Subject: [PATCH 17/20] test(analytics): DB-gated behavioral verification of
 the consent substrate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The branch had no behavioral tests — every wiring test is a source-string
assertion, and the plan's manual verification steps were unevidenced.
This adds real-MySQL integration tests (skipped unless P202_TEST_DB_* is
set) using the actual schema definitions and a captured fake transport:

- EU geo persistence, one-time prompt flow, grant/decline (Tasks 6/10).
- Consent-gated, tier'd event writes through the Analytics facade (5/7).
- Snapshot write while consented; denial purges the snapshot and the
  undelivered analytics events, keeps essential rows (Task 9 + revocation).
- Transport boundary: a held (EU+unset) user syncs ONLY essential rows,
  an empty attribute payload, and an identity without the snapshot; a
  granted user syncs both tiers with tier in the payload.

Verified locally against mysql:8 (6 tests, 101 assertions).
---
 .../Messaging/ConsentSyncIntegrationTest.php  | 338 ++++++++++++++++++
 1 file changed, 338 insertions(+)
 create mode 100644 tests/Messaging/ConsentSyncIntegrationTest.php

diff --git a/tests/Messaging/ConsentSyncIntegrationTest.php b/tests/Messaging/ConsentSyncIntegrationTest.php
new file mode 100644
index 00000000..c006b833
--- /dev/null
+++ b/tests/Messaging/ConsentSyncIntegrationTest.php
@@ -0,0 +1,338 @@
+<?php
+// tests/Messaging/ConsentSyncIntegrationTest.php
+
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+use Prosper202\Database\Tables\CoreTables;
+use Prosper202\Database\Tables\UserTables;
+
+require_once __DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/MessagingService.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/Analytics.class.php';
+
+/**
+ * Captures every wire call instead of talking to my.tracking202.com, so the
+ * consent boundary can be asserted on the exact payloads that would have
+ * been transmitted.
+ */
+final class ConsentSyncFakeClient extends MessagingClient
+{
+    /** @var array<int,array{identity:array,attributes:array,events:array}> */
+    public array $trackCalls = [];
+    /** @var array<int,array{identity:array,cursor:?string}> */
+    public array $pullCalls = [];
+
+    public function pull(array $identity, ?string $cursor): ?array
+    {
+        $this->pullCalls[] = ['identity' => $identity, 'cursor' => $cursor];
+        return ['conversations' => [], 'cursor' => 'cur-1'];
+    }
+
+    public function send(array $identity, ?string $conversationExternalId, string $body, string $clientToken): ?array
+    {
+        return null;
+    }
+
+    public function markRead(array $identity, array $externalIds): ?array
+    {
+        return ['ok' => true];
+    }
+
+    public function track(array $identity, array $attributes, array $events): ?array
+    {
+        $this->trackCalls[] = ['identity' => $identity, 'attributes' => $attributes, 'events' => $events];
+        return ['ok' => true];
+    }
+}
+
+/**
+ * DB-gated behavioral verification of the consent substrate: EU geo
+ * persistence, prompt flow, tier'd event writes, denial purge, and the
+ * spec §9 sync boundary (only essential rows/no snapshot for non-consented
+ * users). These are the behaviors the per-task manual verifications were
+ * supposed to cover; they run against a real MySQL using the real schema
+ * definitions.
+ *
+ * Skipped unless a test database is configured:
+ *
+ *   docker run -d --name p202-test-mysql -e MYSQL_ROOT_PASSWORD=root \
+ *     -e MYSQL_DATABASE=p202_test -p 33061:3306 mysql:8
+ *
+ *   P202_TEST_DB_HOST=127.0.0.1 P202_TEST_DB_PORT=33061 \
+ *   P202_TEST_DB_USER=root P202_TEST_DB_PASS=root P202_TEST_DB_NAME=p202_test \
+ *   vendor/bin/phpunit -c phpunit.ci.xml tests/Messaging/ConsentSyncIntegrationTest.php
+ */
+final class ConsentSyncIntegrationTest extends TestCase
+{
+    private const USER_ID = 4242;
+
+    private static ?mysqli $db = null;
+    private static string $skipReason = 'P202_TEST_DB_HOST not set (integration test needs a real MySQL)';
+
+    public static function setUpBeforeClass(): void
+    {
+        $host = getenv('P202_TEST_DB_HOST');
+        if ($host === false || $host === '') {
+            return;
+        }
+
+        mysqli_report(MYSQLI_REPORT_OFF); // UI-path semantics: failures return false, never throw
+
+        $db = mysqli_init();
+        $connected = $db && @$db->real_connect(
+            $host,
+            getenv('P202_TEST_DB_USER') !== false ? (string) getenv('P202_TEST_DB_USER') : 'root',
+            getenv('P202_TEST_DB_PASS') !== false ? (string) getenv('P202_TEST_DB_PASS') : '',
+            getenv('P202_TEST_DB_NAME') !== false ? (string) getenv('P202_TEST_DB_NAME') : 'p202_test',
+            (int) (getenv('P202_TEST_DB_PORT') !== false ? getenv('P202_TEST_DB_PORT') : 3306)
+        );
+        if (!$connected) {
+            self::$skipReason = 'could not connect to the configured test MySQL';
+            return;
+        }
+
+        // Mirror the UI path (connect.php runs with strict mode disabled).
+        $db->query("SET SESSION sql_mode = ''");
+
+        // Real schema definitions — the same SQL fresh installs run.
+        foreach ([
+            UserTables::usersPref(),
+            CoreTables::messagingEvents(),
+            CoreTables::messagingAttributes(),
+            CoreTables::messagingSync(),
+            CoreTables::messagingConversations(),
+            CoreTables::messagingMessages(),
+        ] as $definition) {
+            if ($db->query('DROP TABLE IF EXISTS `' . $definition->tableName . '`') === false
+                || $db->query($definition->createStatement) === false) {
+                self::$skipReason = 'failed to create schema: ' . $db->error;
+                return;
+            }
+        }
+
+        self::$db = $db;
+    }
+
+    public static function tearDownAfterClass(): void
+    {
+        if (self::$db !== null) {
+            self::$db->close();
+            self::$db = null;
+        }
+        unset($GLOBALS['db'], $_SESSION['user_id']);
+    }
+
+    protected function setUp(): void
+    {
+        if (self::$db === null) {
+            $this->markTestSkipped(self::$skipReason);
+        }
+        $db = self::$db;
+        foreach (['202_messaging_events', '202_messaging_attributes', '202_messaging_sync',
+                  '202_messaging_messages', '202_messaging_conversations', '202_users_pref'] as $table) {
+            $this->assertNotFalse($db->query("DELETE FROM `{$table}`"), "cleanup of {$table} failed: " . $db->error);
+        }
+        $this->assertNotFalse(
+            $db->query('INSERT INTO `202_users_pref` (user_id) VALUES (' . self::USER_ID . ')'),
+            'seeding 202_users_pref failed: ' . $db->error
+        );
+    }
+
+    private function service(array $identity = []): MessagingService
+    {
+        return new MessagingService(self::$db, self::USER_ID, $identity);
+    }
+
+    private function injectFakeClient(MessagingService $service): ConsentSyncFakeClient
+    {
+        $fake = new ConsentSyncFakeClient();
+        $prop = new ReflectionProperty(MessagingService::class, 'client');
+        $prop->setAccessible(true);
+        $prop->setValue($service, $fake);
+        return $fake;
+    }
+
+    /** @return array<int,array<string,mixed>> */
+    private function eventRows(): array
+    {
+        $res = self::$db->query(
+            'SELECT event_name, tier, delivery_status FROM `202_messaging_events` WHERE user_id = '
+            . self::USER_ID . ' ORDER BY id ASC'
+        );
+        $this->assertNotFalse($res);
+        return $res->fetch_all(MYSQLI_ASSOC);
+    }
+
+    // ------------------------------------------------------------------
+    // Task 6/10 behaviors: EU geo persistence + one-time prompt flow
+    // ------------------------------------------------------------------
+
+    public function test_eu_geo_persistence_prompt_and_grant_flow(): void
+    {
+        $db = self::$db;
+
+        $this->assertTrue(ConsentPolicy::rememberGeo($db, self::USER_ID, true));
+        $this->assertFalse(ConsentPolicy::analyticsAllowed($db, self::USER_ID), 'EU + unset must be held');
+        $this->assertTrue(ConsentPolicy::needsEuPrompt($db, self::USER_ID));
+
+        $this->assertTrue(ConsentPolicy::record($db, self::USER_ID, 'analytics', 'granted', 'eu_prompt'));
+        $this->assertTrue(ConsentPolicy::analyticsAllowed($db, self::USER_ID));
+        $this->assertFalse(ConsentPolicy::needsEuPrompt($db, self::USER_ID), 'prompt is one-time');
+
+        $res = $db->query(
+            'SELECT analytics_geo_is_eu, eu_consent_prompt_seen, analytics_consent, analytics_consent_source
+               FROM `202_users_pref` WHERE user_id = ' . self::USER_ID
+        );
+        $this->assertNotFalse($res);
+        $row = $res->fetch_assoc();
+        $this->assertSame(1, (int) $row['analytics_geo_is_eu']);
+        $this->assertSame(1, (int) $row['eu_consent_prompt_seen']);
+        $this->assertSame('granted', $row['analytics_consent']);
+        $this->assertSame('eu_prompt', $row['analytics_consent_source']);
+    }
+
+    public function test_eu_decline_denies_and_marks_prompt_seen(): void
+    {
+        $db = self::$db;
+        $this->assertTrue(ConsentPolicy::rememberGeo($db, self::USER_ID, true));
+        $this->assertTrue(ConsentPolicy::record($db, self::USER_ID, 'analytics', 'denied', 'eu_prompt'));
+        $this->assertFalse(ConsentPolicy::analyticsAllowed($db, self::USER_ID));
+        $this->assertFalse(ConsentPolicy::needsEuPrompt($db, self::USER_ID));
+    }
+
+    // ------------------------------------------------------------------
+    // Task 5/7 behaviors: consent-gated, tier'd event writes
+    // ------------------------------------------------------------------
+
+    public function test_analytics_events_are_consent_gated_and_tiered(): void
+    {
+        $db = self::$db;
+        $GLOBALS['db'] = $db;
+        $_SESSION['user_id'] = self::USER_ID;
+
+        // Non-EU default: analytics flows and lands with tier='analytics'.
+        $this->assertTrue(ConsentPolicy::rememberGeo($db, self::USER_ID, false));
+        Analytics::event('feature_used', ['feature' => 'export'], 'analytics');
+        $rows = $this->eventRows();
+        $this->assertCount(1, $rows);
+        $this->assertSame(['feature_used', 'analytics', 'pending'], array_values($rows[0]));
+
+        // Denial: no further analytics writes (and the pending row is purged).
+        $this->assertTrue(ConsentPolicy::record($db, self::USER_ID, 'analytics', 'denied', 'settings'));
+        Analytics::event('feature_used', ['feature' => 'export'], 'analytics');
+        $this->assertSame([], $this->eventRows(), 'denied user must produce no analytics rows');
+
+        // Essential still flows for the denied user.
+        Analytics::event('login', [], 'essential');
+        $rows = $this->eventRows();
+        $this->assertCount(1, $rows);
+        $this->assertSame(['login', 'essential', 'pending'], array_values($rows[0]));
+    }
+
+    // ------------------------------------------------------------------
+    // Task 9 behavior + revocation: profile write, then purge on denial
+    // ------------------------------------------------------------------
+
+    public function test_denial_purges_snapshot_and_undelivered_analytics_events(): void
+    {
+        $db = self::$db;
+        $service = $this->service();
+
+        $service->updateAttributes(['clicks_30d' => 5, 'offers' => [['name' => 'Keto - US', 'url' => 'https://x.example/o']]]);
+        $service->recordEvent('page_viewed', ['path' => '/tracking202/'], 'analytics');
+        $service->recordEvent('login', null, 'essential');
+
+        $res = $db->query('SELECT data, dirty FROM `202_messaging_attributes` WHERE user_id = ' . self::USER_ID);
+        $this->assertNotFalse($res);
+        $snapshot = $res->fetch_assoc();
+        $this->assertNotNull($snapshot, 'profile snapshot must be written while consented');
+        $this->assertStringContainsString('Keto - US', (string) $snapshot['data']);
+        $this->assertCount(2, $this->eventRows());
+
+        $this->assertTrue(ConsentPolicy::record($db, self::USER_ID, 'analytics', 'denied', 'settings'));
+
+        $res = $db->query('SELECT COUNT(*) c FROM `202_messaging_attributes` WHERE user_id = ' . self::USER_ID);
+        $this->assertNotFalse($res);
+        $this->assertSame(0, (int) $res->fetch_assoc()['c'], 'denial must purge the analytics snapshot');
+
+        $rows = $this->eventRows();
+        $this->assertCount(1, $rows, 'denial must purge undelivered analytics events, keep essential');
+        $this->assertSame('login', $rows[0]['event_name']);
+    }
+
+    // ------------------------------------------------------------------
+    // Spec §9 transport boundary: what actually goes over the wire
+    // ------------------------------------------------------------------
+
+    public function test_sync_transmits_only_essential_rows_when_analytics_held(): void
+    {
+        $db = self::$db;
+
+        // EU + unset: analytics held with NO denial purge — the exact case
+        // where leftover analytics rows/snapshot exist locally and the
+        // transport boundary is the only defense.
+        $this->assertTrue(ConsentPolicy::rememberGeo($db, self::USER_ID, true));
+
+        $identity = ['install_hash' => 'h', 'api_key' => 'k', 'user_id' => self::USER_ID,
+                     'attributes' => ['clicks_30d' => 9, 'offers' => [['name' => 'Keto - US']]]];
+        $service = $this->service($identity);
+        $fake = $this->injectFakeClient($service);
+
+        $service->recordEvent('login', null, 'essential');
+        $service->recordEvent('page_viewed', ['path' => '/x'], 'analytics');
+        $service->updateAttributes(['clicks_30d' => 9]); // dirty analytics snapshot
+
+        $this->assertTrue($service->sync(true));
+
+        $this->assertCount(1, $fake->trackCalls);
+        $track = $fake->trackCalls[0];
+        $this->assertSame(['login'], array_column($track['events'], 'name'),
+            'only essential rows may sync for a non-consented user');
+        $this->assertSame('essential', $track['events'][0]['tier'], 'tier must travel in the payload');
+        $this->assertSame([], $track['attributes'], 'the analytics snapshot must not sync');
+        $this->assertArrayNotHasKey('attributes', $track['identity'],
+            'identity must not embed the attribute snapshot for a non-consented user');
+        $this->assertCount(1, $fake->pullCalls);
+        $this->assertArrayNotHasKey('attributes', $fake->pullCalls[0]['identity'],
+            'pull identity re-transmitted the profile — the revocation leak the review flagged');
+
+        // Local state: essential delivered, analytics kept local and pending.
+        $rows = $this->eventRows();
+        $this->assertSame([['login', 'essential', 'sent'], ['page_viewed', 'analytics', 'pending']],
+            array_map('array_values', $rows));
+        $res = $db->query('SELECT dirty FROM `202_messaging_attributes` WHERE user_id = ' . self::USER_ID);
+        $this->assertNotFalse($res);
+        $this->assertSame(1, (int) $res->fetch_assoc()['dirty'],
+            'snapshot stays dirty so a later grant delivers it');
+    }
+
+    public function test_sync_transmits_analytics_rows_and_snapshot_when_granted(): void
+    {
+        $db = self::$db;
+        $this->assertTrue(ConsentPolicy::rememberGeo($db, self::USER_ID, true));
+        $this->assertTrue(ConsentPolicy::record($db, self::USER_ID, 'analytics', 'granted', 'eu_prompt'));
+
+        $identity = ['install_hash' => 'h', 'api_key' => 'k', 'user_id' => self::USER_ID];
+        $service = $this->service($identity);
+        $fake = $this->injectFakeClient($service);
+
+        $service->recordEvent('login', null, 'essential');
+        $service->recordEvent('page_viewed', ['path' => '/x'], 'analytics');
+        $service->updateAttributes(['clicks_30d' => 9]);
+
+        $this->assertTrue($service->sync(true));
+
+        $this->assertCount(1, $fake->trackCalls);
+        $track = $fake->trackCalls[0];
+        $this->assertSame(['login', 'page_viewed'], array_column($track['events'], 'name'));
+        $this->assertSame(['essential', 'analytics'], array_column($track['events'], 'tier'));
+        $this->assertSame(9, $track['attributes']['clicks_30d'] ?? null);
+        $this->assertSame(9, $track['identity']['attributes']['clicks_30d'] ?? null,
+            'consented identity carries the snapshot as before');
+
+        $rows = $this->eventRows();
+        $this->assertSame([['login', 'essential', 'sent'], ['page_viewed', 'analytics', 'sent']],
+            array_map('array_values', $rows));
+    }
+}

From a01e1f64370bb32bada6c73bbabaec02e15f4230 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 09:49:06 -0700
Subject: [PATCH 18/20] =?UTF-8?q?feat(analytics):=20transmit=20consent=20b?=
 =?UTF-8?q?lock=20to=20central=20server=20(receiver=20spec=20=C2=A76)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 202-config/Messaging/ConsentPolicy.class.php  |  70 ++++
 .../Messaging/MessagingClient.class.php       |  16 +-
 .../Messaging/MessagingService.class.php      |  34 +-
 tests/Messaging/ConsentSyncBlockTest.php      | 307 ++++++++++++++++++
 .../Messaging/ConsentSyncIntegrationTest.php  |  15 +-
 5 files changed, 433 insertions(+), 9 deletions(-)
 create mode 100644 tests/Messaging/ConsentSyncBlockTest.php

diff --git a/202-config/Messaging/ConsentPolicy.class.php b/202-config/Messaging/ConsentPolicy.class.php
index 520568d4..dcd853a1 100644
--- a/202-config/Messaging/ConsentPolicy.class.php
+++ b/202-config/Messaging/ConsentPolicy.class.php
@@ -39,6 +39,76 @@ public static function emailMarketingAllowed(mysqli $db, int $userId): bool
         return $row !== null && $row['email_marketing_consent'] === 'granted';
     }
 
+    /**
+     * Consent state as transmitted to the central server (receiver spec §6
+     * CONTRACT DELTA). Operational bookkeeping — exported for ALL users so
+     * the server learns denials too. On any lookup failure OR a genuine
+     * missing row the all-unset shape (nulls for source/timestamps) is
+     * returned: absence must read as "no grant" server-side (fail closed),
+     * so a failure can never masquerade as a grant on the wire.
+     *
+     * Failure and missing-row take the same fail-closed shape but stay
+     * distinguished below, mirroring loadPref's raw-mysqli checks: a false
+     * get_result() on a SELECT is a fetch FAILURE (server gone away
+     * mid-fetch, mysqlnd OOM) and is logged as one — a successful SELECT
+     * always yields a mysqli_result, even with zero rows.
+     *
+     * @return array{analytics:string,analytics_source:?string,analytics_at:?string,email_marketing:string,email_marketing_at:?string}
+     */
+    public static function exportForSync(mysqli $db, int $userId): array
+    {
+        $unset = [
+            'analytics'          => 'unset',
+            'analytics_source'   => null,
+            'analytics_at'       => null,
+            'email_marketing'    => 'unset',
+            'email_marketing_at' => null,
+        ];
+        try {
+            $stmt = $db->prepare(
+                "SELECT `analytics_consent`, `analytics_consent_source`, `analytics_consent_at`,
+                        `email_marketing_consent`, `email_marketing_consent_at`
+                   FROM `202_users_pref` WHERE `user_id` = ? LIMIT 1"
+            );
+            if ($stmt === false) {
+                error_log('[ConsentPolicy] exportForSync prepare failed: ' . $db->error);
+                return $unset;
+            }
+            $stmt->bind_param('i', $userId);
+            if (!$stmt->execute()) {
+                error_log('[ConsentPolicy] exportForSync execute failed: ' . $stmt->error);
+                $stmt->close();
+                return $unset;
+            }
+            $res = $stmt->get_result();
+            if ($res === false) {
+                // Fetch FAILURE, not a missing row (see docblock).
+                error_log('[ConsentPolicy] exportForSync get_result failed: ' . $stmt->error);
+                $stmt->close();
+                return $unset;
+            }
+            $row = $res->fetch_assoc();
+            $stmt->close();
+        } catch (\Throwable $e) {
+            error_log('[ConsentPolicy] exportForSync failed: ' . $e->getMessage());
+            return $unset;
+        }
+        // Genuine missing row: the user truly never answered — same
+        // fail-closed all-unset shape, via the no-row path.
+        if (!$row) { return $unset; }
+
+        $states = ['granted', 'denied', 'unset'];
+        return [
+            'analytics'          => in_array($row['analytics_consent'] ?? '', $states, true)
+                ? (string) $row['analytics_consent'] : 'unset',
+            'analytics_source'   => isset($row['analytics_consent_source']) ? (string) $row['analytics_consent_source'] : null,
+            'analytics_at'       => isset($row['analytics_consent_at']) ? (string) $row['analytics_consent_at'] : null,
+            'email_marketing'    => in_array($row['email_marketing_consent'] ?? '', $states, true)
+                ? (string) $row['email_marketing_consent'] : 'unset',
+            'email_marketing_at' => isset($row['email_marketing_consent_at']) ? (string) $row['email_marketing_consent_at'] : null,
+        ];
+    }
+
     public static function needsEuPrompt(mysqli $db, int $userId): bool
     {
         $row = self::loadPref($db, $userId);
diff --git a/202-config/Messaging/MessagingClient.class.php b/202-config/Messaging/MessagingClient.class.php
index 59a722f4..eeb0cc3c 100644
--- a/202-config/Messaging/MessagingClient.class.php
+++ b/202-config/Messaging/MessagingClient.class.php
@@ -87,16 +87,24 @@ public function markRead(array $identity, array $externalIds): ?array
      *
      * @param array      $identity   Identity payload.
      * @param array      $attributes Latest custom-attribute snapshot.
-     * @param array<int,array> $events Queued events (name/metadata/occurred_at/client_token).
+     * @param array<int,array> $events Queued events (name/metadata/occurred_at/client_token/tier).
+     * @param array|null $consent    Consent block (receiver spec §6 delta); when
+     *                               non-null it is sent as a TOP-LEVEL sibling of
+     *                               identity/attributes/events. Null preserves the
+     *                               pre-delta wire shape (backward-compatible).
      * @return array|null Decoded response, or null on failure.
      */
-    public function track(array $identity, array $attributes, array $events): ?array
+    public function track(array $identity, array $attributes, array $events, ?array $consent = null): ?array
     {
-        return $this->postJson('track', [
+        $payload = [
             'identity'   => $identity,
             'attributes' => (object) $attributes,
             'events'     => array_values($events),
-        ]);
+        ];
+        if ($consent !== null) {
+            $payload['consent'] = $consent;
+        }
+        return $this->postJson('track', $payload);
     }
 
     /**
diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index 2a345439..a56a6f47 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -33,6 +33,8 @@ class MessagingService
     private ?MessagingClient $client = null;
     /** Cached consent decision for this instance (one lookup per sync run). */
     private ?bool $analyticsSyncAllowed = null;
+    /** Cached consent export for this instance (one lookup per sync run). */
+    private ?array $consentExport = null;
 
     /**
      * @param array<string,mixed> $identity Identity payload for the central API.
@@ -138,12 +140,32 @@ private function analyticsSyncAllowed(): bool
         return $this->analyticsSyncAllowed;
     }
 
+    /**
+     * Consent state as sent to the central server (receiver spec §6 delta).
+     * Operational bookkeeping: attached for ALL users — including
+     * analytics-denied ones, since the server must learn a user is denied —
+     * so it is NOT gated on analyticsSyncAllowed(). ConsentPolicy stays the
+     * only reader of the raw consent columns; exportForSync never throws and
+     * fails closed to the all-unset shape. Cached per instance like
+     * analyticsSyncAllowed() so a sync run performs one export read.
+     *
+     * @return array<string,string|null>
+     */
+    private function consentExport(): array
+    {
+        if ($this->consentExport === null) {
+            $this->consentExport = ConsentPolicy::exportForSync($this->db, $this->userId);
+        }
+        return $this->consentExport;
+    }
+
     /**
      * Identity payload as sent over the wire. The stored attribute snapshot
      * is analytics-tier data (the offer profile + client custom attributes),
      * so it is stripped for non-consented users — only essential identity
      * fields (install hash, email, registration date) may leave the install
-     * (spec §9). Every client() call site must use this, never raw identity.
+     * (spec §9). The consent export always rides along (spec §6). Every
+     * client() call site must use this, never raw identity.
      *
      * @return array<string,mixed>
      */
@@ -153,6 +175,12 @@ private function outboundIdentity(): array
         if (!$this->analyticsSyncAllowed()) {
             unset($identity['attributes']);
         }
+        // Deliberately outside the strip above: the denied state itself must
+        // reach the server (spec §6 — absence reads as "unset", not "denied",
+        // and an explicit denial is what stops server-side email marketing).
+        // The export is total (fail-closed all-unset on any lookup failure),
+        // so the attach is unconditional.
+        $identity['consent'] = $this->consentExport();
         return $identity;
     }
 
@@ -966,7 +994,9 @@ private function flushEvents(): void
         }, $events);
 
         $attributes = $analyticsAllowed ? $this->getAttributes() : [];
-        $response = $this->client()->track($this->outboundIdentity(), $attributes, $payloadEvents);
+        // The consent block is passed top-level for ALL users (spec §6): a
+        // denied user's flush still tells the server the user is denied.
+        $response = $this->client()->track($this->outboundIdentity(), $attributes, $payloadEvents, $this->consentExport());
 
         if ($response === null) {
             // Bump attempts so poison events eventually stop being retried.
diff --git a/tests/Messaging/ConsentSyncBlockTest.php b/tests/Messaging/ConsentSyncBlockTest.php
new file mode 100644
index 00000000..a2b51547
--- /dev/null
+++ b/tests/Messaging/ConsentSyncBlockTest.php
@@ -0,0 +1,307 @@
+<?php
+// tests/Messaging/ConsentSyncBlockTest.php
+use PHPUnit\Framework\TestCase;
+require_once __DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/MessagingClient.class.php';
+require_once __DIR__ . '/../../202-config/Messaging/MessagingService.class.php';
+
+/**
+ * Captures wire calls so the consent block can be asserted on the exact
+ * identity payload that would have been transmitted — DB-less counterpart of
+ * ConsentSyncFakeClient in ConsentSyncIntegrationTest.
+ */
+final class ConsentBlockFakeClient extends MessagingClient
+{
+    /** @var array<int,array{identity:array,cursor:?string}> */
+    public array $pullCalls = [];
+    /** @var array<int,array{identity:array,attributes:array,events:array,consent:?array}> */
+    public array $trackCalls = [];
+
+    public function pull(array $identity, ?string $cursor): ?array
+    {
+        $this->pullCalls[] = ['identity' => $identity, 'cursor' => $cursor];
+        return ['conversations' => [], 'cursor' => 'cur-1'];
+    }
+
+    public function send(array $identity, ?string $conversationExternalId, string $body, string $clientToken): ?array
+    {
+        return null;
+    }
+
+    public function markRead(array $identity, array $externalIds): ?array
+    {
+        return ['ok' => true];
+    }
+
+    public function track(array $identity, array $attributes, array $events, ?array $consent = null): ?array
+    {
+        $this->trackCalls[] = ['identity' => $identity, 'attributes' => $attributes, 'events' => $events, 'consent' => $consent];
+        return ['ok' => true];
+    }
+}
+
+/**
+ * Receiver spec §6 CONTRACT DELTA: the client must transmit its consent state
+ * to the central server — attached to identity on every endpoint and as a
+ * TOP-LEVEL "consent" block in the /track body. Consent state is operational
+ * bookkeeping: it is sent for ALL users, including analytics-denied ones (the
+ * server must learn a user is denied), so it must never ride inside the
+ * attributes-strip branch.
+ *
+ * Failure semantics (the contract): on ANY DB failure or a genuine missing
+ * row, exportForSync returns the explicit all-unset shape — absence/unset
+ * must read as "no grant" server-side (fail closed), so a failure can never
+ * masquerade as a grant on the wire. Failure and missing-row remain
+ * distinguished inside exportForSync (a false get_result() on a SELECT is a
+ * fetch FAILURE, logged as one; a genuine zero-row SELECT still yields a
+ * mysqli_result) even though both export the same fail-closed shape.
+ * Behavioral proof for the DB read lives in ConsentSyncIntegrationTest-style
+ * DB-gated tests; these are source guards plus the DB-less fail-closed checks.
+ */
+final class ConsentSyncBlockTest extends TestCase
+{
+    private const ALL_UNSET = [
+        'analytics'          => 'unset',
+        'analytics_source'   => null,
+        'analytics_at'       => null,
+        'email_marketing'    => 'unset',
+        'email_marketing_at' => null,
+    ];
+
+    private function policySrc(): string
+    {
+        return file_get_contents(__DIR__ . '/../../202-config/Messaging/ConsentPolicy.class.php');
+    }
+
+    private function serviceSrc(): string
+    {
+        return file_get_contents(__DIR__ . '/../../202-config/Messaging/MessagingService.class.php');
+    }
+
+    private function clientSrc(): string
+    {
+        return file_get_contents(__DIR__ . '/../../202-config/Messaging/MessagingClient.class.php');
+    }
+
+    // ------------------------------------------------------------------
+    // ConsentPolicy::exportForSync — the ONLY reader of raw consent columns
+    // ------------------------------------------------------------------
+
+    public function test_export_for_sync_exists_and_selects_all_five_columns(): void
+    {
+        $src = $this->policySrc();
+        $this->assertStringContainsString(
+            'public static function exportForSync(mysqli $db, int $userId): array',
+            $src,
+            'ConsentPolicy must expose exportForSync(mysqli, int): array (never null — the contract shape is total)'
+        );
+        // The SELECT inside exportForSync must read all five consent columns.
+        // (loadPref reads only the two enum columns; record() only writes.)
+        $this->assertMatchesRegularExpression(
+            '/function exportForSync.*?SELECT.*?`analytics_consent`.*?`analytics_consent_source`.*?`analytics_consent_at`.*?`email_marketing_consent`.*?`email_marketing_consent_at`.*?FROM `202_users_pref`/s',
+            $src,
+            'exportForSync must SELECT all five consent columns from 202_users_pref'
+        );
+    }
+
+    public function test_export_fails_closed_to_all_unset_on_db_failure(): void
+    {
+        // Same failure shape as ConsentPolicyTest: prepare() fails (mid-retry
+        // migration under the UI path's non-throwing mysqli report mode).
+        $db = $this->createMock(mysqli::class);
+        $db->method('prepare')->willReturn(false);
+
+        $this->assertSame(self::ALL_UNSET, ConsentPolicy::exportForSync($db, 7),
+            'a lookup failure must export the all-unset shape (fail closed: absence reads as "no grant" server-side)');
+    }
+
+    public function test_export_fails_closed_to_all_unset_on_get_result_failure(): void
+    {
+        // A successful SELECT always yields a mysqli_result, even with zero
+        // rows. get_result() === false is therefore a fetch FAILURE
+        // (server-gone-away mid-fetch, mysqlnd OOM) — NOT a missing row —
+        // and must take the failure path, not the missing-row path.
+        $stmt = $this->createMock(mysqli_stmt::class);
+        $stmt->method('bind_param')->willReturn(true);
+        $stmt->method('execute')->willReturn(true);
+        $stmt->method('get_result')->willReturn(false);
+        $stmt->method('close')->willReturn(true);
+
+        $db = $this->createMock(mysqli::class);
+        $db->method('prepare')->willReturn($stmt);
+
+        $this->assertSame(self::ALL_UNSET, ConsentPolicy::exportForSync($db, 7),
+            'a get_result() fetch failure must export the fail-closed all-unset shape');
+    }
+
+    public function test_export_returns_all_unset_for_a_genuine_missing_row(): void
+    {
+        // prepare/bind/execute succeed and the SELECT yields a result set
+        // with zero rows (fetch_assoc() → null): a user with no
+        // 202_users_pref row genuinely never answered. Same fail-closed
+        // all-unset shape, but via the missing-row path, not the failure path.
+        $result = $this->createMock(mysqli_result::class);
+        $result->method('fetch_assoc')->willReturn(null);
+
+        $stmt = $this->createMock(mysqli_stmt::class);
+        $stmt->method('bind_param')->willReturn(true);
+        $stmt->method('execute')->willReturn(true);
+        $stmt->method('get_result')->willReturn($result);
+        $stmt->method('close')->willReturn(true);
+
+        $db = $this->createMock(mysqli::class);
+        $db->method('prepare')->willReturn($stmt);
+
+        $this->assertSame(self::ALL_UNSET, ConsentPolicy::exportForSync($db, 7),
+            'a genuine missing row (zero-row result set) must export the all-unset shape');
+    }
+
+    public function test_export_distinguishes_fetch_failure_from_missing_row(): void
+    {
+        // Guard the loadPref-style raw-mysqli checks: exportForSync must not
+        // route through a helper that conflates get_result() === false with a
+        // zero-row result (Connection::fetchOne does). CLAUDE.md #5 — the
+        // same failure class is already handled correctly in loadPref.
+        $src = $this->policySrc();
+        preg_match('/function exportForSync.*?\n    \}/s', $src, $m);
+        $this->assertNotEmpty($m, 'exportForSync must exist');
+        $body = $m[0];
+        $this->assertStringContainsString('get_result()', $body,
+            'exportForSync must inspect get_result() itself (mirroring loadPref)');
+        $this->assertMatchesRegularExpression('/\$res === false/', $body,
+            'exportForSync must treat get_result() === false as a fetch failure, distinct from a zero-row result');
+        $this->assertStringNotContainsString('fetchOne', $body,
+            'Connection::fetchOne conflates a get_result() failure with a missing row — exportForSync must not use it');
+    }
+
+    public function test_consent_policy_stays_the_only_reader_of_raw_consent_columns(): void
+    {
+        // Neither MessagingService nor MessagingClient may touch the raw
+        // consent columns — they consume ConsentPolicy's export only.
+        foreach (['MessagingService' => $this->serviceSrc(), 'MessagingClient' => $this->clientSrc()] as $name => $src) {
+            $this->assertStringNotContainsString('analytics_consent', $src,
+                "{$name} must not read raw consent columns");
+            $this->assertStringNotContainsString('email_marketing_consent', $src,
+                "{$name} must not read raw consent columns");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // MessagingService — consent attached to identity for ALL users
+    // ------------------------------------------------------------------
+
+    public function test_outbound_identity_attaches_consent_export_unconditionally(): void
+    {
+        $src = $this->serviceSrc();
+        preg_match(
+            '/private function outboundIdentity\(\): array.*?\n    \}/s',
+            $src,
+            $m
+        );
+        $this->assertNotEmpty($m, 'outboundIdentity() must exist');
+        $body = $m[0];
+        $this->assertStringContainsString("\$identity['consent'] = \$this->consentExport();", $body,
+            'outboundIdentity() must attach the cached consent export');
+        $this->assertStringNotContainsString('!== null', $body,
+            'the attach must be unconditional — exportForSync is total (fail-closed all-unset), never null');
+    }
+
+    public function test_consent_is_not_stripped_with_attributes(): void
+    {
+        $src = $this->serviceSrc();
+        // Extract the attributes-strip branch and prove consent is NOT inside
+        // it: denied users must still transmit their (denied) consent state.
+        preg_match('/if \(!\$this->analyticsSyncAllowed\(\)\) \{[^}]*\}/s', $src, $m);
+        $this->assertNotEmpty($m, 'the attributes-strip branch must exist');
+        $this->assertStringNotContainsString('consent', $m[0],
+            'consent is operational bookkeeping — it must not sit under the attributes-strip branch');
+        $this->assertStringContainsString("unset(\$identity['attributes'])", $m[0]);
+    }
+
+    public function test_consent_export_is_cached_per_request(): void
+    {
+        $src = $this->serviceSrc();
+        $this->assertStringContainsString('private ?array $consentExport = null;', $src,
+            'the export must be cached per instance like analyticsSyncAllowed');
+        $this->assertMatchesRegularExpression(
+            '/private function consentExport\(\): array\s*\{\s*if \(\$this->consentExport === null\) \{.*?ConsentPolicy::exportForSync\(\$this->db, \$this->userId\)/s',
+            $src,
+            'consentExport() must null-check-cache ConsentPolicy::exportForSync exactly the way analyticsSyncAllowed() caches'
+        );
+        $this->assertStringNotContainsString('consentExportLoaded', $src,
+            'no extra loaded flag: the export is total (never null), so the null check alone guards the cache');
+    }
+
+    public function test_track_flush_passes_the_cached_export_top_level(): void
+    {
+        $this->assertMatchesRegularExpression(
+            '/client\(\)->track\(\s*\$this->outboundIdentity\(\),\s*\$attributes,\s*\$payloadEvents,\s*\$this->consentExport\(\)\s*\)/',
+            $this->serviceSrc(),
+            'flushEvents must pass the same cached export as the top-level /track consent block'
+        );
+    }
+
+    public function test_db_failure_still_transmits_the_fail_closed_all_unset_block(): void
+    {
+        // Every DB call fails (prepare → false): the transient-failure window.
+        // The sync must still run, and the identity that reaches the wire must
+        // carry the explicit fail-closed all-unset consent block (the contract:
+        // absence/unset reads as "no grant" server-side).
+        $db = $this->createMock(mysqli::class);
+        $db->method('prepare')->willReturn(false);
+
+        $service = new MessagingService($db, 7, [
+            'install_hash' => 'h',
+            'api_key'      => 'k',
+            'user_id'      => 7,
+            'attributes'   => ['clicks_30d' => 9],
+        ]);
+        $fake = new ConsentBlockFakeClient();
+        $prop = new ReflectionProperty(MessagingService::class, 'client');
+        $prop->setAccessible(true);
+        $prop->setValue($service, $fake);
+
+        $service->sync(true);
+
+        $this->assertCount(1, $fake->pullCalls);
+        $identity = $fake->pullCalls[0]['identity'];
+        $this->assertSame(self::ALL_UNSET, $identity['consent'] ?? null,
+            'a DB failure must transmit the fail-closed all-unset consent block, never an accidental grant');
+        // The consent lookup failing also means analyticsAllowed fails closed,
+        // so the analytics-tier snapshot must be stripped as before.
+        $this->assertArrayNotHasKey('attributes', $identity,
+            'a consent lookup failure must still fail CLOSED for the attribute snapshot');
+    }
+
+    // ------------------------------------------------------------------
+    // MessagingClient::track — optional, backward-compatible consent param
+    // ------------------------------------------------------------------
+
+    public function test_track_signature_accepts_optional_nullable_consent(): void
+    {
+        $method = new ReflectionMethod(MessagingClient::class, 'track');
+        $params = $method->getParameters();
+        $this->assertCount(4, $params, 'track() must gain exactly one extra parameter');
+
+        $consent = $params[3];
+        $this->assertSame('consent', $consent->getName());
+        $this->assertTrue($consent->allowsNull(), 'consent must be nullable (?array)');
+        $this->assertTrue($consent->isDefaultValueAvailable(), 'consent must default (backward-compatible)');
+        $this->assertNull($consent->getDefaultValue(), 'consent must default to null');
+        $type = $consent->getType();
+        $this->assertInstanceOf(ReflectionNamedType::class, $type);
+        $this->assertSame('array', $type->getName());
+    }
+
+    public function test_track_payload_includes_top_level_consent_when_present(): void
+    {
+        $src = $this->clientSrc();
+        preg_match('/public function track\(.*?\n    \}/s', $src, $m);
+        $this->assertNotEmpty($m, 'track() must exist');
+        $body = $m[0];
+        // Top-level sibling of identity/attributes/events (spec §6), only
+        // when non-null so older call sites keep the old wire shape.
+        $this->assertStringContainsString('if ($consent !== null) {', $body);
+        $this->assertStringContainsString("\$payload['consent'] = \$consent;", $body);
+    }
+}
diff --git a/tests/Messaging/ConsentSyncIntegrationTest.php b/tests/Messaging/ConsentSyncIntegrationTest.php
index c006b833..e2c3c888 100644
--- a/tests/Messaging/ConsentSyncIntegrationTest.php
+++ b/tests/Messaging/ConsentSyncIntegrationTest.php
@@ -18,7 +18,7 @@
  */
 final class ConsentSyncFakeClient extends MessagingClient
 {
-    /** @var array<int,array{identity:array,attributes:array,events:array}> */
+    /** @var array<int,array{identity:array,attributes:array,events:array,consent:?array}> */
     public array $trackCalls = [];
     /** @var array<int,array{identity:array,cursor:?string}> */
     public array $pullCalls = [];
@@ -39,9 +39,9 @@ public function markRead(array $identity, array $externalIds): ?array
         return ['ok' => true];
     }
 
-    public function track(array $identity, array $attributes, array $events): ?array
+    public function track(array $identity, array $attributes, array $events, ?array $consent = null): ?array
     {
-        $this->trackCalls[] = ['identity' => $identity, 'attributes' => $attributes, 'events' => $events];
+        $this->trackCalls[] = ['identity' => $identity, 'attributes' => $attributes, 'events' => $events, 'consent' => $consent];
         return ['ok' => true];
     }
 }
@@ -293,6 +293,12 @@ public function test_sync_transmits_only_essential_rows_when_analytics_held(): v
         $this->assertSame([], $track['attributes'], 'the analytics snapshot must not sync');
         $this->assertArrayNotHasKey('attributes', $track['identity'],
             'identity must not embed the attribute snapshot for a non-consented user');
+        // Spec §6 delta: the consent block still travels for a held user —
+        // absence would read as "unset" server-side, but so must "held".
+        $this->assertSame('unset', $track['consent']['analytics'] ?? null,
+            'the /track consent block must travel even when analytics is held');
+        $this->assertSame('unset', $track['identity']['consent']['analytics'] ?? null,
+            'identity.consent must travel even when attributes are stripped');
         $this->assertCount(1, $fake->pullCalls);
         $this->assertArrayNotHasKey('attributes', $fake->pullCalls[0]['identity'],
             'pull identity re-transmitted the profile — the revocation leak the review flagged');
@@ -330,6 +336,9 @@ public function test_sync_transmits_analytics_rows_and_snapshot_when_granted():
         $this->assertSame(9, $track['attributes']['clicks_30d'] ?? null);
         $this->assertSame(9, $track['identity']['attributes']['clicks_30d'] ?? null,
             'consented identity carries the snapshot as before');
+        $this->assertSame('granted', $track['consent']['analytics'] ?? null,
+            'the /track consent block must carry the granted state (spec §6)');
+        $this->assertSame('eu_prompt', $track['consent']['analytics_source'] ?? null);
 
         $rows = $this->eventRows();
         $this->assertSame([['login', 'essential', 'sent'], ['page_viewed', 'analytics', 'sent']],

From 259c9963defed29969bea6872ff60342d0a0bdb5 Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 20:44:38 -0700
Subject: [PATCH 19/20] docs(messaging): sync CENTRAL-API contract with tier,
 consent block, nested profile

---
 202-config/Messaging/CENTRAL-API.md | 60 ++++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 10 deletions(-)

diff --git a/202-config/Messaging/CENTRAL-API.md b/202-config/Messaging/CENTRAL-API.md
index 5ba1a1ce..7825f0d2 100644
--- a/202-config/Messaging/CENTRAL-API.md
+++ b/202-config/Messaging/CENTRAL-API.md
@@ -49,8 +49,16 @@ install with `api_key` + `install_hash` and uses the remaining fields for **targ
     "registered_at": "2024-01-02 03:04:05",
     "attributes": {
       "plan": "pro",
-      "monthly_clicks": 18204,
-      "trackers_created": 12
+      "clicks_30d": 18204,
+      "offers": [ { "name": "…", "url": "…", "payout": 38.0 } ],
+      "ltv": { "mrr": 546.0, "customers": 32 }
+    },
+    "consent": {
+      "analytics":          "granted",
+      "analytics_source":   "settings",
+      "analytics_at":       "2026-07-16 16:09:24",
+      "email_marketing":    "granted",
+      "email_marketing_at": "2026-07-16 09:48:05"
     }
   }
 }
@@ -64,11 +72,25 @@ install with `api_key` + `install_hash` and uses the remaining fields for **targ
 | `user_email`   | `202_users.user_email`                   | Targeting / display on central side  |
 | `registered_at`| `202_users.user_time_register`           | Cohort targeting (e.g. "new users")  |
 | `attributes`   | `202_messaging_attributes` snapshot      | **Custom attributes for segmentation** |
-
-`attributes` is the latest snapshot of custom attributes set by page JavaScript via
-`Prosper202Messenger('update', {...})` (see *Client JavaScript API* below). It is sent
-on **every** request so the central server always has fresh data to segment audiences on.
-Values are scalars (string/number/bool); nested objects are not guaranteed.
+| `consent`      | `202_users_pref` via `ConsentPolicy::exportForSync()` | **Consent bookkeeping** (see below) |
+
+`attributes` is the latest snapshot of the user's segmentation profile: the offer/volume
+profile computed by the sync cron (`OfferProfile::compute()` — 30-day volumes, per-offer
+detail, account-level LTV aggregates, feature flags) merged with any custom attributes set
+by page JavaScript via `Prosper202Messenger('update', {...})` (see *Client JavaScript API*
+below). Values may be **nested objects and arrays** (e.g. `offers[]`, `ltv`, `device_mix`);
+store them as JSON, not flat key/value pairs.
+
+**Consent-driven variance:** the attribute snapshot is analytics-tier data. For users who
+have not granted analytics consent, the client **omits `identity.attributes` entirely**.
+Treat a missing `attributes` key as "no consent", not as an empty profile — and never wipe
+a previously-stored profile because a request arrived without one.
+
+`consent` is attached for **all** users — including analytics-denied ones — because the
+server must know a user is denied. Semantics: each flag is `granted|denied|unset`;
+anything other than an explicit `email_marketing: "granted"` (including a missing
+`consent` object from an older client) means **no marketing email** to that user.
+Analytics consent and email consent are independent flags.
 
 If `api_key`/`install_hash` do not validate, respond `401`. The client degrades
 gracefully (shows cached data, no error to the user).
@@ -222,16 +244,24 @@ snapshot plus several events at once.
 ```json
 {
   "identity": { ... },
+  "consent": {
+    "analytics":          "granted",
+    "analytics_source":   "settings",
+    "analytics_at":       "2026-07-16 16:09:24",
+    "email_marketing":    "granted",
+    "email_marketing_at": "2026-07-16 09:48:05"
+  },
   "attributes": {
     "plan": "pro",
-    "monthly_clicks": 18204
+    "clicks_30d": 18204
   },
   "events": [
     {
-      "name": "created_tracker",
+      "name": "tracker_created",
       "metadata": { "tracker_id": 42, "source": "google" },
       "occurred_at": "2026-06-16 07:05:00",
-      "client_token": "uuid for idempotency"
+      "client_token": "uuid for idempotency",
+      "tier": "analytics"
     }
   ]
 }
@@ -245,6 +275,16 @@ snapshot plus several events at once.
 
 - `attributes` mirrors what is sent inside `identity.attributes`; it is included here too
   so a dedicated flush can update the central profile even when no message is pulled.
+  For non-consented users the client sends `{}` — treat that as "no update", never as an
+  instruction to clear the stored profile.
+- `consent` is the same block as `identity.consent` (top-level here per the receiver
+  contract); store the latest values. Tolerate its absence (older clients) and fail closed:
+  no explicit `email_marketing: "granted"` means no marketing email.
+- Every event carries `tier`: `"essential"` (operational/lifecycle — arrives for all users;
+  usable for support and account operations) or `"analytics"` (behavioural — arrives only
+  for consented users; usable for segmentation and marketing). Store it; never treat an
+  unrecognized tier as `essential`, and never feed essential-only users into marketing
+  segmentation.
 - Each event has a `client_token`; treat repeated tokens as idempotent so retries do not
   double-count.
 - The central server stores attributes on the user profile and records events on a

From 0165543e22e047e33bd4fa590fae1f456cce763c Mon Sep 17 00:00:00 2001
From: Nana <nana@tracking202.com>
Date: Thu, 16 Jul 2026 20:59:05 -0700
Subject: [PATCH 20/20] docs(messaging): relocate central API contract to
 internal docs repo

---
 202-config/Messaging/CENTRAL-API.md           | 386 ------------------
 202-config/Messaging/MOCK-SERVER.md           |   2 +-
 .../Messaging/MessagingClient.class.php       |   3 +-
 .../Messaging/MessagingService.class.php      |   2 +-
 202-config/Messaging/mock-server.php          |   2 +-
 202-config/connect.php                        |   2 +-
 6 files changed, 6 insertions(+), 391 deletions(-)
 delete mode 100644 202-config/Messaging/CENTRAL-API.md

diff --git a/202-config/Messaging/CENTRAL-API.md b/202-config/Messaging/CENTRAL-API.md
deleted file mode 100644
index 7825f0d2..00000000
--- a/202-config/Messaging/CENTRAL-API.md
+++ /dev/null
@@ -1,386 +0,0 @@
-# Prosper202 Messaging — Central Server API Contract
-
-This document defines the HTTP API that the **central server** (`my.tracking202.com`)
-must implement so that self-hosted Prosper202 installs (the *client*) can deliver an
-Intercom-style messenger to their users.
-
-The client side (this repository) is implemented in:
-
-- `202-config/Messaging/MessagingClient.class.php` — HTTP transport
-- `202-config/Messaging/MessagingService.class.php` — local cache + sync orchestration
-- `202-account/ajax/messaging/*.php` — browser endpoints
-- `202-js/messenger.js`, `202-css/messenger.css` — the floating widget
-- `202-cronjobs/sync-messaging.php` — proactive background delivery
-
-Because each Prosper202 install is self-hosted and can only make **outbound** HTTPS
-requests, all communication is **client-initiated (pull)**. The central server never
-connects to an install. The client polls; the central server queues.
-
----
-
-## Base URL
-
-```
-https://my.tracking202.com/api/v3/messaging
-```
-
-Configured client-side as `MESSAGING_API_URL` in `202-config/connect.php`.
-
-## Transport
-
-- All requests are `POST` with a JSON body and `Content-Type: application/json`.
-- All responses are JSON with `Content-Type: application/json` and HTTP `200` on success.
-- Non-`200` responses are treated as failures; the client keeps its local cache and retries later.
-- TLS certificate verification is enforced (`CURLOPT_SSL_VERIFYPEER`/`VERIFYHOST`). Use a valid certificate.
-
-## Authentication & identity
-
-Every request body includes an `identity` object. The central server authenticates the
-install with `api_key` + `install_hash` and uses the remaining fields for **targeting**
-(broadcasts to a customer/cohort) and **routing** (which user a conversation belongs to).
-
-```json
-{
-  "identity": {
-    "install_hash":  "32-char install identifier",
-    "api_key":       "p202_customer_api_key for this install",
-    "user_id":       123,
-    "user_email":    "user@example.com",
-    "registered_at": "2024-01-02 03:04:05",
-    "attributes": {
-      "plan": "pro",
-      "clicks_30d": 18204,
-      "offers": [ { "name": "…", "url": "…", "payout": 38.0 } ],
-      "ltv": { "mrr": 546.0, "customers": 32 }
-    },
-    "consent": {
-      "analytics":          "granted",
-      "analytics_source":   "settings",
-      "analytics_at":       "2026-07-16 16:09:24",
-      "email_marketing":    "granted",
-      "email_marketing_at": "2026-07-16 09:48:05"
-    }
-  }
-}
-```
-
-| Field          | Source (client)                          | Purpose                              |
-|----------------|------------------------------------------|--------------------------------------|
-| `install_hash` | `202_users.install_hash`                 | Identifies the installation          |
-| `api_key`      | `202_users.p202_customer_api_key`        | Authenticates the customer account   |
-| `user_id`      | local `202_users.user_id`                | Routes conversations to a user       |
-| `user_email`   | `202_users.user_email`                   | Targeting / display on central side  |
-| `registered_at`| `202_users.user_time_register`           | Cohort targeting (e.g. "new users")  |
-| `attributes`   | `202_messaging_attributes` snapshot      | **Custom attributes for segmentation** |
-| `consent`      | `202_users_pref` via `ConsentPolicy::exportForSync()` | **Consent bookkeeping** (see below) |
-
-`attributes` is the latest snapshot of the user's segmentation profile: the offer/volume
-profile computed by the sync cron (`OfferProfile::compute()` — 30-day volumes, per-offer
-detail, account-level LTV aggregates, feature flags) merged with any custom attributes set
-by page JavaScript via `Prosper202Messenger('update', {...})` (see *Client JavaScript API*
-below). Values may be **nested objects and arrays** (e.g. `offers[]`, `ltv`, `device_mix`);
-store them as JSON, not flat key/value pairs.
-
-**Consent-driven variance:** the attribute snapshot is analytics-tier data. For users who
-have not granted analytics consent, the client **omits `identity.attributes` entirely**.
-Treat a missing `attributes` key as "no consent", not as an empty profile — and never wipe
-a previously-stored profile because a request arrived without one.
-
-`consent` is attached for **all** users — including analytics-denied ones — because the
-server must know a user is denied. Semantics: each flag is `granted|denied|unset`;
-anything other than an explicit `email_marketing: "granted"` (including a missing
-`consent` object from an older client) means **no marketing email** to that user.
-Analytics consent and email consent are independent flags.
-
-If `api_key`/`install_hash` do not validate, respond `401`. The client degrades
-gracefully (shows cached data, no error to the user).
-
----
-
-## Targeting model (server-side)
-
-Targeting is entirely the central server's responsibility. Both modes Intercom offers
-are supported by the same `pull` response:
-
-- **Broadcast / one-way** — the server creates a `type: "broadcast"` conversation for
-  every user matching an audience (all users, a plan, a signup cohort, a specific
-  `user_id`, etc.). The user may reply, which upgrades it into a two-way thread.
-- **Two-way conversation** — the server creates/continues a `type: "conversation"`
-  thread for a specific user, and support agents reply into it.
-
-The client does not filter or target; it simply renders whatever `pull` returns for the
-identified user.
-
----
-
-## Endpoints
-
-### `POST /pull`
-
-Returns all conversations and messages visible to the identified user. The client
-upserts the result into its local cache keyed by `external_id`, so the endpoint may
-return either full state or only changes since `cursor`.
-
-**Request**
-
-```json
-{
-  "identity": { ... },
-  "cursor": "opaque string from previous pull, or null on first sync"
-}
-```
-
-**Response**
-
-```json
-{
-  "ok": true,
-  "server_time": "2026-06-16 07:00:00",
-  "cursor": "opaque-cursor-to-send-next-time",
-  "conversations": [
-    {
-      "external_id": "conv_abc123",
-      "type": "conversation",          // "conversation" | "broadcast"
-      "subject": "Welcome to Prosper202",
-      "status": "open",                 // "open" | "closed"
-      "last_message_at": "2026-06-16 06:59:00",
-      "messages": [
-        {
-          "external_id": "msg_001",
-          "direction": "inbound",       // "inbound" (team→user) | "outbound" (user→team)
-          "author": "team",             // "team" | "system" | "user"
-          "body": "Hi! Need a hand getting set up?",
-          "created_at": "2026-06-16 06:59:00"
-        }
-      ]
-    }
-  ],
-  "deleted_conversation_ids": ["conv_retracted1"]
-}
-```
-
-Notes:
-- `deleted_conversation_ids` (optional) is an array of conversation `external_id`s the
-  server has retracted/removed; the client deletes those conversations and their messages
-  from its local cache. Omit it (or send `[]`) when there is nothing to delete.
-- `direction` is from the **user's** perspective: `inbound` = received, `outbound` = sent.
-- `body` is plain text. The client HTML-escapes it before rendering. Do not send HTML.
-- `cursor` is opaque to the client and echoed back on the next `pull`. Use it to return
-  only deltas; returning full state every time is also valid (the client upserts).
-- Messages the user already sent (echoed back with a real `external_id`) let the client
-  reconcile its locally-queued copies via `client_token` (see `send`).
-
-### `POST /send`
-
-Delivers a message the user composed in the widget.
-
-**Request**
-
-```json
-{
-  "identity": { ... },
-  "conversation_external_id": "conv_abc123 or null to start a new thread",
-  "body": "plain text the user typed",
-  "client_token": "uuid generated by the client for idempotency"
-}
-```
-
-**Response**
-
-```json
-{
-  "ok": true,
-  "conversation": {
-    "external_id": "conv_abc123",
-    "type": "conversation",
-    "subject": "Welcome to Prosper202",
-    "status": "open"
-  },
-  "message": {
-    "external_id": "msg_042",
-    "client_token": "the uuid from the request",
-    "direction": "outbound",
-    "author": "user",
-    "body": "plain text the user typed",
-    "created_at": "2026-06-16 07:01:00"
-  }
-}
-```
-
-- `client_token` **must** be echoed back so the client can match the server's canonical
-  message to the optimistic local copy and avoid duplicates. Treat repeated
-  `client_token`s as idempotent (return the same message).
-- If `conversation_external_id` is null, create a new `conversation` thread and return it.
-
-### `POST /read`
-
-Reports which inbound messages the user has read (for agent-side read receipts).
-
-**Request**
-
-```json
-{
-  "identity": { ... },
-  "message_external_ids": ["msg_001", "msg_002"]
-}
-```
-
-**Response**
-
-```json
-{ "ok": true }
-```
-
-This is advisory; the client also tracks read state locally for its unread badge.
-
-### `POST /track`
-
-Delivers custom attributes and behavioural events for **segmentation**. The client
-batches these (queued locally, flushed on sync) so a flush may carry the latest attribute
-snapshot plus several events at once.
-
-**Request**
-
-```json
-{
-  "identity": { ... },
-  "consent": {
-    "analytics":          "granted",
-    "analytics_source":   "settings",
-    "analytics_at":       "2026-07-16 16:09:24",
-    "email_marketing":    "granted",
-    "email_marketing_at": "2026-07-16 09:48:05"
-  },
-  "attributes": {
-    "plan": "pro",
-    "clicks_30d": 18204
-  },
-  "events": [
-    {
-      "name": "tracker_created",
-      "metadata": { "tracker_id": 42, "source": "google" },
-      "occurred_at": "2026-06-16 07:05:00",
-      "client_token": "uuid for idempotency",
-      "tier": "analytics"
-    }
-  ]
-}
-```
-
-**Response**
-
-```json
-{ "ok": true }
-```
-
-- `attributes` mirrors what is sent inside `identity.attributes`; it is included here too
-  so a dedicated flush can update the central profile even when no message is pulled.
-  For non-consented users the client sends `{}` — treat that as "no update", never as an
-  instruction to clear the stored profile.
-- `consent` is the same block as `identity.consent` (top-level here per the receiver
-  contract); store the latest values. Tolerate its absence (older clients) and fail closed:
-  no explicit `email_marketing: "granted"` means no marketing email.
-- Every event carries `tier`: `"essential"` (operational/lifecycle — arrives for all users;
-  usable for support and account operations) or `"analytics"` (behavioural — arrives only
-  for consented users; usable for segmentation and marketing). Store it; never treat an
-  unrecognized tier as `essential`, and never feed essential-only users into marketing
-  segmentation.
-- Each event has a `client_token`; treat repeated tokens as idempotent so retries do not
-  double-count.
-- The central server stores attributes on the user profile and records events on a
-  timeline, both usable to define audiences for broadcasts.
-
----
-
-## Client JavaScript API
-
-Page code on a Prosper202 install can feed the messenger exactly the way Intercom's
-JavaScript API works — a command queue on a single global function. The widget
-(`202-js/messenger.js`) installs this before it finishes loading, so calls made early
-are buffered and replayed.
-
-```js
-// Set/merge custom attributes on the current user (for segmentation):
-Prosper202Messenger('update', { plan: 'pro', monthly_clicks: 18204 });
-
-// Record a behavioural event (optionally with metadata):
-Prosper202Messenger('trackEvent', 'created_tracker', { tracker_id: 42 });
-
-// Control the widget:
-Prosper202Messenger('show');     // open the panel
-Prosper202Messenger('hide');     // close the panel
-Prosper202Messenger('toggle');   // toggle the panel
-```
-
-`update` and `trackEvent` POST to `202-account/ajax/messaging/track.php`, which persists
-the data locally (`202_messaging_attributes`, `202_messaging_events`) and forwards it to
-`POST /track` on the next sync. Attribute values should be scalars.
-
----
-
-## Error handling
-
-| Situation                         | Server response | Client behavior                         |
-|-----------------------------------|-----------------|-----------------------------------------|
-| Bad/missing auth                  | `401`           | Silent; keep cache; retry next cycle    |
-| Malformed request                 | `400`           | Logged; retried with backoff            |
-| Transient server error            | `5xx`           | Retried with exponential backoff        |
-| Success                           | `200` + `ok:true`| Cache updated                           |
-
-The client never surfaces raw transport errors to end users; the widget simply shows the
-last successfully cached state.
-
----
-
-## Known limitations & operational notes
-
-These are scale/architecture concerns, not bugs. For a typical self-hosted install (one
-operator or a small team, with a responsive central server) neither is noticeable. They
-matter for large multi-user installs or when the central server is slow/unreachable, and
-each needs an infrastructure or contract change to resolve — deliberately out of scope for
-the client-side implementation.
-
-### 1. The inbox poll syncs synchronously
-
-`202-account/ajax/messaging/inbox.php` calls `MessagingService::sync()` on every poll
-(~every 25s per open widget), which makes the outbound HTTPS calls to this API. It is
-throttled by `MESSAGING_SYNC_THROTTLE` (default 20s), and a failed sync still stamps
-`last_sync` so a down server is not re-hit within the window. But because the poll interval
-is longer than the throttle, most polls do reach the network, and PHP holds a web worker
-for the duration of that call. If this API is slow or down, each poll blocks up to
-~21s (10s timeout × 2 attempts + 1s pause); the browser degrades gracefully (it shows
-cached state), but enough concurrent users polling into a slow upstream can exhaust the
-front-end worker pool.
-
-- **Mitigations in place:** throttle + capped retries (2 attempts, 1s backoff); the widget
-  never blocks the page and always renders the last cached state.
-- **Proper fix (ops/infra):** make `inbox.php` read the local cache only, and move *all*
-  network sync into the `202-cronjobs/sync-messaging.php` cron (run it frequently and
-  monitor it). PHP has no built-in async, so a non-blocking request path requires either a
-  job runner/queue that owns the outbound calls, or `fastcgi_finish_request()` to flush the
-  response before syncing (still occupies a worker). This is a deployment decision, so it
-  belongs in the install runbook rather than the client code.
-
-### 2. The cron syncs users sequentially (no batch pull)
-
-`202-cronjobs/sync-messaging.php` iterates active users and calls
-`MessagingService::forUser($id)->sync(true)` one at a time. Each `sync()` is several HTTP
-round-trips (flush events, push pending messages, report receipts, pull), so total runtime
-is `N users × (several sequential calls)`. At hundreds/thousands of users the cron runtime
-balloons, one slow/timing-out user stalls the rest, and delivery latency grows.
-
-- **Proper fix (requires a central-API change):** add a **batched pull** so the cron can
-  fetch many users in one request, e.g.
-
-  ```
-  POST /pull/batch
-  { "install_hash": "...", "api_key": "...",
-    "users": [ { "user_id": 1, "cursor": "..." }, { "user_id": 2, "cursor": "..." } ] }
-  -> { "ok": true, "results": [ { "user_id": 1, "cursor": "...", "conversations": [...] }, ... ] }
-  ```
-
-  The cron would then page through users (e.g. 100 per request) instead of one request per
-  user. Client-only alternatives (`curl_multi` parallelism, sharding users across cron
-  workers) add complexity and still issue N requests at this server, so the real win is
-  server-side batch support. **This endpoint is not yet implemented** — until it exists, the
-  cron uses the per-user `POST /pull` above.
diff --git a/202-config/Messaging/MOCK-SERVER.md b/202-config/Messaging/MOCK-SERVER.md
index 89dc242d..038d91e2 100644
--- a/202-config/Messaging/MOCK-SERVER.md
+++ b/202-config/Messaging/MOCK-SERVER.md
@@ -2,7 +2,7 @@
 
 `mock-server.php` is a dependency-free stand-in for the central
 `my.tracking202.com` messaging API, so you can click through the messenger
-widget locally. It implements the contract in `CENTRAL-API.md`.
+widget locally. It implements the central messaging API contract.
 
 ## Run it
 
diff --git a/202-config/Messaging/MessagingClient.class.php b/202-config/Messaging/MessagingClient.class.php
index eeb0cc3c..b45cdc9a 100644
--- a/202-config/Messaging/MessagingClient.class.php
+++ b/202-config/Messaging/MessagingClient.class.php
@@ -10,7 +10,8 @@
  * (the install can only make outbound requests), so this class only ever POSTs
  * and reads the JSON response.
  *
- * The contract implemented here is documented in 202-config/Messaging/CENTRAL-API.md.
+ * The contract implemented here is exercised end-to-end by the local mock server
+ * (202-config/Messaging/mock-server.php, see MOCK-SERVER.md).
  *
  * Every method returns a decoded associative array on success, or null on any
  * transport/parse/HTTP failure. Callers must treat null as "could not reach the
diff --git a/202-config/Messaging/MessagingService.class.php b/202-config/Messaging/MessagingService.class.php
index a56a6f47..f6027a35 100644
--- a/202-config/Messaging/MessagingService.class.php
+++ b/202-config/Messaging/MessagingService.class.php
@@ -271,7 +271,7 @@ private function applyPull(array $response): void
             }
 
             // Optional: the server may signal conversations it has removed/retracted
-            // so the local cache doesn't keep them forever (see CENTRAL-API.md).
+            // so the local cache doesn't keep them forever (per the central API contract).
             if (isset($response['deleted_conversation_ids']) && is_array($response['deleted_conversation_ids'])) {
                 $this->deleteConversations($response['deleted_conversation_ids']);
             }
diff --git a/202-config/Messaging/mock-server.php b/202-config/Messaging/mock-server.php
index e03eb0fa..ca2f8569 100644
--- a/202-config/Messaging/mock-server.php
+++ b/202-config/Messaging/mock-server.php
@@ -7,7 +7,7 @@
  *
  * A self-contained, dependency-free stand-in for the my.tracking202.com messaging
  * API so you can click through the Prosper202 messenger widget locally. It
- * implements the contract in 202-config/Messaging/CENTRAL-API.md:
+ * implements the central messaging API contract:
  *   POST /messaging/pull
  *   POST /messaging/send
  *   POST /messaging/read
diff --git a/202-config/connect.php b/202-config/connect.php
index 8e3b53bd..e97a0ceb 100644
--- a/202-config/connect.php
+++ b/202-config/connect.php
@@ -80,7 +80,7 @@ function withWritableSession(callable $callback): void
 DEFINE('TRACKING202_ADS_URL', 'https://ads.tracking202.com');
 
 // Messaging API configuration (Intercom-style messenger).
-// Central server contract: 202-config/Messaging/CENTRAL-API.md
+// Central server contract: exercised by 202-config/Messaging/mock-server.php (see MOCK-SERVER.md).
 // Both values are overridable via environment variables so a developer can point
 // the app at the local mock server (202-config/Messaging/mock-server.php) without
 // editing tracked config, e.g. MESSAGING_API_URL=http://127.0.0.1:8787/messaging