# Como uma LLM deve gerar o JSON de importação

Este guia descreve a versão atualmente implementada do Planejador, contrato `planejador/v2`. Consulte-o novamente quando o aplicativo mudar. Não acrescente campos de funcionalidades propostas que ainda não existem.

## Instrução pronta para usar

> Gere um arquivo JSON para importar no Planejador de Independência Financeira. Leia este guia e o exemplo em https://planejador.pages.dev/cenario-exemplo.json. Use somente os dados que eu fornecer como fatos. Identifique informações ausentes, pergunte pelas que afetam materialmente o resultado e liste separadamente qualquer hipótese aprovada. Não invente bases fiscais, taxas contratadas, renda, carências ou mudanças já realizadas na carteira. Entregue um arquivo .json válido, sem comentários, sem Markdown dentro do arquivo e sem dados de identificação. Explique fora do JSON o total do patrimônio, o agrupamento dos investimentos e as hipóteses usadas. Não afirme ter executado a simulação sem executá-la.

## Fluxo recomendado

1. Baixe o [exemplo completo](https://planejador.pages.dev/cenario-exemplo.json). Todos os valores são fictícios e ilustrativos, não recomendações.
2. Obtenha a data do inventário, ano de nascimento, saldos, custos históricos, despesas, aportes, renda extra, INSS e ano de saída.
3. Classifique cada investimento uma única vez. Confirme se subtotais incluem posições também listadas separadamente. Não some saldo bruto e líquido do mesmo ativo.
4. Converta saldos estrangeiros para BRL com o câmbio informado para a data do inventário. A base fiscal deve vir do custo histórico nominal em BRL: não converta automaticamente o custo em USD pelo câmbio atual. Se faltar, solicite o dado ou obtenha aprovação explícita de uma hipótese e sinalize-a fora do arquivo.
5. Substitua os valores do exemplo pelos dados e pelas premissas confirmadas. Uma alocação futura pretendida não é uma alocação atual já executada.
6. Confira total, unidades, datas e bases fiscais. Entregue `cenario-planejador.json`. Oriente o usuário a clicar em “Importar cenário”, conferir os valores e então em “Analisar Viabilidade Atuarial”.

## Formato obrigatório

O objeto externo contém `schema: "planejador/v2"` e `params`. Dentro de `params`, use `model_version: 2` e mantenha os campos do exemplo. `B0` tem B maiúsculo e zero; nomes são sensíveis a maiúsculas. Valores monetários são números, como `123456.78`, sem `R$` nem separadores de milhar. Percentuais são frações: 35% = `0.35`. Anos são inteiros. Booleanos são `true`/`false`, não strings. Use `null` apenas nos campos opcionais indicados. Não use `NaN`, `Infinity`, comentários ou vírgula após o último item. Limite do importador: 100.000 bytes.

## Patrimônio e custos

| Campo em params | Conteúdo |
| --- | --- |
| `B0.pos` | Caixa/pós-fixado: Selic e CDBs, com desconto estimado de IR preexistente conforme o campo da interface. Se só houver saldo bruto, explicite essa aproximação. |
| `B0.lca` | LCA/LCI e renda fixa isenta agregada. Agrupar CRA aqui exige explicitar a simplificação de risco e liquidez. |
| `B0.jr` | Tesouro IPCA+/NTN-B agregado. Título público identificado como NTN-B pertence aqui, não automaticamente em pós-fixado. |
| `B0.vgbl`, `B0.pgbl` | Saldo bruto de cada modalidade, incluindo RF e bolsa; não some os componentes novamente. |
| `B0.rv_br`, `B0.rv_off` | Bolsa Brasil e ativos diretamente no exterior, respectivamente. ETFs e ações estrangeiras entram no offshore. |
| `B0.fii` | Valor de mercado dos FIIs. Não some dividendos já reinvestidos ou já incluídos no caixa. |
| `planning.crypto` | Saldo de cripto/outros. Não repita esse valor em B0. |
| `base.vgbl` | Base de contribuições remanescente após eventuais resgates. Não deduza a base de um valor líquido estimado sem confirmar como esse líquido foi calculado. |
| `base.rv_br`, `base.rv_off` | Custo fiscal histórico nominal em reais das posições remanescentes; não é valor de mercado. Pode superar o saldo em caso de prejuízo. |

Total investível = soma dos oito campos `B0` + `planning.crypto`. Bases fiscais não são patrimônio adicional. Não inclua imóveis, veículos ou participações empresariais sem configuração explícita. Valores de patrimônio e base entre zero e 1 trilhão.

## Fluxo e calendário (campos em params)

| Campos | Unidade e significado |
| --- | --- |
| `ano_base`, `ano_nascimento`, `saida` | Ano do inventário, nascimento e último ano de acumulação. O ano-base é uma fotografia. Aportes ocorrem de ano_base + 1 até saida, inclusive; retiradas começam em saida + 1. |
| `gasto`, `aluguel` | Gasto mensal e redução mensal na aposentadoria. `aluguel` é uma redução, não uma despesa a somar. |
| `aporte` | Aporte anual em reais do ano-base; não mensal. |
| `extra`, `inss`, `anoInss` | Renda extra mensal, benefício mensal e início do INSS. Não presuma benefício nem elegibilidade. O motor não calcula IR pessoal dessas rendas separadamente: informe o valor disponível para despesas ou explicite o uso do bruto. |
| `cortaFilhas`, `anoFilhas` | Redução mensal de despesas e ano em que começa; esse ano também aciona a redução de saúde configurada. |
| `saude` | Gasto mensal de saúde separado. Use zero se mantido dentro de gasto, para não duplicar. Para aplicar inflação médica separadamente, retire o custo atual de saúde de gasto e informe-o aqui. |
| `vcmh`, `vcmhLongo`, `saudeFilhas` | Inflação médica adicional ao IPCA inicial (0–0.10 na interface), de longo prazo (0–0.05), e redução proporcional de saúde (0–0.80). |
| `dynamic` | Guardrail. Se o usuário não aceita cortes, use false. Isso não desativa reduções de despesas explicitamente agendadas. |

Ano-base aceito pela interface: 1900–2100; nascimento deve produzir idade entre 18 e 94 no ano-base; saida entre ano_base e 2130. Verifique anos de eventos conforme a situação do usuário. Campos monetários do fluxo são não negativos.

## Retorno, impostos e estresse (campos em params)

| Campos | Valores compatíveis com a interface |
| --- | --- |
| `ipca`, `rf`, `rv`, `swr` | Frações anuais: IPCA 0.02–0.10; RF 0.02–0.10; bolsa 0–0.12; SWR 0.02–0.06. RF e bolsa são retornos reais, não nominais. SWR é referência inicial de retirada, não garantia. |
| `irPrev` | Alíquota efetiva estimada de resgate previdenciário: 0–0.275. É a referência comum, substituída por advanced.vgbl_tax e advanced.pgbl_tax quando informadas. |
| `vol` | Volatilidade anual da bolsa e dos FIIs: 0–0.30. |
| `tetoBolsa`, `pisoBolsa` | Limites fixos de bolsa, 0.20–1 e 0–0.80; piso deve ser menor ou igual ao teto. Incluem bolsa dentro da previdência, mas não FIIs. Com glide ligado, são substituídos pelo alvo e banda. |
| `anoCrash`, `dropCrash` | Ano inteiro e queda positiva como fração. Ex.: 2032 e 0.40 representam queda de 40% em 2032. Para cenário sem crash, use dropCrash = 0 e recovery_years = 0, com anoCrash depois do horizonte, por exemplo 2251. Usar apenas queda zero ainda substitui o retorno do ano escolhido por zero. |

As faixas acima priorizam compatibilidade com a interface; o motor aceita algumas faixas mais amplas. O importador expande limites dos sliders para preservar valores válidos importados. Não dependa dessa expansão para inventar premissas. As alíquotas editáveis ficam em `advanced`, conforme a tabela abaixo. Não invente nomes de campos.

## Campos de planning

Inclua o objeto completo do exemplo. Datas opcionais aceitam `null`; os demais campos precisam de número ou booleano.

| Campos | Significado / limites |
| --- | --- |
| `vgbl_equity`, `pgbl_equity` | Fração atual de bolsa dentro de cada modalidade, 0–1. Restante recebe retorno RF previdenciário. |
| `pension_rf_return` | Retorno real anual RF da previdência, líquido das taxas do fundo, antes do IR de resgate: -0.10 a 0.20. `null` usa RF menos 1,2 p.p. |
| `extra_start`, `extra_end` | Anos inclusivos, 1900–2250 ou null. null significa desde o ano-base / até o fim. Não presuma trabalho vitalício se a duração não foi informada. |
| `spending_change_year`, `spending_change` | Ano opcional e alteração proporcional do custo de vida, -1 a 1. |
| `contribution_start` | true = aporte no início; false = fim do ano. |
| `glide`, `equity_start`, `equity_end`, `glide_end` | Habilitação, alvos inicial/final de bolsa (0–1) e ano final (1900–2250 ou null = saída). Alvo final permanece constante após essa data. |
| `band` | Tolerância em fração de pontos percentuais: 0.02 = 2 p.p.; limite 0–0.20. |
| `reserve_months` | Meses de reserva, 0–120. A base padrão é a retirada necessária; advanced.reserve_basis pode mudar para gasto total. A reserva já integra o patrimônio. |
| `rf_vol`, `correlation` | Volatilidade anual RF 0–0.30 e correlação RF × bolsa -1 a 1. |
| `offshore_distribution` | Distribuição anual como fração do saldo offshore: 0–0.15. É parte do retorno total, não retorno adicional. VWRA acumulador não distribui ao cotista; uma carteira com VT deve usar hipótese ponderada aprovada. |
| `offshore_withholding`, `offshore_losses` | Retenção estrangeira nas distribuições (0–0.50) e perdas fiscais compensáveis em BRL nominal (0–1 trilhão). Não invente perdas a partir de oscilação não realizada. |
| `crypto`, `crypto_return`, `crypto_vol` | Saldo, retorno real líquido (-0.30 a 0.30), volatilidade (0–1). |
| `recovery_years`, `recovery_return` | Número inteiro de anos de recuperação após crash (0–20) e retorno real anual imposto nesse intervalo (-0.50 a 0.50). Não garante recuperar o preço anterior. |
| `deterministic_only` | Use true no arquivo da interface. A tela executa separadamente o Monte Carlo em segundo plano, com advanced.mc_rounds (5.000 por padrão). |

`rodadas_mc` e `semente` são opções da chamada direta ao motor (rodadas: 1–50.000). Para importação/exportação pela tela, use `advanced.mc_rounds` e `advanced.simulation_seed`, que são preservados. O botão de recalcular usa a mesma semente; altere-a no formulário para testar outra amostra. Novas versões do motor podem mudar resultados da mesma semente.

## Campos opcionais de advanced

O objeto `params.advanced` amplia o contrato v2. O exemplo público sem esse objeto continua válido e mantém a avaliação legada aos 94 anos. Novos cenários da tela usam 100 anos e destino global. Para uma nova análise, confirme explicitamente a idade final e a política desejada; não mude um arquivo antigo sem explicar. Campos omitidos neste objeto recebem os padrões legados descritos abaixo. A reexportação normaliza o objeto com todos os campos. Campos desconhecidos em advanced são rejeitados.

| Campos | Significado / padrão quando omitido |
| --- | --- |
| `final_age` | Inteiro 95–120, posterior ao ano de saída. Define fim da projeção, sucesso e saldo terminal. `null` mantém avaliação aos 94 e projeção legada até o maior entre 2130 e idade 110. Para novos cenários, recomenda-se discutir pelo menos 100 anos. |
| `mc_rounds`, `simulation_seed` | Inteiro 5.000–50.000, padrão 5.000; semente inteira 0–4294967295, padrão 20260906. Ambos exportáveis. |
| `offshore_tax`, `brazil_equity_tax` | Alíquotas sobre ganho nominal realizado, 0–0.60; padrão 0.15. Offshore também tributa distribuições. Valores hipotéticos, não mudança automática na legislação. |
| `cash_tax`, `bonds_tax`, `other_fixed_tax` | Alíquotas 0–0.60, padrões 0.15, 0.15 e 0. RF agregada usa arrasto fiscal sobre rendimento nominal positivo; títulos detalhados tributam cupons/resgate. |
| `vgbl_tax`, `pgbl_tax` | Alíquotas efetivas 0–0.60 ou `null` (herda irPrev). VGBL sobre ganho nominal; PGBL sobre total. Não modela tabela progressiva, deduções ou lotes regressivos individuais. |
| `withdrawal_order` | Permutação de todos os índices 0–8, sem repetição. Padrão `[0,1,3,4,2,6,5,7,8]`. Índices: 0 caixa, 1 LCA/outros RF, 2 IPCA+, 3 VGBL, 4 PGBL, 5 bolsa Brasil, 6 offshore, 7 FII, 8 cripto/outros. |
| `reserve_basis` | `"withdrawals"` (padrão: necessidade da carteira) ou `"spending"` (gasto após reduções programadas, incluindo saúde, antes de INSS/renda extra). |
| `reserve_min_months` | Número entre 0 e planning.reserve_months; padrão 0. Limiar da reposição minimum. |
| `refill` | `"annual"` (padrão), `"minimum"` (caixa abaixo do mínimo), `"positive"` (retorno de bolsa positivo no ano), `"overweight"` (bolsa acima do alvo/teto), `"never"`. Reposição avaliada a partir do ano de saída, antes do saque. |
| `refill_sources` | Índices 1–8 únicos, em ordem; padrão `[1,2]`. Lista vazia desativa fontes. Vendas tributáveis pagam imposto; títulos detalhados não podem ser vendidos. |
| `protection`, `drawdown_threshold` | false e 0.20 por padrão. Queda desde o pico do índice de bolsa, não do saldo após saques. Limiar 0.01–1. Em proteção, bolsa/FII/previdência com bolsa vão ao fim dos saques e não são vendidos para reposição/rebalanceamento. Não proíbe venda se outras fontes acabarem. |
| `withdraw_overweight` | false por padrão. Prioriza bolsa Brasil/offshore nas retiradas quando acima da banda, fora da proteção. |
| `equity_destination` | 6 global ou 5 Brasil. Destina novas compras e a parcela de bolsa direta dos aportes; não transfere automaticamente a carteira existente nem muda a previdência. `null` (legado): aportes proporcionais à posição inicial e compras de rebalanceamento Brasil. |
| `extra_indexed`, `extra_tax` | true e 0 por padrão. false mantém renda nominal constante desde o ano-base; alíquota efetiva 0–0.60 reduz renda disponível. Se extra já é líquido, use imposto zero para não tributar duas vezes. INSS continua informado como valor disponível. Datas inclusivas permanecem em planning. |
| `returns` | null ou quatro retornos reais anuais: `[caixa, IPCA_agregado, outros_RF, bolsa]`, cada um -0.30–0.30. null herda rf−0.007, rf+0.018, rf+0.003, rv. Previdência RF mantém premissa própria; FII usa bolsa−0.01. Não substitui fluxos contratuais de títulos detalhados. |
| `volatilities` | null ou quatro volatilidades 0–1, na mesma ordem. null herda rf_vol nas três RF e vol na bolsa. Previdência RF usa risco do caixa; bolsa previdenciária e FIIs usam risco da bolsa. Nos títulos detalhados, risco IPCA é choque na taxa real de desconto. |
| `correlations` | null ou matriz 4×4, na mesma ordem; simétrica, diagonal 1, valores -1–1, semidefinida positiva. null usa a correlação RF × bolsa anterior. Não invente matriz “histórica” sem dados. Cripto permanece independente. |
| `bonds` | Lista de até 30 títulos; padrão `[]`. Cada item exige os cinco campos da descrição abaixo. |

Título em `advanced.bonds`: `{ "value": 10000, "basis_nominal": 9000, "maturity_year": 2032, "redemption_real": 13000, "coupon_real": 0 }` é apenas exemplo sintético. `value` é valor atual já incluído em B0.jr; soma dos títulos não pode superar B0.jr. `basis_nominal` é custo fiscal histórico em BRL. `redemption_real` é resgate contratual e `coupon_real` cupom anual, ambos em poder de compra do ano-base. Valores 0–1 trilhão, value e redemption_real positivos; vencimento inteiro após ano-base e até 2250. Cupom anual agrega os semestrais: não reproduz datas exatas.

Não confunda saldo de mercado com resgate contratual. Só cadastre um título com fluxo e custo confirmados. A taxa implícita vem do preço/fluxos; cada ano estocástico reprifica os fluxos restantes com choque em torno dessa taxa. No vencimento, transfere o resgate líquido ao caixa. Não permite venda antecipada, não inclui risco de crédito e não trata um fundo IMA-B como título que vence. A parte não detalhada de B0.jr continua agregada. Se faltarem os dados, mantenha-a agregada e sinalize a limitação — nunca invente cupons, quantidade ou principal.

## Busca de gasto sustentável

Disponível por botão nos resultados ou `gasto_sustentavel(JSON.stringify(params))` no WASM. Não há endpoint. Compara gasto-base (`gasto`, não saque) para metas de sucesso 99%, 95%, 90% e 80%, com e sem renda extra; mantém INSS e demais despesas e desliga guardrail somente nessa comparação. Retorna limite inferior testado, sucesso observado e limite superior, com intervalo de até R$10/mês quando convergente. Busca binária com as mesmas sequências; políticas condicionais podem gerar não monotonicidade, portanto não é prova de máximo global nem garantia futura. Há estados para inviável até com gasto zero e teto da busca (R$10 milhões/mês). O cálculo é sob demanda, local e cancelável.

## Conferência e limitações

- Confira cada valor importado, o ano do primeiro saque, as rendas vigentes e se o guardrail corresponde à escolha do usuário.
- O exemplo público é testado pelo importador real e pela reexportação nos testes do projeto. Isso valida o formato, não a qualidade das hipóteses pessoais.
- Não execute conteúdo do JSON como código. Não inclua nome, CPF, contas, credenciais ou extratos no arquivo. A importação é local; o cenário pode ficar no armazenamento da sessão da aba para voltar da metodologia.
- Há projeção determinística, Monte Carlo e crash configurado. Um choque manual é um estresse hipotético, não uma série histórica observada.
- Títulos individuais, matriz, ordem de saque e risco usam apenas os campos de advanced documentados acima. Não há consulta automática a corretoras nem atualização legal automática.
- Motor: `simular(JSON.stringify(params))`. Resposta: `model_version`, `accRun`, `dd`, `mc`, `exits`, `stats`, `first_withdrawal`. Isso é uma função local de WebAssembly; não existe endpoint HTTP de simulação.
- Cada ano de `dd.series` inclui `actions`, lista ordenada das operações realmente simuladas: tipo (`kind`), índices de origem/destino (`source`, `destination`, ou null), valor bruto (`gross`), imposto (`tax`) e líquido (`net`). Aportes, saques para despesas, reposição, rebalanceamento, trocas internas de previdência, cupons, vencimentos e reinvestimentos são distintos. `required_withdrawal` é a necessidade anual após eventual guardrail; `withdrawal_shortfall` é a parte não paga. Esses são campos de saída: não coloque o roteiro dentro dos parâmetros de importação nem deduza operações apenas comparando saldos.
- Resultados principais são BRL do ano-base. Custos fiscais e perdas são BRL nominais históricos. Não confunda as duas unidades.

Veja a [metodologia](https://planejador.pages.dev/metodologia.html) para fórmulas e limites. Somente declare uma validação de execução quando tiver usado de fato o motor ou o navegador.