cdp-edge 2.3.7 → 2.3.9

package/README.md

@@ -1,620 +1,274 @@
-# 🚀 CDP Edge — Quantum Tracking Enterprise
-
-**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
-
-> **v2.3.7** — Infraestrutura Git & Contratos de API (14 de Abril de 2026) 🛠️
-
-> **v2.3.6** — Retry Queue Completo & Hardening TypeScript (14 de Abril de 2026) 🔁
-
-> **v2.3.5** — UTMs Obfuscadas & Segmentação de Valor (14 de Abril de 2026) 🏷️
-
-### Novidades
-- graphify obrigatório em todas as sessões (CLAUDE.md)
-- Git hooks instalados (post-commit, post-checkout)
-- Hook corrigido para UTF-8 nativo no Windows
-- Redução de custo documentada (40–90% economia ao navegar grafo)
-- Tripé de documentação sincronizado (README + CLAUDE.md + Business Book)
-
-### Correções
-- Hook post-commit corrigido para encoding UTF-8
-- Rebuild code-only funcional após cada commit
-- Push para ts/main (CDP-Edge-Premium.ts.git) concluído
-
----
-
-## 📋 CHANGELOG v2.3.7 — Infraestrutura Git & Contratos de API (14 de Abril de 2026)
-
-### 🛠️ Infraestrutura Git
-
-- **`.gitattributes`** criado — força LF em todos os arquivos de texto, elimina o falso "M" por conversão CRLF no Windows de forma permanente para qualquer clone futuro
-- **`core.autocrlf=false`** — desativado localmente para que `.gitattributes` tenha controle total dos line endings
-- **`.gitignore`** — `server-edge-tracker/dist-check/` adicionado (output do `wrangler deploy --dry-run` não deve ser versionado)
-
-### 📋 Contratos de API
-
-- **`contracts/api-versions.json`** — versão `1.0.0` → `1.1.0`
-  - `updated_at` atualizado para `2026-04-14`
-  - `last_updated_by` reflete `Intelligence Agent — CDP Edge v2.3.6`
-  - `next_review_date` atualizado para `2026-05-14`
-
-### Breaking Changes
-
-- Nenhuma.
-
----
-
-## 📋 CHANGELOG v2.3.6 — Retry Queue Completo & Hardening TypeScript (14 de Abril de 2026)
-
-### 🔁 Retry Queue — Cobertura Total de Dispatchers
-
-**Problema resolvido:** a infraestrutura de retry (`RETRY_QUEUE` + consumer + DLQ) estava 100% montada no `wrangler.toml` e no `index.ts`, mas `RETRY_QUEUE.send()` nunca era chamado. Eventos perdidos por falha de rede ficavam mortos no D1.
-
-**Solução implementada:**
-- `RETRY_QUEUE.send()` ativo nos 7 dispatchers: Meta, GA4, TikTok, Pinterest, Reddit, LinkedIn, Spotify
-- Apenas falhas de rede (`catch`) são enfileiradas — erros HTTP 4xx não são retentados (payload rejeitado pela plataforma)
-- Consumer (`queue()`) recebe `ctx: ExecutionContext` — background ops (`logMatchQuality`, `writeAuditLog`) agora funcionam no reprocessamento
-- Cobertura expandida de 3 para 7 plataformas no consumer
-- `Queue<QueueMessage>` adicionado ao `Env` em `types.ts`
-
-**Fluxo de retry:**
-```
-Dispatcher → catch (falha de rede)
-  → logApiFailure (D1)
-  → RETRY_QUEUE.send({ eventType, payload, platform })
-      → consumer reprocessa (até 3 tentativas)
-      → se esgotar → DLQ (cdp-edge-dlq)
-```
-
-### 🔧 Hardening TypeScript
-
-- Tipo explícito `SanitizeResult` para o objeto de sanitização em `index.ts`
-- `STR_FIELDS` renomeado para `TRACKING_ID_FIELDS` (transactionId, fbclid, ttclid, gclid) — elimina conflito com `GENERIC_SANITIZE_FIELDS` (UTMs)
-- Build TypeScript: zero erros, zero warnings críticos
-
-### Breaking Changes
-
-- Nenhuma. API HTTP e comportamento em runtime são idênticos.
-
-### Migração
-
-Nenhuma migração necessária. Se a fila `cdp-edge-retry` ainda não foi criada:
-```bash
-wrangler queues create cdp-edge-retry
-wrangler queues create cdp-edge-dlq
-wrangler deploy
-```
-
----
-
-## 📋 CHANGELOG v2.3.5 — UTMs Obfuscadas & Segmentação de Valor (14 de Abril de 2026)
-
-### 🏷️ UTM Agent — Novo Agente para Segmentação de Público
-
-**Problema resolvido:**
-- Múltiplos anúncios com diferentes faixas de valor (ex: imóveis 500k-800k, 800k-1.5M, 1M-3M) precisam ser segmentados corretamente para o Meta criar públicos separados
-- Dados sensíveis (valor de preço) não devem estar visíveis na URL pública por segurança
-
-**Solução implementada:**
-- **UTMs Obfuscadas:** Valores de faixa são convertidos em hash SHA256 truncado (8 caracteres)
-  - `800k-1.5M` → `b4e2a1c9` (obfuscado)
-  - Humans veem: `imovel_b4e2a1c9`
-  - Worker sabe: `faixa_real = "800k-1.5M"` (de-obfuscado)
-
-- **Módulo UTM Enricher:** `server-edge-tracker/modules/utm/utm-enricher.ts`
-  - `obfuscateValue()` — gera hash truncado de 8 caracteres
-  - `deobfuscateValue()` — de-obfusca usando mapeamento
-  - `enrichPayloadWithUTM()` — enriquece payload com segmentação
-  - Integração com Meta CAPI: `external_id` segmentado por hash
-
-- **Schema D1:** `server-edge-tracker/schema-utm.sql`
-  - Tabela `utm_mappings` — persiste mapeamento hash→valor
-  - Colunas em `leads`: `faixa_obfuscada`, `faixa_real`, `faixa_category`
-  - VIEW `leads_segmented` — para dashboard e exports
-
-- **Master Orchestrator Atualizado:** UTM Agent integrado ao fluxo (FASE 2-B)
-  - Ordem: Page Analyzer → **UTM Agent** → Premium Intelligence → Browser Tracking
-  - Arquivo: `extracted-skill/tracking-events-generator/agents/utm-agent.md`
-
-**Fluxo de criação de projeto:**
-```
-USUÁRIO INICIA CDP EDGE
-    ↓
-FASE 1: Seleção de plataformas + credenciais
-    ↓
-FASE 2: Page Analyzer (identifica tipo de página)
-    ↓
-FASE 2-B: UTM Agent ← NOVO
-    → Pergunta: "Qual a faixa de valor deste imóvel?"
-    → Gera: URL obfuscada + mapeamento hash→valor
-    ↓
-FASE 3+: Continua fluxo normal (Premium Intelligence, Browser Tracking, etc.)
-```
-
-**Segmentação na Meta:**
-```
-Públicos criados automaticamente via external_id segmentado:
-- Público LOW:  cdp_uid_8a3f1d2b  (500k-800k)
-- Público MID:  cdp_uid_b4e2a1c9  (800k-1.5M)
-- Público HIGH: cdp_uid_d6c3b4e7   (1M-3M)
-```
-
-**Remarketing futuro:**
-```sql
--- Exportar público por faixa para Meta Custom Audience
-SELECT email, phone, city, state
-FROM leads_segmented
-WHERE faixa_real = '800k-1.5M'
-  AND created_at >= datetime('now', '-30 days');
-```
-
-### Correções
-
-- Documentação sincronizada: README.md + CLAUDE.md + Business Book
-- Versões alinhadas: package.json, CHANGELOG, README
-- Referências cruzadas: agents, modules, schemas
-
-### Breaking Changes
-
-- Nenhuma. API HTTP e comportamento em runtime são idênticos.
-
-### Migração
-
-Para projetos existentes:
-```bash
-# Aplicar schema UTM (adicional)
-cd server-edge-tracker
-wrangler d1 execute cdp-edge-db --file=schema-utm.sql --remote
-
-# Configurar utm-mapping.json (manual ou via UTM Agent)
-cp config/utm-mapping.json.example config/utm-mapping.json
-
-# Deploy
-wrangler deploy
-```
-
----
-
-> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações, correções ou novas features devem OBRIGATORIAMENTE ser documentadas de forma sincronizada neste `README.md`, no arquivo de instruções `CLAUDE.md` e no dossiê de diretoria `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
-
----
-
-## 🤖 MANIFESTO: EU, CDP EDGE
-
-*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
-
-**A Linha de Montagem Sincronizada (A Prova de Latência)**
-Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint `/track`:
-1. **O Escudo Frontal (Fraud Gate):** Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
-2. **A Roleta Invisível (A/B LTV):** Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
-3. **O Cérebro Financeiro (LTV Predictor):** Rodo Machine Learning (Granite 4.0 Micro) para qualificar a intenção e gerar o LTV Preditivo.
-4. **Envio para as Plataformas:** O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
-5. **Máquina Autônoma (Background):** Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (`ctx.waitUntil`).
-
-**Minha Vantagem Absoluta (A "Killer Feature")**
-- **A Extinção da Latência:** Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
-- **Cookies Indestrutíveis:** Meus *First-Party Cookies Seguros* originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
-- **Filas Inquebráveis (Fail-Safe + Queues):** Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em *Cloudflare Queues* e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).
-
----
-
-## 📋 CHANGELOG v2.3.1 — Hardening Enterprise (12 de Abril de 2026)
-
-### 🔒 Segurança & Conformidade
-
-- **PII removido dos logs:** `DeviceGraph` parou de logar `user_id` nos Workers logs — dados sensíveis nunca aparecem no Cloudflare dashboard
-- **Deploy seguro:** novo `deploy-client.js` — lê credenciais de `.client.env` (gitignored), gera `wrangler.deploy.toml` temporário, faz deploy e autodestrói o arquivo. Credenciais de cliente nunca entram no repo
-- **`.gitignore` reforçado:** `.client.env` e `wrangler.deploy.toml` explicitamente ignorados
-- **WhatsApp secrets alinhados à Meta Cloud API v22.0:** `resolvePhoneNumberId()` e `resolveAccessToken()` com fallback canônico → legado — backwards compat garantido
-- **`api-versions.json` v1.1.0:** metadata `updated_at` corrigido para `2026-04-12`
-- **`/health` WhatsApp:** reflete corretamente secrets com nomes canônicos ou legados
-
-### 🔧 Deploy de Cliente — Novo Fluxo
-
-```bash
-cd server-edge-tracker
-cp .client.env.example .client.env
-# preencher DATABASE_ID, SITE_DOMAIN, pixels
-node deploy-client.js --dry-run   # valida sem subir
-node deploy-client.js             # deploy real
-```
-
----
-
-## 📋 CHANGELOG v2.3.0 — TypeScript Nativo (12 de Abril de 2026)
-
-### 🔷 Worker 100% TypeScript — Migração Completa
-
-Todo o código server-side (`server-edge-tracker/`) foi migrado de JavaScript para **TypeScript nativo**. O Wrangler compila diretamente o `.ts` via esbuild — sem etapa de build separada, sem configuração extra.
-
-**Por que TypeScript muda o jogo no CDP Edge:**
-- **Env tipado** — typos em nomes de secrets (`META_ACCESS_TOKEN`, `GEO_CACHE`, `DB`) viram erros em build time, nunca em produção
-- **TrackPayload contratado** — o shape do payload entre browser e Worker é garantido pelo compilador
-- **Cloudflare types nativos** — D1, KV, R2, Workers AI com autocomplete e validação de métodos
-- **Fraud Gate e ML seguros** — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` — nenhum `undefined` passa despercebido
-- **Refatoração segura** — renomear qualquer campo do `TrackPayload` lista automaticamente todos os pontos de quebra
-
-**Arquivos migrados (JS → TS) — 16 módulos:**
-- `index.ts` — entry point do Worker
-- `types.ts` — **novo** — contratos centralizados: `Env`, `TrackPayload`, `BehavioralData`, `HotmartWebhook`, `KiwifyWebhook`, `TictoWebhook`, `QueueMessage`, `PromiseResult<T>`
-- `modules/utils.ts`, `modules/db.ts`, `modules/intelligence.ts`
-- `modules/dispatch/` — `meta.ts`, `ga4.ts`, `tiktok.ts`, `platforms.ts`, `whatsapp.ts`
-- `modules/ml/` — `ltv.ts`, `fraud.ts`, `bidding.ts`, `segmentation.ts`, `logistic.ts`, `matchquality.ts`
-
-**Infraestrutura:**
-- `tsconfig.json` — `target: ESNext`, `moduleResolution: "bundler"`, `strict: true`, `@cloudflare/workers-types`
-- `wrangler.toml` — `main = "index.ts"` (TypeScript nativo via wrangler/esbuild)
-- `contracts/types.ts` — tipos públicos exportados no pacote NPM: `QuantumEventPayload`, `AgencyContext`, `ApiVersionsConfig`
-- `npm run typecheck` — `tsc --noEmit` (225 testes passando, zero erros de compilação)
-
-**Breaking change:** nenhuma — API HTTP e comportamento em runtime são idênticos. TypeScript é invisível para o Cloudflare.
-
----
-
-## 📋 CHANGELOG v2.2.5 (11 de Abril de 2026)
-
-### 🔧 Correção de Versão Dinâmica
-
-- **Versão Dinâmica**: `bin/cdp-edge.js` e `dist/commands/install.js` agora leem a versão do `package.json` dinamicamente
-- **Banner Corrigido**: O banner de instalação agora mostra sempre a versão correta (`cdp-edge --version`)
-- **Compatibilidade**: Garante que a versão exibida no CLI e banner esteja sempre sincronizada com o `package.json`
-
----
-
-## 📋 CHANGELOG v2.2.0 (10 de Abril de 2026)
-
-### 🤖 AI Engine Upgrade — Novos Modelos
-
-- **LTV Prediction**: `@cf/meta/llama-3.1-8b-instruct` → **`@cf/ibm-granite/granite-4.0-h-micro`** (menor latência, otimizado para edge e function calling)
-- **ML Clustering**: algoritmo LLM simulado → **K-means vetorial real** com embeddings `@cf/baai/bge-m3` (distância cosseno, K-means++ inicialização, silhouette score real)
-- Granite continua sendo usado para naming dos segmentos pós-clustering
-
-### 🧹 Limpeza (Zero Lixo)
-
-- Removido: detecção de emails descartáveis (mailinator, guerrilla, tempmail, etc.) do Fraud Gate e do agente `fraud-detection-agent.md`
-- Removido: secrets `WEBHOOK_SECRET_HOTMART` e `WEBHOOK_SECRET_KIWIFY` (wrangler + wrangler.toml)
-
-### 🔧 Observability
-
-- Adicionado bloco `[observability]` no `wrangler.toml` (`logs.enabled = true`, `traces.enabled = false`)
-
----
-
-## 📋 CHANGELOG v2.0.7 (10 de Abril de 2026)
-
-### 🔧 Audit Completo — 45 Agentes
-
-- **Endpoints corrigidos**: `/api/tracking` → `/track`, `/api/wh/` → `/webhook/` em todos os agentes
-- **Secrets WhatsApp**: `WA_PHONE_ID`/`WA_ACCESS_TOKEN`/`WHATSAPP_TOKEN` → `WHATSAPP_PHONE_NUMBER_ID`/`WHATSAPP_ACCESS_TOKEN`
-- **`env.DB.prepare`**: corrigido em 8 agentes (attribution, crm, dashboard, debug, performance, security, master-feedback-loop)
-- **`env.GEO_CACHE`**: substituiu `KV.` bare em dashboard-agent, performance-agent, performance-optimization-agent
-- **YouTube events**: `video_milestone`/`video_progress_25/50/75` → `video_25`/`video_50`/`video_75` (alinhado ao VALID_EVENT_NAMES do worker)
-- **LinkedIn CAPI**: endpoint `/rest/conversionEvents` + header `LinkedIn-Version: 202401` em `contracts/api-versions.json`
-- **Workers AI model**: `llama-3-8b-instruct` → `@cf/meta/llama-3.1-8b-instruct`
-- **index.ts**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
-- **Testes**: bugs críticos em `deduplication.test.js` corrigidos (template literals escapados, prefixo errado)
-- **npm**: lodash 4.17.23 → 4.18.1, node-fetch removido
-
----
-
-## 📋 CHANGELOG v2.0.0 (9 de Abril de 2026)
-
-### 🆕 Sprint Enterprise — Fases 1 a 4
-
-#### ✅ Fase 1 — ML Clustering (Segmentação Dinâmica)
-- **`POST /api/segmentation/cluster`** — K-means / DBSCAN / Hierarchical via Workers AI
-- **`GET  /api/segmentation/list`** — Segmentos ativos com métricas
-- **`GET  /api/segmentation/outliers`** — Detecção de outliers comportamentais
-- **`PUT  /api/segmentation/update`** — Atualização de metadados de segmento
-- Schema D1: `ml_segments`, `ml_segment_members` + VIEWs otimizadas
-- Agente: `ml-clustering-agent.md`
-
-#### ✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)
-- **`POST /api/bidding/recommend`** — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula `LTV × ROI target / CPA base`
-- **`GET  /api/bidding/history`** — Histórico completo de recomendações
-- **`GET  /api/bidding/status`** — Snapshot atual das recomendações ativas por vertical
-- Schema D1: `bid_recommendations` + VIEW `v_active_bid_recommendations`
-- Agente: `bidding-agent.md`
-
-#### ✅ Fase 3 — A/B Testing de Prompts LTV
-- **`POST /api/ltv/ab-test/create`** — Cria experimento com múltiplas variações de system prompt
-- **`GET  /api/ltv/ab-test/list`** — Lista experimentos com status e progresso
-- **`GET  /api/ltv/ab-test/results`** — Accuracy score por variação + recomendação automática de winner
-- **`POST /api/ltv/ab-test/winner`** — Declara vencedor e retorna o prompt ganador
-- Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
-- Schema D1: `ltv_ab_tests`, `ltv_ab_variations`, `ltv_ab_assignments` + VIEW `v_ab_test_performance`
-- Agente: `ab-ltv-agent.md`
-
-#### ✅ Fase 4 — Fraud Detection Engine
-- **Fraud Gate automático em `/track`** — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
-- Silent drop (retorna 200 falso) — bots não detectam a defesa
-- **`GET  /api/fraud/stats`** — Dashboard de fraude (últimas 24h)
-- **`GET  /api/fraud/alerts`** — Log de sinais detectados com filtros
-- **`GET  /api/fraud/blocklist`** — IPs/fingerprints atualmente bloqueados
-- **`POST /api/fraud/blocklist/add`** — Bloquear IP ou fingerprint (via KV, efeito imediato)
-- **`DELETE /api/fraud/blocklist/remove`** — Remover do blocklist
-- Sinais detectados: bot_score, datacenter IP, velocity attack, headless UA, sem Accept-Language
-- Schema D1: `fraud_signals`, `fraud_alerts` + VIEW `v_fraud_dashboard`
-- Agente: `fraud-detection-agent.md`
-
-### 🔧 Fix: `wrangler.toml` atualizado
-- Todos os placeholders (`SEU_D1_DATABASE_ID`, `SEU_KV_NAMESPACE_ID`) substituídos pelos IDs reais da conta Cloudflare
-- D1: `SEU_DATABASE_ID`
-- KV: `SEU_KV_ID`
-
----
-
-## 🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)
-
-```mermaid
-graph TD
-    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
-    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
-    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
-    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
-    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
-    Worker -->|LTV + A/B Prompt| AI[Workers AI Granite 4.0 Micro]
-    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
-    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
-    Worker -->|Background| Queue[Cloudflare Queues]
-    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
-    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
-    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
-    D1 -->|Reports| Dash[Dashboard Agent]
-```
-
----
-
-## 🧠 CATÁLOGO DE AGENTES ESPECIALISTAS
-
-O sistema é composto por **43+ agentes** coordenados pelo **Master Orchestrator**:
-
-### 🧠 Núcleo de Inteligência
-| Agente | Função |
-|---|---|
-| **Master Orchestrator** | Coordenação central — guia todo o setup do projeto |
-| **Page Analyzer** | Mapeamento automático de CTAs, Forms e nicho do site |
-| **Validator Agent** | Auditoria de código, segurança e conformidade de APIs |
-| **Memory Agent** | Contexto e checkpoints da sessão por projeto |
-| **Intelligence Agent** | Monitoramento de versões de API (Meta v22.0+, etc) |
-
-### 🚀 Plataformas de Anúncio
-| Agente | Especialidade |
-|---|---|
-| **Meta Agent** | Facebook Pixel + CAPI v22.0 + WhatsApp CTWA |
-| **Google Agent** | GA4 + Google Ads Enhanced Conversions |
-| **TikTok Agent** | TikTok Pixel + Events API v1.3 |
-| **LinkedIn Agent** | Insight Tag + Conversions API v2 |
-| **Pinterest Agent** | Tag + Conversions API v5 |
-| **Reddit Agent** | Pixel + Conversions API v2.0 |
-| **Spotify Agent** | Pixel + Conversions API v1 |
-| **Bing Agent** | UET Tag + Enhanced Conversions |
-
-### 🤖 Enterprise Intelligence (Fase 1–4)
-| Agente | Endpoint Principal | Impacto |
-|---|---|---|
-| **ML Clustering Agent** | `POST /api/segmentation/cluster` | K-means vetorial real (bge-m3 embeddings + Granite naming) |
-| **Bidding Agent** | `POST /api/bidding/recommend` | -20% CPA via bid por segmento de LTV |
-| **A/B LTV Agent** | `POST /api/ltv/ab-test/create` | +25% precisão LTV via test de prompts |
-| **Fraud Detection Agent** | Auto em `/track` | Bloqueia click fraud, bots, velocity attacks |
-
-### 🛡️ Módulos Enterprise
-| Agente | Função |
-|---|---|
-| **Attribution Agent** | Atribuição Multi-Touch de alta fidelidade |
-| **Security Agent** | Rate Limiting, AES-256 e Bot Defense |
-| **Compliance Agent** | LGPD e GDPR (Consent Mode v2) |
-| **Performance Agent** | Otimização de caches e queries D1 |
-
----
-
-## 📊 BANCO DE DADOS D1 — 21 Tabelas
-
-```
-CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
-─────────────────        ─────────────────────    ─────────────────────
-leads                   ml_segments               fraud_signals
-events                  ml_segment_members        fraud_alerts
-sessions                bid_recommendations       ltv_ab_tests
-webhook_events          ltv_ab_tests              ltv_ab_variations
-api_failures            ltv_ab_variations         ltv_ab_assignments
-
-VIEWS
-─────────────────────────────────────────────────
-v_active_segments          → Segmentos ML ativos com contagem de membros
-v_active_bid_recs          → Bids ativos por plataforma/vertical
-v_ab_test_performance      → Accuracy por variação de prompt
-v_fraud_dashboard          → Dashboard fraude 24h
-```
-
----
-
-## 🔄 FLUXO ENTERPRISE COMPLETO
-
-```
-POST /track (evento Lead)
-  │
-  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
-  │         ├─ score < 40  → processa normalmente
-  │         ├─ score 40-79 → processa + loga suspeito (background)
-  │         └─ score ≥ 80  → silent drop 200 + loga (background)
-  │
-  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
-  │         └─ passa customSystemPrompt para predictLtv()
-  │
-  ├─ [3] 🧮 LTV Prediction — Workers AI Granite 4.0 Micro
-  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
-  │
-  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
-  │         ├─ upsertLtvProfile() → tabela leads
-  │         ├─ recordAbAssignment() → ltv_ab_assignments
-  │         └─ resolveDeviceGraph() → cross-device linking
-  │
-  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
-            └─ com LTV injetado no value field
-```
-
----
-
-## 💻 INSTALAÇÃO E USO
-
-### OPÇÃO 1 — Instalação via npm (Recomendada)
-
-Abra o terminal dentro da pasta do projeto do cliente e rode:
-
-```bash
-npx cdp-edge install
-```
-
-Ou instale globalmente e use em qualquer projeto:
-
-```bash
-npm install -g cdp-edge
-cdp-edge install . --name "Nome do Projeto"
-```
-
-> **Já tem o CDP Edge instalado globalmente?** Atualize para a versão mais recente:
-> ```bash
-> npm install -g cdp-edge@latest
-> ```
-
-### OPÇÃO 2 — Instalação via Git Clone
-
-```bash
-git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .
-```
-*(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).*
-
-### Ativar no Claude Code
-
-```bash
-claude .
-```
-Dentro do Claude Code:
-```
-/cdp
-```
-
----
-
-## 🚀 DEPLOY COMPLETO (referência)
-
-```bash
-cd server-edge-tracker
-
-# 1. Schemas D1 (todos em sequência)
-wrangler d1 execute cdp-edge-db --file=schema.sql --remote
-wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
-wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote  # Fase 1
-wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
-wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
-wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4
-
-# 2. Secrets
-wrangler secret put META_ACCESS_TOKEN
-wrangler secret put GA4_API_SECRET
-wrangler secret put TIKTOK_ACCESS_TOKEN
-
-# 3. Deploy
-wrangler deploy
-```
-
----
-
-## 🗺️ NAVEGANDO O CÓDIGO COM GRAPHIFY
-
-O **graphify** gera um mapa de conhecimento navegável do projeto (nós, arestas, comunidades). Antes de qualquer trabalho de código:
-
-```bash
-# 1. Verifique se o grafo existe
-ls graphify-out/GRAPH_REPORT.md
-
-# 2. Se não existe ou está desatualizado, gere:
-/graphify .
-
-# 3. Navegue o grafo para entender arquitetura
-/graphify query "como funciona o fraud gate?"
-/graphify query "identity graph → ltv prediction"
-/graphify path "cdp_uid" "cloudflare d1"
-```
-
-### O que o grafo fornece
-
-- **God Nodes**: abstrações centrais (D1, Meta CAPI v22.0, Intelligence Agent, ML Clustering)
-- **65 comunidades**: grupos lógicos (Multi-Platform Agent Layer, ML Bidding, Browser SDK, etc.)
-- **Surprising Connections**: relações inferidas entre conceitos que você não sabia que eram similares
-- **Redução de custo**: navegar grafo = até 40% menos tokens vs. ler arquivos brutos
-
-### Exemplo de uso
-
-**❌ Não faça:**
-> "Ler 50 arquivos para entender como o fraud gate conecta com o LTV predictor"
-
-**✅ Faça:**
-> `/graphify query "fraud gate → ltv predictor"` — resposta instantânea com caminho completo, arquivos fonte e nível de confiança
-
-O grafo fica atualizado automaticamente após cada `git commit` (via hook).
-
----
-
-## 🖱️ HUMAN-BEHAVIOR ENGINE
-
-| Evento | Pontuação |
-|--------|-----------|
-| Scroll 25–90% | +5 a +15 pts |
-| VSL Watch 25–100% | +10 a +50 pts |
-| Copy Intent (cupom, PIX) | +20 pts |
-| Preenchimento de campo | +10 pts |
-| Rage Click | -10 pts |
-| **Hot Lead (80+ pts)** | **Dispara High_Intent_Lead** |
-
----
-
-## 📋 TODOS OS ENDPOINTS (referência rápida)
-
-### Core Tracking
-| Rota | Método | Função |
-|---|---|---|
-| `/track` | POST | Evento principal (browser → CAPI) |
-| `/health` | GET | Smoke test completo |
-| `/webhook/ticto` | POST | Webhook Ticto Purchase |
-
-### Intelligence ML
-| Rota | Método | Função |
-|---|---|---|
-| `/api/segmentation/cluster` | POST | Clustering K-means/DBSCAN |
-| `/api/segmentation/list` | GET | Segmentos ativos |
-| `/api/segmentation/outliers` | GET | Outliers comportamentais |
-| `/api/bidding/recommend` | POST | Bid otimizado por segmento |
-| `/api/bidding/history` | GET | Histórico de bids |
-| `/api/bidding/status` | GET | Status por plataforma |
-
-### A/B Testing LTV
-| Rota | Método | Função |
-|---|---|---|
-| `/api/ltv/ab-test/create` | POST | Criar experimento |
-| `/api/ltv/ab-test/list` | GET | Listar experimentos |
-| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
-| `/api/ltv/ab-test/winner` | POST | Declarar vencedor |
-
-### Fraud Detection
-| Rota | Método | Função |
-|---|---|---|
-| `/api/fraud/stats` | GET | Dashboard 24h |
-| `/api/fraud/alerts` | GET | Log de alertas |
-| `/api/fraud/blocklist` | GET | Lista bloqueada |
-| `/api/fraud/blocklist/add` | POST | Bloquear IP/fingerprint |
-| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
-
----
-
-## 📞 SUPORTE
-
-- **Issues**: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
-- **Releases**: https://github.com/ricardosoli777/CDP-Edge-Premium/releases
-
----
-
-### **CDP Edge — By Rica Soares**
-> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
-
-© 2026 CDP Edge Premium. Todos os direitos reservados.
+# 🚀 CDP Edge — Quantum Tracking Enterprise
+
+**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
+
+> **v2.5.0** — Sales Engine: ROAS Feedback + Nurture Engine + Lookalike Dinâmico (14 de Abril de 2026) 💰
+> **v2.4.0** — Quiz Scoring Engine: Qualificação AI de Respondentes (14 de Abril de 2026) 🤖
+> **v2.3.8** — Fix Definitivo: api-versions.json (14 de Abril de 2026) 🔒
+
+---
+
+## 📋 CHANGELOG v2.5.0 — Sales Engine (14 de Abril de 2026) 💰
+
+### O que foi adicionado
+
+**ROAS Feedback Loop** (`modules/ml/roas.ts`)
+- Cruza leads com compras reais por campanha no D1
+- Calcula: `conversion_rate`, `revenue_per_lead`, `ltv_accuracy` (valida o modelo preditivo)
+- Recomendação automática de bid: `increase | maintain | decrease | pause`
+- Relatório semanal via CallMeBot com top campanhas e alertas
+- Persiste histórico em `roas_reports` + VIEW `v_roas_latest`
+
+**Nurture Engine** (`modules/nurture.ts`)
+- Sequências automáticas pós-quiz por qualificação:
+  - `interessado` → D+1, D+3, D+7 (WhatsApp)
+  - `curioso` → D+2, D+5 (conteúdo)
+  - `comprador` → contato imediato via hot lead (já existente)
+  - `perdido` → `cohort_label = excluded` (remove do remarketing)
+- `scheduleNurture()` chamado no QuizComplete em background
+- `runNurtureQueue()` executado pelo Intelligence Agent (cron diário)
+- D1: `nurture_sequences` + VIEWs de fila e stats
+
+**Lookalike Dinâmico** (`syncMetaLookalikeSeed()` em intelligence.ts)
+- Seed de Lookalike com compradores CONFIRMADOS (Purchase event) — não apenas high_intent
+- Une compradores reais + leads qualificados como `comprador` no quiz
+- Atualiza `cohort_label = buyer_confirmed` nos perfis
+- Persiste histórico em `lookalike_seeds`
+- Roda automaticamente no cron semanal do Intelligence Agent
+
+**Schema D1**: `schema-sales-engine.sql` — `roas_reports`, `nurture_sequences`, `lookalike_seeds` + 5 VIEWs
+
+### Migração
+```bash
+cd server-edge-tracker
+wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote
+wrangler deploy
+```
+
+---
+
+## 📋 CHANGELOG v2.4.0 — Quiz Scoring Engine (14 de Abril de 2026) 🤖
+
+**Quiz Scoring Engine** (`modules/ml/quiz.ts`) — análise dimensional automática via Granite 4.0 Micro:
+- Detecta o TIPO de cada pergunta: `urgency | budget | timeline | fit | engagement | awareness | objection`
+- Atribui peso automático por dimensão (budget/urgency=5, fit=4, timeline=3, engagement=2)
+- Score ponderado → `comprador | interessado | curioso | perdido`
+- Fallback heurístico por palavras-chave quando AI indisponível
+- `quiz_sessions` no D1 com breakdown completo por dimensão
+
+**Integração no pipeline `/track`**:
+- `QuizComplete` + `quiz_answers[]` → scoring antes do LTV
+- `intentionLevel` qualificado alimenta LTV Prediction → `comprador` = LTV High automático
+- `QuizComplete` adicionado ao `LTV_EVENTS`
+
+**Migração**: `wrangler d1 execute cdp-edge-db --file=schema-quiz.sql --remote`
+
+---
+
+## 📋 CHANGELOG v2.3.8 — Fix Definitivo: api-versions.json (14 de Abril de 2026) 🔒
+
+`build.js` copia `extracted-skill/.../contracts/` → `contracts/` no `prepare` script. A fonte estava na v1.0.0, sobrescrevendo o arquivo correto a cada `npm publish`. Ambos os arquivos agora sincronizados em v1.1.0.
+
+---
+
+> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações devem ser documentadas de forma sincronizada em `README.md`, `CLAUDE.md` e `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
+
+---
+
+## 🤖 MANIFESTO: EU, CDP EDGE
+
+*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
+
+Quando um evento de Lead bate no endpoint `/track`:
+1. **Fraud Gate:** Bloqueio bots silenciosamente antes de qualquer processamento (~2ms via KV)
+2. **Quiz Scoring Engine:** Classifico as respostas do quiz com Granite 4.0 Micro — `comprador | interessado | curioso | perdido`
+3. **A/B LTV Testing:** Sorteio de prompt via KV Cache em ~0ms
+4. **LTV Predictor:** Machine Learning para qualificar intenção e gerar valor preditivo em BRL
+5. **Nurture Scheduler:** Agendar sequência de follow-up baseada na qualificação (background)
+6. **CAPI Dispatch:** Meta/GA4/TikTok recebem payload limpo com LTV e intention injetados
+7. **Sales Engine:** Semanalmente, calculo ROAS real por campanha e atualizo o seed de Lookalike com compradores confirmados
+
+---
+
+## 🏗️ ARQUITETURA QUANTUM ENTERPRISE
+
+```
+POST /track (QuizComplete)
+  │
+  ├─ [1] 🛡️  Fraud Gate (KV blocklist + velocity) ~2ms
+  ├─ [2] 🤖  Quiz Scoring Engine (Granite 4.0 Micro) → comprador/interessado/curioso/perdido
+  ├─ [3] 🔮  A/B LTV Sorting (KV cache ~0ms)
+  ├─ [4] 🧮  LTV Prediction (Granite 4.0 Micro) — intent qualificado → High LTV
+  ├─ [5] 💾  D1 Writes background (quiz_sessions + leads + nurture_sequences)
+  └─ [6] 📡  CAPI paralelo (Meta v22.0 + GA4 + TikTok v1.3)
+
+Cron semanal (Intelligence Agent):
+  ├─ ROAS Feedback — cruza leads × purchases por campanha → bid recommendation
+  ├─ Nurture Queue — envia D+1/D+3/D+7 para leads qualificados
+  ├─ Lookalike Seed — compradores confirmados → Meta Custom Audience
+  ├─ LTV Model Training — regressão logística com dados reais
+  └─ A/B LTV Auto-winner — declara vencedor quando amostra suficiente
+```
+
+---
+
+## 📊 BANCO DE DADOS D1 — 25 Tabelas + 12 VIEWs
+
+```
+CORE TRACKING          ML & INTELLIGENCE         SALES ENGINE
+──────────────         ─────────────────────     ──────────────────
+leads                  ml_segments               roas_reports
+events                 ml_segment_members        nurture_sequences
+sessions               bid_recommendations       lookalike_seeds
+webhook_events         ltv_ab_tests              quiz_sessions
+api_failures           ltv_ab_variations
+device_graph           ltv_ab_assignments
+user_profiles          fraud_signals
+intelligence_logs      fraud_alerts
+messaging_history      match_quality_logs
+automation_rules       utm_mappings
+edge_fingerprints
+
+VIEWS (12)
+──────────────────────────────────────────────────────────────────
+v_active_segments           v_active_bid_recs
+v_ab_test_performance       v_fraud_dashboard
+v_quiz_qualification_summary v_quiz_dimension_impact
+v_roas_latest               v_nurture_pending
+v_nurture_stats             v_quiz_session_summary
+v_leads_segmented           v_ltv_feedback
+```
+
+---
+
+## 🧠 CATÁLOGO DE MÓDULOS ML
+
+| Módulo | Arquivo | Função |
+|---|---|---|
+| **Quiz Scoring** | `modules/ml/quiz.ts` | Análise dimensional automática das respostas |
+| **LTV Prediction** | `modules/ml/ltv.ts` | Score 0-100 + valor BRL via Granite + A/B test |
+| **Fraud Gate** | `modules/ml/fraud.ts` | Detecção de bots e fraude na borda |
+| **ML Clustering** | `modules/ml/segmentation.ts` | K-means vetorial com bge-m3 embeddings |
+| **Bidding ML** | `modules/ml/bidding.ts` | Recomendação de bid por segmento × plataforma |
+| **ROAS Feedback** | `modules/ml/roas.ts` | ROAS real por campanha, alimenta bidding |
+| **Match Quality** | `modules/ml/matchquality.ts` | Score de qualidade de dados para CAPI |
+| **Logistic** | `modules/ml/logistic.ts` | Regressão logística para LTV model treinável |
+| **Nurture Engine** | `modules/nurture.ts` | Sequências automáticas pós-qualificação |
+
+---
+
+## 🧠 CATÁLOGO DE AGENTES
+
+| Categoria | Agente | Função |
+|---|---|---|
+| Orquestração | `master-orchestrator.md` | Coordena todo o setup |
+| Análise | `page-analyzer.md` | Detecta CTAs, forms e nicho |
+| Plataformas | `meta-agent.md`, `google-agent.md`, `tiktok-agent.md`... | Especialistas por plataforma |
+| Infra | `server-tracking.md`, `devops-agent.md` | Arquitetura Cloudflare |
+| Enterprise | `ml-clustering-agent.md` | Segmentação dinâmica ML |
+| Enterprise | `bidding-agent.md` | Bids ML por segmento |
+| Enterprise | `ab-ltv-agent.md` | A/B testing de prompts LTV |
+| Enterprise | `fraud-detection-agent.md` | Detecção de fraude na borda |
+| Monitoramento | `intelligence-agent.md` | Cron — ROAS, Nurture, Lookalike, LTV training |
+
+---
+
+## 📋 TODOS OS ENDPOINTS
+
+### Core
+| Rota | Método | Função |
+|---|---|---|
+| `/track` | POST | Evento principal — Fraud Gate → Quiz Scoring → LTV → CAPI |
+| `/health` | GET | Smoke test D1 + KV + AI |
+| `/webhook/ticto` | POST | Purchase webhook (HMAC) |
+| `/export/customer-match` | GET | Export leads para Google Ads |
+
+### ML Clustering (Fase 1)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/segmentation/cluster` | POST | K-means vetorial (bge-m3 + Granite) |
+| `/api/segmentation/list` | GET | Segmentos ativos |
+| `/api/segmentation/outliers` | GET | Outliers comportamentais |
+| `/api/segmentation/update` | PUT | Atualiza metadados |
+
+### Bidding (Fase 2)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/bidding/recommend` | POST | Bid por segmento × plataforma |
+| `/api/bidding/history` | GET | Histórico de recomendações |
+| `/api/bidding/status` | GET | Snapshot atual |
+
+### A/B LTV (Fase 3)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/ltv/ab-test/create` | POST | Cria experimento |
+| `/api/ltv/ab-test/list` | GET | Lista experimentos |
+| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
+| `/api/ltv/ab-test/winner` | POST | Declara vencedor |
+
+### Fraud (Fase 4)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/fraud/stats` | GET | Dashboard 24h |
+| `/api/fraud/alerts` | GET | Log de sinais |
+| `/api/fraud/blocklist` | GET | IPs bloqueados |
+| `/api/fraud/blocklist/add` | POST | Bloquear |
+| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
+
+---
+
+## 🚀 DEPLOY COMPLETO
+
+```bash
+cd server-edge-tracker
+
+# Schemas D1 (ordem correta — todos idempotentes)
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-utm.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-quiz.sql --remote        # Fase 6
+wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote # Fase 7
+
+# Secrets
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+wrangler secret put TIKTOK_ACCESS_TOKEN
+
+# Deploy
+wrangler deploy
+```
+
+---
+
+## 💻 INSTALAÇÃO
+
+```bash
+npx cdp-edge install
+# ou
+npm install -g cdp-edge
+cdp-edge install . --name "Nome do Projeto"
+```
+
+---
+
+## 🗺️ GRAPHIFY — Navegando o Código
+
+```bash
+/graphify .                                          # gera o mapa
+/graphify query "como funciona o quiz scoring?"      # exploração BFS
+/graphify query "nurture engine → meta audience"     # exploração DFS
+/graphify path "quiz_answers" "meta capi"            # menor caminho
+```
+
+---
+
+### **CDP Edge — By Rica Soares**
+> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
+
+© 2026 CDP Edge Premium. Todos os direitos reservados.