Contextual Flux
Architecture v2.1

1. Introdução

O Contextual Flux Architecture (CFA) é uma arquitetura para sistemas orientados por IA que substitui o paradigma tradicional de Agents + Tools/Skills estáticas por um modelo baseado em resolução de intenção como entidade arquitetural de primeira ordem.

O CFA trata a execução não como um ato imediato, mas como uma decisão fundamentada — condicionada por intenção compreendida, políticas de governança, restrições de custo (FinOps), contratos de dados e estado atual do ambiente.

Definição Formal de Intenção

O termo intenção é usado com precisão técnica no CFA, não como sinônimo de instrução ou comando:

O fluxo fundamental do CFA é:

2. Problema que o CFA Resolve

Arquiteturas tradicionais de agentes com tools estáticas apresentam quatro limitações estruturais que o CFA foi desenhado para resolver:

3. Princípios Fundamentais

4. Arquitetura Geral

5.1 Intent Normalizer + Semantic Resolution

O Intent Normalizer é o componente mais crítico do pipeline. Uma assinatura incorreta gerada aqui contamina todos os componentes downstream — o Policy Engine governará o problema errado, o Planner construirá a DAG errada, e o código gerado será determinísticamente incorreto sem qualquer alucinação aparente.

Input do Componente

O Normalizer obrigatoriamente consulta o Context Registry antes de gerar a assinatura. Este é um input arquitetural, não opcional:

intent_normalizer:
  inputs:
    - user_intent                           # linguagem natural
    - context_registry.environment_state   # estado atual do ambiente
    - data_catalog                          # metadados e classificações
  outputs:
    - semantic_resolution

Semantic Resolution

semantic_resolution:
  signature: {...}                       # State Signature gerada
  confidence_score: 0.82                # [0.0 - 1.0]
  ambiguity_level: medium              # low | medium | high
  competing_interpretations:
    - join_nfe_clientes_silver
    - enrich_nfe_with_master_data
  confirmation_mode: hard_required     # auto | soft | hard_required
  environment_constraints_injected:    # constraints do Context Registry
    - silver_documentos.state = partially_committed
    - silver_documentos.publish_allowed = false

Modos de Confirmação

Integração com Context Registry

Se o Context Registry indica silver_documentos.state = partially_committed, o Normalizer deve: ajustar a interpretação da intenção, injetar a constraint no plano, ou bloquear intenções que dependam de publicação do dataset afetado. Sem essa consulta, o sistema propõe planos sobre premissas inválidas do estado do mundo.

5.1.1 Resiliência e Adaptabilidade do Intent Normalizer

Fallback Strategies e Degradação Graciosa

O Intent Normalizer opera sob a premissa de acesso ao Context Registry para resolução de ambiguidades semânticas e validação de restrições ambientais. Contudo, em cenários de indisponibilidade transitória do registry, o sistema adota uma política de degradação em camadas:

normalizer_fallback_policy:
  primary: context_registry_query  # Tentativa padrão
  secondary: 
    - local_cache_lookup          # Cache LRU de intenções recentes (TTL: 15min)
    - conservative_heuristics     # Regras determinísticas de baixo risco
  tertiary: 
    - request_human_confirmation  # Elevação para confirmação explícita
    - queue_for_retry             # Enfileiramento com backoff exponencial

• Modo Conservativo: Quando operando sem acesso ao registry, o normalizer eleva automaticamente o confidence_threshold para 0.95 e exige confirmação explícita para qualquer intenção que envolva:
  • Escrita em datasets marcados como critical: true
  • Transformações com side_effects não idempotentes
  • Restrições de custo acima do percentil 90 histórico

Confidence Calibration Dinâmica

O sistema mantém um Calibration Tracker por domínio de intenção, registrando:

@dataclass
class CalibrationMetrics:
    intent_domain: str
    total_confirmations: int
    auto_approved_count: int
    human_overrides: int  # Casos onde humano corrigiu decisão automática
    false_positive_rate: float  # Aprovações automáticas posteriormente invalidadas
    last_recalibration: datetime

A cada N execuções (configurável, padrão: 100), o sistema recalibra os thresholds:

Esta abordagem permite que o sistema aprenda com correções humanas sem exigir retreinamento de modelos, mantendo adaptabilidade operacional.

5.1b Confirmation Orchestrator

O Intent Normalizer é o single point of failure mais perigoso do sistema — uma assinatura errada contamina todo o pipeline com perfeição determinística. O Confirmation Orchestrator é a mitigação estrutural: interpõe uma camada de escalonamento entre a resolução semântica e a Policy Engine, ativada seletivamente por risco.

Ele não adiciona atrito em 90% dos casos. Nos 10% onde o risco é real — PII, ambiguidade, escrita em camadas críticas — ele é obrigatório.

