Análise de carteira construída sobre uma regra: código determinístico calcula os números e o modelo os narra

O problema

Um relatório de patrimônio é uma lista de números, e a maioria desses números chega sem fonte, sem data e sem método. Uma cotação pode ser de ontem. Uma avaliação pode se apoiar em um preço que ninguém consegue rastrear. Quando um modelo de linguagem é colocado diante de um relatório assim, o risco cresce: o modelo pode produzir uma frase fluente com um número que nenhum cálculo sustenta.

O Portfolio Horizon, descrito na própria página como "Private Wealth Intelligence System" (sistema de inteligência patrimonial privada), foi construído sobre uma regra, não sobre uma promessa: cada número tem fonte, data e método, e o modelo de linguagem nunca é chamado para calcular um número, só para narrar os números que recebe.

O Portfolio Horizon não é recomendação de investimento e não faz nenhuma afirmação de desempenho.

O que foi construído

A página pública declara o que o sistema faz: reavaliação de carteira ao vivo, análise de risco e leitura probabilística de cenários. O título, em inglês, é "Your portfolio, with every figure traceable." (seu patrimônio, com cada número rastreável). Ela nomeia três atributos: patrimônio rastreável, câmbio PTAX oficial e IA explicável.

Seis compromissos estão listados na página: fonte e horário no número exibido; câmbio PTAX oficial datado; horizonte e limites por previsão; indisponibilidade declarada; adequação explícita; leitura probabilística. Quatro blocos repetem a ideia de forma mais curta: PTAX, o câmbio oficial datado; fontes, com origem e horário visíveis; lacunas, declaradas em vez de escondidas; código, ou seja, cálculos determinísticos.

A carteira mostrada na página pública é um exemplo ilustrativo. A composição é rotulada como fictícia e a demonstração roda sobre dados sintéticos. Nenhuma carteira de cliente é mostrada nem alegada.

Como funciona

A regra do próprio repositório é que todo número exibido vem de funções determinísticas em src/quant e que o modelo de linguagem só narra os números que recebe. O que foi medido é mais estreito. Na formulação do projeto: "As exposições, a concentração, a liquidez, o VaR paramétrico e o motor de cenários são determinísticos e cobertos por testes ao centavo." (execução de 31 de julho de 2026). O modelo de linguagem fica depois dessa etapa: recebe os números calculados e escreve a narrativa em torno deles.

O câmbio segue uma cadeia de resolução. Na formulação do projeto: "O endpoint GET /api/fx resolve a PTAX de fechamento do BACEN: primeiro o boletim de hoje, depois até quatro dias úteis anteriores, por fim a referência local rotulada. O rótulo exibido declara o que o número é, com data e fonte." Em 24 de setembro de 2026, a página pública mostrava o estado de dia útil anterior, com o texto, em inglês, "Latest available PTAX. Official close from the last available business day. Not an intraday quote." (última PTAX disponível; fechamento oficial do último dia útil disponível; não é cotação intradiária).

Entre o modelo e o leitor há uma fronteira de saída projetada para falhar fechada. Na formulação do projeto: "Na suíte adversarial documentada executada em 31/07/2026, a fronteira de saída fail-closed não liberou número financeiro sem suporte sob o modelo de ameaça especificado." O modelo de ameaça: payloads adversariais de prompt contra a via de orquestração, com a saída do modelo nunca renderizada diretamente para o cliente. A rota pública de entrevista de perfil está fora desse limite e não carrega nenhuma afirmação.

Sobre a procedência, na formulação do projeto: "No escopo dos resultados operacionais verificados em 31/07/2026, o número exibido informa função, provider e horário de referência." E ainda: "No escopo verificado em 31/07/2026, o número exibido no relatório abre a trilha de evidência que o originou." As previsões recebem a mesma disciplina: "No escopo verificado em 31/07/2026, a previsão exibida vem acompanhada de horizonte, metodologia e limites." A página resume em cinco palavras: a IA justifica, você decide.

Evidências

Tudo o que o Portfolio Horizon diz em público é delimitado pela allowlist de afirmações externas do próprio projeto (a lista do que pode ser dito), decidida em 31 de julho de 2026, e por um registro de afirmações retidas que anota cada declaração removida e o motivo (fato portfolio-horizon-16). A verificação é mecânica: um lint falha se uma formulação permitida não consta da allowlist ou se uma formulação retida reaparece em uma superfície pública, e cada comando de reprodução da allowlist é reexecutado e tem o resultado registrado.

Os números que sobrevivem a esse processo são contagens de testes, cada uma ligada a um comando e a uma data. Em 31 de julho de 2026, na execução por trás da afirmação do núcleo determinístico, 67 testes passaram em 6 arquivos; essa execução cobre o núcleo quantitativo, a cadeia PTAX e as afirmações da página inicial (allowlist EXT-A03, fato portfolio-horizon-14). Na cadeia de resolução da PTAX, sozinha, 11 testes passaram, e eles fazem parte desses 67 (allowlist EXT-A02, fato portfolio-horizon-13). Na suíte adversarial por trás da fronteira de saída fail-closed, 415 testes passaram em 11 arquivos, e a fronteira não liberou número financeiro sem suporte sob o modelo de ameaça especificado (allowlist EXT-B03, fato portfolio-horizon-12).

O rodapé da própria página declara o limite do que afirma. Na formulação do projeto: "Previsão não é promessa. No escopo verificado em 31/07/2026, a tela preditiva declara horizonte, confiança e limites." (página no ar, fato portfolio-horizon-11). Nenhum número de desempenho, retorno ou acurácia de previsão é publicado, porque nenhum está na allowlist.

Tecnologias

O Portfolio Horizon é uma aplicação web escrita em TypeScript: React 19 com Vite no cliente, Express no servidor, Tailwind CSS para estilo e Zod para validação. Os dados ficam em PostgreSQL, acessados pelo cliente pg e pelo cliente do Supabase. O Vitest roda os testes unitários nomeados na allowlist e o Playwright roda os testes end-to-end. O site no ar roda a mesma stack: o cabeçalho de resposta menciona o Express e a página carrega um bundle do Vite.

O que demonstra

Definir. A tarefa tinha uma definição mensurável antes de qualquer modelo ser escolhido: uma leitura patrimonial em que cada número carrega fonte, data e método, e em que as lacunas são declaradas em vez de preenchidas.

Instrumentar. A avaliação existe em duas camadas. O núcleo quantitativo é coberto por testes unitários ao centavo e a cadeia de câmbio por seus próprios testes unitários, ambos em uma execução datada de 31 de julho de 2026. A fronteira de saída é coberta por uma suíte adversarial com modelo de ameaça declarado. Acima do código, as próprias afirmações são instrumentadas: uma allowlist de formulações exatas, um registro de afirmações retidas e um lint que falha quando qualquer um dos dois é violado.

Integrar. A PTAX oficial, o rótulo de procedência no número exibido, a trilha de evidência e a indisponibilidade declarada fazem parte do produto, não de um slide sobre ele.

Transferir. A allowlist e o registro de afirmações retidas são o runbook do que pode ser dito. Eles sobrevivem à construção e podem ser reexecutados por qualquer pessoa com o repositório, que é como a NASCIA prefere entregar um sistema: com os testes, os limites e as palavras, tudo por escrito.