Ir para o conteúdo

Decision Engine — Motor de Decisão

Seleção de ofertas (onde investir primeiro, com P(lucro), Keyword Planner e regras bayesianas ao vivo em SHADOW): ver Motor de Seleção de Ofertas.

O Motor de Decisão Brandvelia transforma dados de marketing em decisões de investimento através de um pipeline determinístico e auditável:

evidência imutável → capital verdadeiro → cenários aprovados
        → recomendação SHADOW → decisão humana → fase operacional

Princípios inegociáveis:

  • SQL calcula, IA explica, humanos aprovam. Nenhuma métrica financeira é calculada por LLM e nenhuma recomendação executa algo sozinha.
  • Desconhecido ≠ zero. Qualquer input ausente produz null + motivo, nunca um zero silencioso.
  • Imutabilidade. Evidência, snapshots de capital, cenários submetidos, recomendações, decisões humanas e histórico de fases são append-only.

Status da implementação (Fases 0–4)

Fase Escopo Status
0 Verdade factual: fundação canônica (15 tabelas, forced RLS), backfill legado idempotente, ClickBank INS v2 atômico, QuickStats com cobertura completa, hardening de PII legado, pilot Meta read-only persistido via RPCs service-only ✅
1 Evidence envelopes + engine de capital S0/Cp/L/Ca + scenario sets LOW/BASE/HIGH com lifecycle e maker-checker ✅
2 Recomendações SHADOW determinísticas (recommendation/v1), decisões humanas imutáveis, máquina de fases de campanha ✅
3 Alertas determinísticos replay-safe + validador de claims IA por allowlist de evidência ✅
4 Opportunity Score v2 (opportunity/v2) em SHADOW, somente cohorts maduras ✅

Modo de entrega atual: SHADOW em todo o workspace (OFF → SHADOW; ADVISORY só existe como gate futuro).

Capital verdadeiro (S0 / Cp / L / Ca)

Fórmula única, materializada em snapshot imutável (capital_calculation_snapshots, fórmula capital/v1):

Variável Definição
S0 Soma dos saldos available do último snapshot por conta, com reconciliação MATCHED, data_status VALID, moeda base e janela de frescor ≤ 30h. Pending/held/accrued, contas em moeda estrangeira e saldos não verificados ficam fora.
Cp Soma do outstanding_amount de compromissos autorizados na moeda base. Conjunto vazio = zero conhecido.
L Soma dos 5 componentes da última versão APPROVED da política de reservas vigente na moeda base. Um componente desconhecido torna L desconhecido.
Ca max(0, S0 − Cp − L). Se S0 ou L for desconhecido ⇒ Ca = null + motivo, nunca zero.

Cada snapshot carrega input_hash canônico estável entre fusos, replay idempotente e um envelope DERIVED_METRIC de evidência. Saldos manuais (Registro em Finance → Saldo de Capital) derivam seus hashes no servidor e geram evidência SOURCE_FACT.

Bridges públicas (service/admin conforme a operação): bv_materialize_capital_snapshot, bv_get_capital_snapshot.

Cenários LOW / BASE / HIGH (preflight/v1)

Um scenario_set versionado contém exatamente três variantes; cada input é:

  • evidenciado (SOURCE_FACT envelope do workspace), ou
  • premissa com racional + expiração futura — nunca ambos.

Inputs: EXPECTED_CPC, VISIT_TO_SALE_RATE, PAYOUT_PER_SALE, REFUND_CGBK_RATE, PLANNED_TEST_CLICKS. A economia derivada é sempre recalculada em SQL:

revenue_per_click   = VISIT_TO_SALE_RATE × PAYOUT_PER_SALE × (1 − REFUND)
break_even_cpc      = revenue_per_click
break_even_rate     = CPC / (PAYOUT × (1 − REFUND))
requested_invest    = PLANNED_TEST_CLICKS × CPC

Lifecycle: DRAFT → IN_REVIEW → APPROVED → SUPERSEDED (+ REJECTED/ARCHIVED). Submeter congela o input_hash canônico. Maker-checker: com dois ou mais admins, o autor não pode aprovar o próprio set; auto-aprovação solo é permitida e marcada AUDITED_SELF_APPROVAL. Aprovar uma versão nova supersede a APPROVED anterior da mesma chave.

Recomendações SHADOW e decisão humana

evaluate_recommendation(cenário aprovado × capital READY) produz TEST / HOLD / BLOCK (VALIDATE/SCALE são tiers reservados para quando houver histórico próprio maduro):

Condição Recomendação
Capital desconhecido / premissa expirada BLOCK
Margem de segurança ≤ 0 HOLD (NO_POSITIVE_MARGIN)
Margem < 10% HOLD (THIN_SAFETY_MARGIN)
Margem ≥ 10% TEST com investimento efetivo min(I, Ca)

A recomendação é imutável, replay-stable e nunca executa nada. Movimentar a fase de uma campanha para TEST/VALIDATE/SCALE exige uma decisão humana ACCEPT vinculada àquela recomendação exata. Fases seguem um grafo fixo (PREFLIGHT → TEST → VALIDATE → SCALE → HOLD/BLOCKED/CLOSED) com histórico append-only.

Evidência, alertas e IA

  • Evidence envelopes: identidade opaca, hash de conteúdo derivado em SQL, supersession tenant-safe. Toda afirmação factual de IA deve citar apenas evidence IDs existentes no workspace — bv_validate_ai_claims rejeita FACT_WITHOUT_EVIDENCE, UNKNOWN_OR_FOREIGN_EVIDENCE e shapes inválidos.
  • Alertas determinísticos (replay-safe por chave): capital bloqueado, atribuição UNKNOWN etc., exibidos no Radar.
  • Opportunity Score v2 (shadow): pesos fixos 50% cobertura de conversão + 50% economia líquida normalizada (saturação USD 1.000), calculado somente sobre cohorts cuja janela de refund fechou.

Contratos e ADRs

Referências normativas completas (em inglês):