confirmation_orchestrator:
  modes:
    - auto              # confiança alta, risco baixo — avança sem interrupção
    - soft              # apresenta assinatura, avança sem conflito
    - hard              # confirmação explícita obrigatória
    - human_escalation  # escalonamento para revisão humana

  escalation_triggers:
    - confidence_score < 0.65 AND contains_pii == true
    - competing_interpretations > 1
    - silver_write AND context_registry.publish_allowed == false
    - gold_write                                  # sempre escalonado
    - estimated_cost > cost_ceiling_dbu * 0.8    # pré-custo acima de 80% do teto

  human_timeout_seconds: 300
  fallback_on_timeout:
    action: block
    reason: human_confirmation_timeout
    notify: governance_team
    audit_event: HUMAN_ESCALATION_TIMEOUT

5.2 State Signature

Representação tipada e enriquecida da intenção. É o contrato formal que governa todo o restante do pipeline. Uma vez gerada e confirmada, a Signature é imutável — qualquer replanejamento gera uma nova Signature.

signature:
  domain: fiscal_data_processing
  intent: reconciliation_and_persist
  source_type: nested_json
  target_layer: bronze_to_silver
  datasets:
    - name: nfe
      size: 4TB
      classification: high_volume
    - name: clientes
      size: 500MB
      classification: sensitive
      pii: [cpf, email]
  constraints:
    no_pii_raw: true
    partition_by: [processing_date]
    enforce_types: true
    merge_key_required: true
  execution_context:                        # contexto normativo da execução
    policy_bundle_version: "v4.2"          # políticas vigentes no momento
    catalog_snapshot_version: "catalog_2026_03_22"  # estado do catálogo

Por que execution_context pertence à Signature

O execution_context não é metadado de auditoria — é parte do contrato de execução. Com ele na Signature, o sistema consegue reproduzir qualquer execução histórica com as políticas e o catálogo que vigoravam naquele momento, não apenas explicar o que aconteceu. Sem isso, o Audit Trail registra o passado mas não o torna reproducível. Os três elementos — intenção formalizada, estado do ambiente, contexto normativo — formam o contrato completo de uma execução.

5.3 Policy Engine

Aplica todas as regras de governança, segurança e FinOps antes da execução. É a camada que garante que o sistema nunca executa o que não deveria.

Resultado possível do Policy Engine: approve, replan (com intervenções obrigatórias declaradas), ou block.

Contrato Declarativo de Regras

Regras do Policy Engine são expressas de forma declarativa — condição + ação — e versionadas junto ao policy_bundle_version. O whitepaper não especifica a DSL de implementação, mas define o contrato mínimo que qualquer regra deve satisfazer:

policy_rule:
  name: forbid_raw_pii_in_silver
  condition: target_layer == "silver" AND contains_pii_raw == true
  action: block                       # approve | replan | block
  severity: critical
  fault_code: GOVERNANCE_RAW_PII_IN_SILVER

Limite de Replanejamento

O ciclo de replanejamento não pode ser ilimitado. Um loop de replans é tão problemático em produção quanto uma execução travada — e não tem estado terminal sem este limite declarado:

replan_policy:
  max_attempts: 3
  on_max_exceeded:
    action: block
    decision_state: blocked
    reason: max_replan_attempts_exceeded
    audit_required: true

5.4 Composite Intent Model

Intenções compostas são decompostas em subintenções com dependências explícitas. No modelo conceitual isso é representado como Intent Graph; na implementação, essa capacidade pode ser absorvida internamente pelo Execution Planner.

intent_graph:
  root_intent: fiscal_reconciliation_publish
  sub_intents:
    - id: ingest_nfe
    - id: anonymize_client_master
    - id: reconcile_documents
    - id: aggregate_by_state
    - id: publish_audit_view
  dependencies:
    - ingest_nfe -> reconcile_documents
    - anonymize_client_master -> reconcile_documents
    - reconcile_documents -> aggregate_by_state
    - aggregate_by_state -> publish_audit_view
  shared_context:
    consistency_unit: partition
    key: processing_date

5.5 Execution Planner

Gera a DAG de execução a partir da Signature aprovada. O Planner não é livre — ele preenche templates, segue o plano aprovado pela Policy Engine e respeita todas as constraints declaradas na Signature.

execution_plan:
  - step: extract
    source: nfe
    filter: processing_date >= '2026-01-01'     # obrigatório por FinOps

  - step: anonymize
    source: clientes
    transform:
      - sha256(cpf) as cpf_hash
      - drop(email)

  - step: join
    type: broadcast
    condition: nfe.cpf = clientes.cpf_hash

  - step: load
    type: merge
    target: silver_documentos
    key: nfe_id                              # obrigatório por Contrato

Pre-cost Estimator

O FinOps Guard bloqueia custo excessivo após o Policy Engine avaliar a Signature. O Pre-cost Estimator antecipa essa avaliação — estima o custo antes da Signature ser aprovada, usando histórico de execuções com o mesmo intent_signature_hash. Isso fecha o gap entre "custo estimado" e "custo real" com feedback loop automático.

pre_cost_estimator:
  inputs:
    - signature
    - context_registry.environment_state
    - execution_history_by_signature_hash   # últimos 30 dias

  outputs:
    estimated_dbu: float
    estimated_shuffle_gb: float
    cost_risk_score: float               # [0.0 - 1.0]
    confidence: float                    # baseado em N execuções históricas

  threshold_policy:
    - if estimated_dbu > cost_ceiling_dbu:
        action: force_replan_with_filter
        reason: PRE_COST_CEILING_EXCEEDED
    - if estimated_dbu > cost_ceiling_dbu * 0.8:
        action: escalate_to_confirmation_orchestrator
        mode: human_escalation

  feedback_loop:
    update_on: post_execution
    key: intent_signature_hash
    window: last_30_days
    model: rolling_weighted_average

Toda execução gerada pelo Planner deve ser idempotente. Em retry ou re-execução após falha parcial, o sistema não pode duplicar dados, criar registros duplicados ou produzir resultado diferente do que produziria na primeira execução bem-sucedida.

execution_semantics:
  idempotency:
    required: true
    strategy:
      - merge_with_deterministic_key   # merge usa merge_key da Signature
      - partition_overwrite_safe        # overwrite de partição inteira é idempotente
    forbidden:
      - append_without_dedup            # append puro gera duplicatas em retry

Consistency Unit — Enum Fechado

O tipo de consistency_unit não é livre — é selecionado por regra baseada no contexto da execução:

consistency_unit:
  allowed_types:
    - partition          # padrão para batch particionado
    - dataset            # para operações atômicas cross-dataset
    - dag_branch         # para composite intents com ramos independentes
    - time_window        # para micro-batch com janela temporal

  selection_rules:
    - if execution_mode == batch:           partition
    - if cross_dataset_atomic == true:      dataset
    - if composite_intent == true:         dag_branch
    - if execution_mode == micro_batch:    time_window

5.5.1 Modelo de Estimativa de Custo: Cold Start e Decaimento Temporal

Estratégia para Cold Start

Para intenções sem histórico prévio (intent_signature_hash não encontrado), o estimador adota uma abordagem hierárquica de fallback:

1. Domain-Level Priors: Utiliza estatísticas agregadas do domínio semântico mais próximo (ex: "join de tabelas fiscais" herda parâmetros de outras intenções do domínio fiscal).
2. Structural Similarity: Calcula similaridade estrutural do DAG de operações com intenções existentes via embedding de grafos; usa a média ponderada das k mais similares.
3. Conservative Upper Bound: Na ausência total de similaridade, aplica limites superiores conservadores baseados em:
   • Volume máximo de dados declarados no execution_context
   • Complexidade teórica das operações (ex: join ≫ filter)
   • Políticas de custo por ambiente (dev, staging, prod)

Política de Decaimento Temporal (Time-Weighted Moving Average)

O estimador utiliza uma média móvel ponderada exponencialmente (EWMA) para priorizar execuções recentes:

• Racional: Execuções recentes refletem melhor o estado atual da infraestrutura (otimizações, mudanças de schema, upgrades de cluster).
• Configuração por Ambiente:
  YAMLcost_estimator.decay_config

  cost_estimator:
    decay_rate:
      prod: 0.005   # Mudanças mais lentas, maior peso histórico
      staging: 0.02 # Mudanças frequentes, foco no recente
      dev: 0.05    # Experimentação, máximo peso no imediato

• Reset Condicional: O histórico é parcialmente resetado (weight *= 0.1) quando detectadas mudanças estruturais no ambiente (ex: alteração de schema, upgrade de versão do Spark).

5.6 Static Validation

Análise do código gerado antes da execução. Detecta violações que podem ser identificadas sem rodar o job. Pertence à família Static Safety Faults.

static_analysis:
  forbidden_tokens:
    - collect()
    - toPandas()
    - crossJoin()
    - cpf                   # PII raw
    - email                 # PII raw
  required_patterns:
    - filter(               # predicado temporal obrigatório
    - merge(                # append direto proibido em Silver
  schema_contract:
    expected_columns: [nfe_id, cpf_hash, processing_date]
    forbidden_columns: [cpf, email]

5.7 Runtime Validation

Valida o comportamento real da execução no Sandbox. Detecta violações que só são visíveis com dados reais. Pertence à família Runtime Behavioral Faults.

runtime_metrics:
  max_rows_output: 10_000_000
  max_shuffle_size_mb: 500
  max_null_ratio: 0.05             # 5%
  expected_output_range:
    min: 1_000
    max: 10_000_000
  schema_drift_detection: true
  cost_ceiling_dbu: 50

5.8 Partial Execution State

Em sistemas de dados reais, a falha total e limpa é rara. O caso comum é falha parcial: 80% das partições processadas, um ramo da DAG materializado, três de quatro datasets conformes. O CFA tem semântica explícita para isso.

Unidade de Consistência

O sistema precisa declarar qual é a granularidade mínima de governança. Sem isso, "parcial" é palavra vaga.

partial_execution_state:
  overall_state: partially_committed

  consistency_unit:
    type: partition             # partition | dataset | dag_branch | time_window
    key: processing_date

  successful_units:
    - dataset: nfe
      partitions: ["2026-01-01", "2026-01-02"]
    - dataset: clientes_anon
      partitions: ["2026-01-01", "2026-01-02"]

  failed_units:
    - dataset: nfe
      partitions: ["2026-01-03"]
      error_code: RUNTIME_SHUFFLE_LIMIT_EXCEEDED
      fault_family: runtime_behavioral

  consistency_policy:
    mode: selective_quarantine
    rollback_required: false
    publish_allowed: false

Partial Failure Policy

A sequência interna do Partial Execution State é determinística e não pode ser reordenada:

partial_execution_flow:
  sequence:
    - retry_failed_units          # tenta recuperar unidades falhadas antes de qualquer decisão
    - apply_partial_failure_policy # determina modo (rollback / quarantine / commit / degraded)
    - project_state               # projeta no Context Registry apenas após policy aplicada

partial_failure_policy:
  mode: selective_quarantine
  allowed_partial_commit: true
  publish_on_partial_success: false
  rollback_scope: failed_consistency_unit_only
  promotion_eligible: false

Retry Policy

Falhas de unidades de consistência individuais são elegíveis a retry automático dentro da mesma execução. O retry opera sobre as failed_units, não sobre a execução inteira — preservando o que já foi comprometido com sucesso.

retry_policy:
  enabled: true
  max_attempts: 3
  retry_scope: failed_consistency_units_only   # nunca re-executa unidades bem-sucedidas
  backoff:
    strategy: exponential
    base_seconds: 30
  on_max_exceeded:
    action: quarantine_failed_units
    state: quarantined

Publish Semantics

O flag publish_allowed tem semântica precisa. "Publicar" não é sinônimo de "escrever" — é tornar o dataset disponível para consumo downstream como dado confiável.

publish_semantics:
  definition: dataset_visible_and_trusted_for_downstream_consumption

  states:
    - committed_not_published   # dado gravado, não disponível downstream
    - published                 # dado disponível e confiável
    - degraded                  # disponível com restrições declaradas (degraded_publish)

  write_vs_publish:
    write: dado gravado no storage
    publish: dado declarado confiável para consumo
    distinction: possível ter write sem publish — nunca publish sem write

Panic Rollback — Mudança de Ambiente Durante Execução

O Partial Execution State trata falha da execução. Existe um caso distinto: mudança do ambiente externo durante a execução — cluster que perde nós, permissão IAM revogada, storage quota excedida. Esses eventos não são erros de execução — são invalidações do contexto em que a execução foi autorizada. Precisam de protocolo próprio.

panic_rollback:
  triggers:
    - external_permission_revoked      # IAM, ACL, credencial expirada em runtime
    - compute_resource_unavailable     # cluster perda de nós além do threshold
    - storage_quota_exceeded           # storage indisponível no meio da escrita
    - policy_bundle_changed_mid_exec   # política alterada enquanto job rodava

  action: immediate_interrupt_and_isolate
  scope: all_in_flight_consistency_units

  post_panic:
    state: quarantined
    projection_allowed: false          # Context Registry não é atualizado
    audit_event: PANIC_ROLLBACK_TRIGGERED
    reason_required: true

  distinction_from_partial_execution_state:
    "Partial Execution State: execução falhou por razão interna"
    "Panic Rollback: ambiente externo invalidou as premissas da execução"

5.8.1 Protocolo de Recuperação Pós-Panic Rollback

Critérios de Retomada Automática

Após um Panic Rollback, o sistema não retoma execuções automaticamente. A decisão de retry segue uma matriz de decisão baseada em:

Mecanismo de Notificação e Retry

O sistema integra-se ao canal de comunicação configurado (webhook, Slack, email) para notificações estruturadas:

{
  "event": "panic_rollback_resolved",
  "intent_id": "abc123",
  "rollback_reason": "schema_drift_detected",
  "resolution": {
    "detected_at": "2026-04-20T14:30:00Z",
    "resolved_at": "2026-04-20T15:45:00Z",
    "resolution_type": "manual_schema_sync",
    "state_integrity": "verified"
  },
  "next_steps": {
    "auto_retry_eligible": true,
    "retry_window": "2026-04-20T16:00:00Z",
    "manual_approval_url": "https://cfa.internal/approve/abc123"
  }
}

• Retry com Janela de Observação: Quando elegível para auto-retry, o sistema aguarda uma janela de observação (retry_window, padrão: 15min) para garantir estabilidade ambiental antes de reexecutar.
• Idempotência Garantida: O intent_id original é preservado, e o Audit Trail registra explicitamente o ciclo rollback → resolution → retry, mantendo rastreabilidade completa.

5.9 Context Registry

O Context Registry é a infraestrutura cognitiva do sistema. Não é um log de execuções — é um modelo vivo do estado do ambiente. Representa não apenas "o que foi feito" mas "em que estado está o que foi feito".

É consultado pelo Intent Normalizer antes de cada nova intenção, e atualizado pelo State Projection Protocol após cada execução.

context_registry:
  environment_state:
    datasets:
      - name: silver_documentos
        state: partially_committed
        last_successful_partition: "2026-01-02"
        pending_partitions: ["2026-01-03"]
        publish_allowed: false
        quarantined_units: ["2026-01-03"]

      - name: clientes_anon
        state: committed
        publish_allowed: true

  execution_history:
    - intent_id: fiscal_reconciliation_001
      outcome: partially_committed
      consistency_unit: partition
      timestamp: "2026-03-22T14:30:00Z"
      policy_bundle_version: "v4.2"

Versionamento do Registro

O Context Registry precisa de versionamento explícito. Sem ele, não existe consistência temporal — e a reprodutibilidade que o execution_context garante na Signature torna-se ilusória se o estado do ambiente no momento da execução não for recuperável.

context_registry:
  versioning:
    model: snapshot
    version_id: uuid                 # gerado a cada write atômico
    timestamp: iso8601

  read_mode:
    type: snapshot_consistent        # leitura sempre de snapshot estável

  write_mode:
    type: atomic_commit              # escrita atômica via State Projection

Pre-execution Revalidation (TOCTOU)

Existe uma janela entre a consulta ao Context Registry pelo Intent Normalizer (etapa 2) e a execução real (etapa 9). Durante esse intervalo, outra execução pode projetar novo estado sobre o mesmo dataset. Sem revalidação, o sistema executa sobre premissa stale — violando o Invariante 3 de forma silenciosa.

pre_execution_revalidation:
  trigger: immediately_before_execution   # após lock adquirido, antes do Sandbox
  checks:
    - context_registry.version_id          # snapshot consultado ainda é o latest_committed?
    - policy_bundle_version                 # policy não mudou desde a Signature?
    - catalog_snapshot_version              # catálogo não mudou desde a Signature?
  on_mismatch:
    action: replan_or_abort
    reason: stale_environment_state
    counts_as_replan_attempt: true         # conta no max_replan_attempts do Policy Engine

TTL e Política de Estado Obsoleto

O Context Registry pode acumular estado obsoleto indefinidamente. Um dataset marcado como partially_committed há semanas, sem nova execução sobre ele, continua bloqueando publicação sem nunca ser resolvido — envenenando silenciosamente as intenções futuras. É necessária uma política explícita de expiração e transição de estados antigos.

ttl_policy:
  partially_committed:
    ttl_days: 7                          # após 7 dias sem resolução
    on_expiry:
      action: transition_to_stale
      notify: true                       # gera evento no Audit Trail

  quarantined:
    ttl_days: 30                         # quarentena longa — requer revisão manual
    on_expiry:
      action: escalate_to_manual_review
      block_dependent_intents: true

  stale:
    definition: estado não atualizado além do TTL sem resolução declarada
    behavior:
      new_intent_on_stale_dataset: hard_confirmation_required
      publish_blocked: true
      audit_event: CONTEXT_STATE_STALE

5.10 State Projection Protocol

A ponte entre execução e contexto. Garante que o resultado de cada execução se torne conhecimento do sistema antes que qualquer nova intenção seja processada.

state_projection:
  trigger: post_runtime_validation      # ocorre após validação, antes da próxima intenção

  inputs:
    - partial_execution_state
    - execution_metadata

  scope:
    - dataset_state
    - partition_availability
    - publish_allowed
    - quarantined_units
    - pending_partitions

  rules:
    - if overall_state == "partially_committed":
        dataset.state = "partially_committed"
        publish_allowed = false
    - if failed_units exist:
        dataset.pending_units = failed_units
    - if policy.mode == "selective_quarantine":
        dataset.quarantined_units = failed_units

  atomicity: required

  on_projection_failure:
    action: block_next_intent
    reason: environment_state_uncertain

Propriedades Obrigatórias

5.11 Índices de Avaliação

Três índices distintos capturam dimensões diferentes da qualidade de uma execução. Cada um é independente e mensurável.

Critério de Promoção

IDI — Intent Drift Index

Quarto sinal de lifecycle, complementar aos três índices de execução. O IDI detecta quando o domínio mudou e a skill ficou "podre" — antes que o IFs detecte a degradação no resultado. Ele mede com que frequência execuções do mesmo hash precisam ser replanejadas:

Evaluation Window Configurável

A janela de avaliação de promoção não é fixa — domínios de alta volatilidade (fiscal, regulatório) precisam de janelas menores. Domínios estáveis (dados mestres, cadastro) podem usar janelas mais longas:

evaluation_window:
  default: last_7_days
  by_domain:
    fiscal: last_3_days           # alta volatilidade regulatória
    master_data: last_30_days    # domínio estável
    operational: last_7_days     # padrão

5.12 Skill Lifecycle Management

Um sistema que só promove skills cria, com o tempo, um novo cemitério de artefatos. Sem ciclo de demoção, o CFA reproduz o problema do catálogo estático com pedigree arquitetural.

Estados

A transição persisted_active → demoted pode ocorrer diretamente, bypassing watchlist, em caso de violação crítica de contrato ou governança.

Critério de Promoção

Promoção exige evidência acumulada em janela temporal — uma única execução bem-sucedida não é suficiente para industrialização:

promotion_policy:
  min_executions: 3                     # mínimo de execuções bem-sucedidas
  evaluation_window: last_7_days        # dentro desta janela
  thresholds:
    IFo: 0.75
    IFs: 0.90
    IFg: 1.0                             # binário — sem exceção
  gate: IFo >= T1 AND IFs >= T2 AND IFg = 1 AND executions >= min_executions
  promotion_unit:
    type: intent_signature_hash          # hash da State Signature — evita promover "parecidos"
    # duas intenções com signatures diferentes = skills diferentes, mesmo que semanticamente próximas

Skill Generation Metadata

Toda skill promovida deve carregar metadado de proveniência. Sem isso, não é possível identificar quais skills foram industrializadas sob uma versão do sistema com bug de promoção — tornando o "Legado Sintético" irrastreável e irrecuperável em escala.

skill_generation_metadata:
  promoted_at: iso8601
  promoted_by_system_version: "cfa_v2.1"    # versão do CFA que executou a promoção
  policy_bundle_at_promotion: "v4.2"        # policy vigente no momento
  catalog_snapshot_at_promotion: "catalog_2026_03_22"
  promotion_scores:
    IFo: 0.88
    IFs: 0.94
    IFg: 1.0
  execution_count_at_promotion: 5
  evaluation_window: last_7_days

5.13 Fault Model

Erros no CFA não são exceções — são eventos governados. Cada família tem um momento de detecção e um responsável definido. Misturar famílias sem explicitar o estágio cria ambiguidade sobre quem detecta, quando detecta e qual estado terminal é possível.

Estrutura de um Fault Event

error_signature:
  code: FINOPS_UNBOUNDED_SCAN
  family: semantic_faults
  severity: high
  stage: policy_engine
  detected_before_execution: true
  mandatory_action: replan_or_block
  remediation:
    - "Aplicar filtro temporal em processing_date"

5.14 Decision Engine

Consolida o resultado de todas as validações e produz o estado final da intenção. Quando componentes divergem — Policy Engine aprovou, Runtime detecta drift, Partial Policy permite commit — o Decision Engine aplica a regra de precedência para determinar quem tem autoridade.

Decision Precedence

Invariantes e componentes têm naturezas distintas na decisão. Invariantes não são participantes — são a borda do campo. Se um invariante é violado, o resultado é determinado antes de qualquer outra avaliação.

decision_precedence:
  veto_absolute:
    - invariants              # violação cancela tudo, sem votação possível
                               # não são "mais um participante" — são o limite do campo
  ordered_authority:
    - policy_engine           # 1º: decide pré-execução (approve / replan / block)
    - runtime_validation      # 2º: decide sobre resultado real (pode escalar severity)
    - partial_failure_policy  # 3º: decide sobre granularidade do commit

Resolução de Conflito entre Autoridades

Quando policy_engine, runtime_validation e partial_failure_policy produzem outcomes divergentes, a estratégia de resolução é strictest_outcome — o resultado mais restritivo entre as autoridades ativas prevalece:

decision_engine:
  conflict_resolution:
    strategy: strictest_outcome
    # se policy_engine = approved e runtime = quarantine → quarantine
    # se policy_engine = replanned e partial = partially_committed → replanned
    # severity ordering: blocked > quarantined > rolled_back > partially_committed
    #                   > approved_with_warnings > approved

Estados Possíveis

decision_state:
  - approved                  # execução completa, validada, publicável
  - approved_with_warnings    # execução completa, alertas não-bloqueantes
  - replanned                 # Policy Engine exigiu alterações, novo ciclo
  - blocked                   # violação irrecuperável pré-execução
  - partially_committed       # resultado parcial, Partial Failure Policy aplicada
  - quarantined              # unidades isoladas, investigação necessária
  - rolled_back              # estado revertido por falha crítica
  - promotion_candidate       # IFo+IFs+IFg acima dos thresholds

5.15 Audit Trail

Registro imutável de todos os eventos de decisão. Não é logging convencional — são eventos tipados, correlacionados por intent_id e versionados por policy_bundle. Serve dois consumidores com necessidades distintas e incompatíveis se não endereçadas explicitamente.

audit_trail:
  intent_id: fiscal_reconciliation_001
  correlation_id: session_4f9a2c
  policy_bundle_version: v4.2

  events:
    - stage: intent_normalizer
      event_type: semantic_resolution
      outcome: resolved
      confidence: 0.81
      confirmation_mode: hard_required
      environment_state_consulted: true

    - stage: policy_engine
      event_type: policy_replan
      outcome: replanned
      faults: [GOVERNANCE_RAW_PII_JOIN, FINOPS_MISSING_TEMPORAL_PREDICATE]

    - stage: static_validation
      event_type: code_analysis
      outcome: passed

    - stage: execution
      event_type: partial_commit
      outcome: partially_committed
      consistency_unit: partition
      successful: ["2026-01-01", "2026-01-02"]
      failed: ["2026-01-03"]

    - stage: state_projection
      event_type: environment_update
      outcome: projected

    - stage: promotion_engine
      event_type: promotion_evaluation
      outcome: not_eligible
      reason: partial_execution

Modos de Consumo

Propriedades do Registro

Imutável após gravação. Ordenado causalmente por intent_id — não apenas cronologicamente. Correlacionado entre subintenções. Versionado pelo policy_bundle ativo no momento da execução — permite replay histórico com política original.

audit_trail:
  immutability: append_only              # eventos só são adicionados, nunca modificados ou removidos
  ordering: causal_order              # não apenas timestamp — ordem causal de eventos
  guarantees:
    - no_event_reordering             # evento A que causou B sempre aparece antes de B
    - immutable_after_write
    - complete_per_intent             # todo intent_id tem início e fim registrados

  decision_state_enum:               # estados são enumerados — sem estados ad-hoc
    - approved
    - approved_with_warnings
    - replanned
    - blocked
    - partially_committed
    - quarantined
    - rolled_back
    - promotion_candidate

5.16 Caracterização de Overhead e Estratégias de Otimização

Quantificação de Latência por Estágio

O pipeline de governança introduz latência adicional mensurável. Em benchmarks realizados em ambiente t3.xlarge com datasets de 10GB–100GB, observou-se:

Estratégias de Early Exit para Intenções de Baixo Risco

Além do modo auto (baseado em histórico), o sistema suporta bypass condicional para intenções que atendam simultaneamente:

def is_low_risk_intent(signature: StateSignature) -> bool:
    return (
        signature.constraints.no_pii_raw is True and
        signature.execution_context.environment == "dev" and
        signature.estimated_cost < cost_thresholds["dev"]["low"] and
        signature.operations.all(lambda op: op.is_read_only) and
        audit_trail.get_success_rate(signature.intent_domain) > 0.99
    )

Quando is_low_risk_intent retorna True:

• Policy Engine: Executa apenas regras críticas (severity=CRITICAL), pulando validações de otimização.
• Static Validation: Pula análises de complexidade ciclomática, mantendo apenas verificações de segurança.
• Audit: Registra o bypass com tag fast_path: true para monitoramento posterior.

6. Invariantes do Sistema

Invariantes são as propriedades que o sistema sempre deve preservar. Diferem de benefícios — não descrevem o que o sistema faz bem, mas o que ele garante. Violação de invariante é falha do sistema, não do usuário.

Precedência entre Invariantes

Sem esta regra de precedência declarada, um implementador poderia interpretar I4 (projeção obrigatória) como mais prioritário que I6 (interrupção imediata), projetando estado contaminado no Context Registry — que é exatamente o cenário que destrói a integridade do sistema.

7. Fluxo Completo

A etapa 5 (Confirmation Orchestrator) é o ponto onde ambiguidade humana é explicitamente endereçada antes de qualquer planejamento. O lock (etapa 11) é adquirido antes da revalidação (etapa 12) — fechando a race condition residual. O IDI na etapa 18 detecta drift de domínio antes que IFs detecte degradação de resultado.

8. Benefícios

9. Extension Points

Um sistema fechado não vira padrão — vira produto de uma empresa. Para o CFA ser adotável como framework, precisa de pontos de extensão declarados onde implementações específicas podem injetar comportamento de domínio sem modificar o núcleo.

Extension points são contratos de interface, não implementações. Cada ponto define o que o CFA espera receber e o que garante devolver — o que acontece dentro é responsabilidade da implementação.

extension_points:

  intent_normalizer:
    - custom_domain_resolver        # lógica de interpretação específica de domínio
    - catalog_enrichment_hook        # enriquecimento externo do catálogo antes da Signature
    - confidence_scorer_override     # modelo de confiança semântica customizado

  policy_engine:
    - custom_rule_provider           # regras declarativas externas (regulatory, domain)
    - external_compliance_validator  # validação contra sistemas legados não-IA

  execution_planner:
    - custom_template_library        # templates de código por domínio (Spark, SQL, dbt)
    - pre_cost_estimator_backend     # backend de estimativa de custo (AQE, histórico)

  context_registry:
    - storage_backend                # Delta, DynamoDB, Redis, etc.
    - snapshot_provider              # implementação de snapshot_consistent

  promotion_engine:
    - custom_promotion_signal        # sinal externo de business value
    - domain_window_provider         # evaluation_window por domínio

  audit_trail:
    - storage_backend                # S3, Kafka, OpenLineage, etc.
    - regulatory_formatter           # formato de auditoria por jurisdição

10. Escopo de Execução (v2)

O CFA v2 foi desenhado e validado para um modelo de execução específico. Declará-lo explicitamente protege o documento contra extrapolação indevida e define onde as garantias arquiteturais são válidas.

execution_model:
  version: v2
  supported_modes:
    - batch
    - micro_batch
  concurrent_intent_support: false         # uma intenção ativa por scope de destino
  streaming_support: planned_for_v3
  consistency_assumption: single_active_intent_per_target_scope

Por que batch e micro-batch — e não streaming

Três componentes do CFA v2 assumem implicitamente fronteiras discretas de execução, que existem em batch e micro-batch mas são problemáticas em streaming contínuo:

Concurrency Control

A declaração concurrent_intent_support: false não é suficiente sozinha. É necessário definir o que acontece quando duas intenções chegam simultaneamente sobre o mesmo scope — sem essa definição, race conditions são possíveis e o Invariante 3 pode ser violado silenciosamente.

concurrency_control:
  model: single_active_intent_per_target_scope

  scope_definition:
    - dataset
    - dataset_partition

  lock:
    acquisition: before_pre_execution_revalidation   # etapa 10 no fluxo
    release: after_state_projection_confirmed        # etapa 15 no fluxo

  conflict_resolution:
    on_conflict: queue              # queue | reject
    # queue: segunda intenção aguarda liberação do scope
    # reject: segunda intenção recebe blocked imediatamente

  locking:
    type: optimistic
    validation: pre_execution_revalidation

O modo queue é o padrão recomendado para batch — evita perda de trabalho. O modo reject é adequado para cenários onde latência importa mais que garantia de execução.

Snapshot Selection

A ambiguidade de qual snapshot o Context Registry serve a cada leitura é resolvida por uma única regra:

context_registry:
  snapshot_selection:
    strategy: latest_committed_before_intent_resolution
    # sempre o snapshot mais recente já atomicamente commitado
    # snapshot em progresso (write em andamento) nunca é servido

Roadmap de Escopo

11. Limitações

Estratégia de Implementação Faseada

12. Non-Goals (Escopo Negativo)

Um whitepaper técnico sério declara o que o sistema não se propõe a fazer. Non-goals protegem contra extrapolação indevida e definem onde o sistema termina — o que é tão importante quanto definir onde ele começa.

non_goals:
  # Escopo de execução
  - real_time_stream_processing       # planejado para v3
  - distributed_multi_writer_concurrency  # exige redesign de Context Registry
  - sub_second_latency_execution       # overhead de validação é intencional

  # Responsabilidade do sistema
  - data_quality_enforcement           # CFA governa execução, não qualidade intrínseca do dado
  - schema_inference                   # schema vem do catálogo, não é inferido
  - business_rule_definition           # CFA aplica regras, não as define

  # Implementação
  - storage_engine                     # agnóstico a engine (Spark, Databricks, etc.)
  - catalog_implementation             # depende de catálogo externo, não o implementa
  - policy_dsl_specification           # contrato de regra definido, DSL é escolha de implementação

13. Conclusão

O CFA v2 representa uma mudança de paradigma na relação entre IA e sistemas de dados críticos:

O que separa o CFA v2 de um conceito elegante é a presença dos elementos que tornam sistemas reais operáveis em produção:

Formalização do que é incerto — a resolução semântica com score de confiança e modos de confirmação trata a ambiguidade como dado do sistema, não como falha do usuário. Tolerância ao que falha parcialmente — a Partial Execution State com consistency_unit transforma a falha parcial de evento não representável em estado governado com política explícita. Memória do estado do mundo — o Context Registry com environment_state fecha o loop entre o que foi executado e o que pode ser executado a seguir. Garantias formais — os sete invariantes com regras de precedência tornam o sistema definível, testável e auditável.

Este documento é o produto de uma colaboração entre arquitetos de IA — cada revisão incorporou críticas reais sobre executabilidade, não apenas sobre elegância conceitual. A próxima etapa natural é o blueprint técnico: classes Python, interfaces e mapeamento de cada componente para código implementável.

B. Validação Automatizada dos Invariantes

Property-Based Tests para Invariantes Críticos

Os 8 invariantes do CFA são validados não apenas por testes unitários, mas por propriedades formais testadas com ferramentas como Hypothesis (Python):

# Exemplo: Invariante #3 - "Nenhuma escrita ocorre sem aprovação explícita do Policy Engine"
@given(
    signature=state_signature_strategy(),
    policy_rules=rule_set_strategy(),
    execution_trace=execution_trace_strategy()
)
def test_no_write_without_policy_approval(signature, policy_rules, execution_trace):
    engine = PolicyEngine(rules=policy_rules)
    result = engine.evaluate(signature)
    
    if result.action != PolicyAction.APPROVE:
        # Nenhuma operação de escrita deve aparecer no trace
        write_ops = [op for op in execution_trace if op.type == "WRITE"]
        assert len(write_ops) == 0, "Escrita ocorreu sem aprovação de política"

Chaos Engineering para Resiliência de Estado

Para validar a robustez do State Projection e do Context Registry, o CFA define um conjunto de fault injection scenarios executáveis em ambiente de staging:

chaos_scenarios:
  - name: "registry_unavailable_during_projection"
    fault:
      type: network_partition
      target: context_registry
      duration: 30s
    expected_behavior:
      - projection_paused
      - state_queued_for_retry
      - no_data_loss_after_recovery
      - audit_trail_records_fault_event
      
  - name: "partial_write_failure"
    fault:
      type: disk_write_error
      target: output_partition
      probability: 0.3
    expected_behavior:
      - rollback_to_last_consistent_snapshot
      - fault_registered_with_consistency_unit
      - user_notified_with_remediation_options

• Execução Automatizada: Cenários são executados semanalmente via pipeline CI/CD, com relatórios de resiliência integrados ao dashboard operacional.
• Feedback Loop para Design: Falhas detectadas em testes de caos alimentam diretamente o backlog de refinamento arquitetural, garantindo evolução baseada em evidências.