@fc/calculos-rgps

Biblioteca de domínio do RGPS — Regime Geral de Previdência Social usada pelas apps prev-tc, prev-rvt, prev-atrasados, prev-api e rmi-api.

Estende @fc/calculos-previdenciarios, que guarda o que o RGPS e o RPPS têm em comum — período, segurado, histórico, dados do cálculo, contrato de requisito e aritmética de tempo. Aqui fica o que é do regime geral: RMI, atrasados, evolução de benefício, fator previdenciário, qualidade de segurado, os requisitos do RGPS e a leitura dos documentos do INSS.

Ela concentra:

contagem de tempo e carência
análise de elegibilidade a benefícios
cálculo de RMI e Revisão da Vida Toda
evolução de benefícios
cálculo de atrasados judiciais

Este README prioriza:

contrato real do código
fluxos reais de uso nas apps
pontos de mutação e efeitos colaterais
onde adicionar novas regras sem quebrar regras antigas

Índice

Visão geral
Superfície pública do pacote
Conceitos centrais do domínio
Entidades principais
Fluxos canônicos de uso
Módulos do pacote
Efeitos colaterais e mutabilidade interna
Como as apps consomem a biblioteca
Guia para novas regras
Estratégia de testes
Armadilhas para agentes de IA
Dependências externas

Visão geral

O pacote implementa regras previdenciárias cujo comportamento varia por:

espécie de benefício
tipo de segurado
marcos legislativos
data de apuração
composição do histórico contributivo

A arquitetura reflete isso:

flowchart TD
  A["parametros / entidades"] --> B["requisitos / calculo-tc"]
  B --> C[analise-beneficios]
  C --> D[calculo-rmi]
  D --> E[evolucao-beneficio]
  E --> F[calculo-atrasados]

Há também módulos horizontais de suporte:

persistencia
documentos — tudo o que existe por causa de documento importado, em quatro estágios: documentos/plugins/<documento>/ (um plugin de leitura por documento; tipos.ts na raiz de documentos/ guarda os DTOs que eles produzem), documentos/segmentacao/ (isolamento de exemplares em PDFs com mais de um documento e ReferenciaExemplarDocumento), documentos/importacao/ (TipoDocumentoPrevidenciario, registroDocumentosPrevidenciarios entregue ao importador genérico de @fc/parsers, mapearTipoSegmentado, atualizarReferenciasDocumentais, prepararImportacaoPrevjud) e documentos/filtros/ (filtros de períodos e salários importados antes de entrarem no cálculo)
qualidade-segurado
segurado
utilidades-apis

O diretório documentos/plugins concentra os plugins RGPS (antes hospedados no antigo @fc/analisador-de-texto), incluindo:

CNIS
carta de concessão
RDCTC
formulário PJe
HISCRE
PDF Fábrica
planilha Google
plenus
processo
sibe-conbas
sibe-hiscal
tempo de contribuição

Superfície pública do pacote

Como consumir

O pacote não tem barrel: nem src/index.ts de raiz nem index.ts de pasta. Cada módulo é publicado pelo subpath do arquivo que o declara, e o consumidor importa exatamente o que usa:

import type { ArquivoTc } from '@fc/calculos-rgps/persistencia/tc/tipos'
import { AnaliseBeneficios } from '@fc/calculos-rgps/analise-beneficios/AnaliseBeneficios'
import { DadosCalculo } from '@fc/calculos-rgps/entidades/DadosCalculo'
import { FormaContagem } from '@fc/calculos-rgps/parametros/forma-contagem/FormaContagem'
import { PluginCnisCompleto } from '@fc/calculos-rgps/documentos/plugins/cnis/PluginCnisCompleto'
import { lerArquivoTc } from '@fc/calculos-rgps/utilidades-apis/tempo/conversor-arquivo/lerArquivoTc'

O import pela raiz (from '@fc/calculos-rgps') não resolve e é barrado pela cerca fc/cerca-pacotes-sem-barrel-raiz do @fc/eslint-config. Os plugins do analisador vivem um por arquivo (documentos/plugins/<documento>/Plugin<Nome>.ts; os leitores de CNIS têm a lista única documentos/plugins/pluginsCnis), e as cadeias de migradores são persistencia/tc/migradoresTc e persistencia/atrasados/migradoresAtrasados. O teste tests/arquitetura/sem-barrels.spec.ts tranca a ausência de index.ts.

O que o `package.json` expõe

O export map de package.json publica cada pasta de src/ por wildcard — @fc/calculos-rgps/<pasta>/* para analise-beneficios, calculadoras, calculo-atrasados, calculo-rmi, calculo-tc, entidades, evolucao-beneficio, fator-previdenciario, quadro-resumo, simulacao-por-totais, documentos (com documentos/plugins/*, documentos/segmentacao/*, documentos/importacao/* e documentos/filtros/* pelo mesmo wildcard), parametros, persistencia, qualidade-segurado, requisitos e utilidades-apis — mais os subpaths de apoio a teste:

@fc/calculos-rgps/testes/paridade-calc/*, suporte de teste para as apps previdenciárias (alinharResultados, caminhos, compararResultadosIntegral…)
@fc/calculos-rgps/testes/prevjud, builders compartilhados de cenários PrevJud

src/segurado/ segue privado (nunca esteve no barrel). O wildcard alcança também arquivos que o barrel escondia — helpers internos —, que continuam fora do contrato: ver "O que não deve ser tratado como API estável".

Superfície preferencial para entrada e saída

Na fase atual de unificação entre web e APIs, a superfície preferencial para adaptação de entrada/saída passou a ficar nas classes centrais do domínio:

DadosCalculo.deEstadoWeb(...) para o formato usado pelo worker do prev-tc
DadosCalculo.deApiTempo(...) para payloads CalculoTempoApi
DadosCalculo.deApiTempoPrevjud(...) para payloads CalculoTempoPrevjudApi
DadosCalculo.deApiRmi(...) para payloads CalculoRmiApi
DadosCalculo.deApiRmiPrevjud(...) para payloads CalculoRmiPrevjudApi
DadosCalculo.deApiRmiDesvinculada(...) para payloads CalculoRmiDesvinculadaApi
DadosCalculo.deApiRmiDesvinculadaPrevjud(...) para payloads CalculoRmiDesvinculadaPrevjudApi
DadosCalculo.deArquivoTc(...) para arquivos .calc
DadosCalculo.dePrevjud(...) para importar DadosPrevjud sobre um estado-base no mesmo formato da web
AnaliseBeneficios.paraApiResultado(...) e AnaliseBeneficios.paraApiGrupos(...) para saídas de tempo
CalculoRmi.paraApiBloco(...) e CalculoRmi.paraApiDesvinculada(...) para saídas de RMI

Os entrypoints legados em utilidades-apis continuam exportados e suportados nesta fase, mas agora funcionam como fachadas de compatibilidade sobre essa nova superfície.

Nas entradas de RMI, criterioSalarioMaternidade aceita UM_DOZE_AVOS ou MEDIA_SIMPLES_DOZE_ULTIMOS; quando omitido, usa UM_DOZE_AVOS. A leitura de um Arquivo .calc preserva esse critério no JSON devolvido. Em PeriodoContribuicaoApi, origem também usa valores nominais (CALCULO_INSS, CNIS, USUARIO, NENHUMA, PREVJUD ou MULTIPLA), e valores fora desse contrato são rejeitados.

O que não deve ser tratado como API estável

Os seguintes diretórios existem e são relevantes para entender a implementação, mas não devem ser assumidos como contrato externo estável:

src/utilidades/
src/calculadoras/
arquivos internos obterRegras*.ts
helpers internos de calculo-rmi, calculo-atrasados e calculo-tc

Se uma nova feature puder ser implementada usando símbolos já publicados pelos subpaths, prefira isso.

calcularPrescricaoParcelasSucessivas(...) é a exceção pública dentro de src/calculadoras: recebe o intervalo real de vencimentos da dívida, a data do ajuizamento e o prazo em meses civis. Opcionalmente, processa um marco interruptivo anterior e um período de suspensão. O resultado separa os períodos prescrito e não prescrito; a parcela cujo vencimento prescricional coincide com o ajuizamento permanece não prescrita.

Conceitos centrais do domínio

Espécies de benefício

O enum EspecieBeneficio concentra os códigos INSS em src/parametros/especie-beneficio/EspecieBeneficio.ts.

Espécies atualmente declaradas:

Código	Identificador
21	`PensaoPrevidenciaria`
25	`AuxilioReclusao`
31	`AuxilioPorIncapacidadeTemporaria`
32	`AposentadoriaPorIncapacidadePermanente`
36	`AuxilioAcidentePrevidenciario`
41	`AposentadoriaPorIdade`
42	`AposentadoriaPorTempoDeContribuicao`
46	`AposentadoriaEspecial`
57	`AposentadoriaPorTempoDeServicoProfessor`
80	`SalarioMaternidade`
87	`AmparoSocialPcd`
88	`AmparoSocialIdoso`
91	`AuxilioPorIncapacidadeTemporariaAcidentario`
92	`AposentadoriaPorIncapacidadePermanenteAcidentaria`
93	`PensaoAcidentaria`
94	`AuxilioAcidenteAcidentario`
95	`AuxilioSuplementar`

Agrupamentos importantes para regras:

AposentadoriasProgramadas
BeneficiosNaoProgramados
BeneficiosComum
BeneficiosPcd
BeneficiosRuricola
ComFator
ComDivisorMinimo
AcumulacaoEC103
ComputaveisComoSalario
ComputavelComoTempo
ComputavelLc123
BeneficiariosDependentes
NaoAdmitemDerivado
BpcLoas
ElegiveisRvt

Ao adicionar nova espécie, quase nunca basta alterar só o enum. Normalmente também é preciso revisar esses agrupamentos.

Tipos de segurado

TipoSegurado define:

Comum
Pcd
Ruricola

Esse tipo altera:

quais regras são geradas em RegrasConcessao
quais grupos aparecem em AnaliseBeneficios.apurarGrupos()
divisor e critérios em certas modalidades de RMI
possibilidade de direito adquirido ou tratamento especial em cenários pós-EC 103

Marcos temporais

MARCOS_TEMPORAIS em src/parametros/marcos-temporais/marcosTemporais.ts centraliza datas legislativas.

As mais usadas no RGPS são:

cf88
lei8213
lei9032
dpe20
lei9876
lc142
regraPontos
elevacaoPontos
lei13846
dpe103
divisorMinimo
transicoesEc103

Regra obrigatória para novas implementações:

nunca codifique datas literais em regra
sempre compare com MarcosTemporais

Unidade de tempo

Grande parte da biblioteca usa a convenção previdenciária de:

1 ano = 360 dias
1 mês = 30 dias

Isso afeta:

tempo de contribuição
idade previdenciária em várias regras
pedágio
pontos

Os testes das apps frequentemente formatam dias nessa convenção, como em apps/prev-tc/test/nuxt/helpers.ts.

Requisitos de concessão

Os requisitos são implementados em src/requisitos/ e retornam o contrato ResultadoRequisito, declarado em src/requisitos/tipos.ts.

Contrato real resumido:

interface ResultadoRequisito {
  dataApuracao: Date
  nome: string
  rotulo: string
  resultado: {
    requisito: number
    apurado: number
    cumprido: boolean
    implementadoEm?: Date | Record<string, Date>
    paraPontos?: number
    paraCoeficiente?: number
    nota?: string
    inconsistencia: boolean
    porExtenso: string
    parametros?: {
      tipoContagem?: TipoContagem
      computarLc123?: boolean
      pedagio?: {
        dpe: Date
        patamar: number
        percentual: number
      }
      carencia?: {
        apenasRural: boolean
      }
    }
  }
}

Observação importante:

implementadoEm não é sempre uma Date; em alguns requisitos é uma tabela por competência.

Entidades principais

`HistoricoRgps`

Classe central do histórico contributivo em src/entidades/HistoricoRgps.ts.

Ela recebe:

lista de PeriodoContribuicao
lista de PeriodoPcd

E mantém:

mapas pré-calculados de tempo e carência
competências descartadas
competências excluídas
períodos excluídos derivados dessas competências

Também expõe operações como:

analisarComum
analisarPcd
analisarRural
analisarEspecial
descartar
excluirUltimoDescarte
excluirTodosDescartes

`DadosSegurado`

Contrato real em src/entidades/DadosSegurado.ts:

new DadosSegurado({
  sexo: Sexo,
  nascimento: Date | string,
  tipo: TipoSegurado,
  historico: HistoricoRgps,
  salarios?: Salarios,
  salariosAnoCivil?: Salarios,
  beneficios?: Beneficios,
})

Observações:

o nome real do campo é nascimento, não dataNascimento
o nome real do campo é tipo, não tipoSegurado
salarios e beneficios são opcionais, mas muitas integrações reais dependem deles
tipo possui setter e é alterado temporariamente por apurarGrupos()

`DadosCalculo`

Contrato real em src/entidades/DadosCalculo.ts:

new DadosCalculo({
  dadosSegurado: DadosSegurado,
  dataApuracao?: Date | string,
  der: Date | string,
  derReafirmada?: Date | string,
  especie: EspecieBeneficio,
  marcoCarencia: MarcoCarencia,
  requisitoB41Pcd: RequisitoB41Pcd,
  aplicarIrsmFev94: boolean,
  calcularRmiPcdComRegraAnterior: boolean,
  calcularRmiComRegraAnteriorNaEc103: boolean,
  criterioSalarioMaternidade: CriterioSalarioMaternidade,
  coeficienteInformado?: number,
  tempoInformadoAnos?: number,
  tempoInformadoMeses?: number,
  tempoInformadoDias?: number,
  opcoesAposEc103: {
    carencia: boolean,
    aplicarFator: boolean,
    excluirCompetenciasAbaixoDoMinimo: boolean,
  },
  calcularAtividades?: boolean,
})

No construtor, DadosCalculo:

valida e converte datas string
consolida salários
detecta competências abaixo do mínimo após EC 103
injeta competenciasExcluidas, datasApuracao e sexo no HistoricoRgps
chama historico.calcularMapas()

Ou seja: construir DadosCalculo já dispara trabalho e mutação controlada no histórico.

Outras entidades frequentes

Entidade	Uso principal
`PeriodoContribuicao`	vínculo/período computável ou não computável
`PeriodoPcd`	marcação de deficiência por intervalo
`Salario` / `Salarios`	salários por competência
`Beneficio` / `Beneficios`	benefícios concedidos, pagos, derivados ou usados em evolução
`DadosAtrasados`	raiz do cálculo de atrasados
`Acrescimo` / `Acrescimos`	adicionais e acréscimos
`Descontoss`	descontos no cálculo de atrasados
`PeriodosBeneficioVantajoso`	janelas para desconto/acumulação em atrasados

Nomes legados relevantes

Alguns nomes reais do código são historicamente “estranhos”, mas precisam ser usados como estão:

CriterioSalarioMaternidade
Descontoss

Não “corrija” esses identificadores em código novo sem uma refatoração deliberada do pacote inteiro.

Fluxos canônicos de uso

Esta seção documenta os fluxos que de fato aparecem em prev-tc, prev-rvt e prev-atrasados.

1. Análise de tempo e elegibilidade

Fluxo-base:

const historico = new HistoricoRgps(periodosContribuicao, periodosPcd)

const dadosSegurado = new DadosSegurado({
  sexo,
  nascimento,
  tipo,
  historico,
  salarios: new Salarios(),
  beneficios: new Beneficios(),
})

const dadosCalculo = new DadosCalculo({
  dadosSegurado,
  der,
  dataApuracao: der,
  especie,
  marcoCarencia,
  requisitoB41Pcd,
  aplicarIrsmFev94: false,
  calcularRmiPcdComRegraAnterior: false,
  calcularRmiComRegraAnteriorNaEc103: false,
  criterioSalarioMaternidade: CriterioSalarioMaternidade.MEDIA_SIMPLES_DOZE_ULTIMOS,
  opcoesAposEc103: {
    carencia: true,
    aplicarFator: true,
    excluirCompetenciasAbaixoDoMinimo: true,
  },
})

const analise = new AnaliseBeneficios(dadosCalculo)
const resultado = analise.apurar()

Quando usar apurarGrupos():

quando a UI precisa avaliar todas as aposentadorias programadas plausíveis
quando a integração quer comparar Comum, Pcd e Ruricola

Comportamento importante:

se a espécie inicial não for programada, apurarGrupos() devolve só um grupo
se for programada, ele itera espécies e tipos, alterando temporariamente dadosSegurado.tipo e dadosCalculo.especie
o parâmetro desativarFiltros muda bastante o resultado; prev-tc usa true no worker principal

2. Cálculo de RMI

O uso real nas apps não é um método simples “calcular tudo e devolver array”. O fluxo canônico é:

const calculoRmi = new CalculoRmi(dadosCalculo, tabelaIndexadores?)

const linhas: ResultadoAposDescarte[] = []
const iterador = calculoRmi.calcular(tipoCalculo)

for (const linha of iterador) {
  linhas.push(linha)
}

const beneficiosMaisVantajosos = calculoRmi.beneficiosMaisVantajosos(linhas)

Esse padrão aparece em prev-tc em apps/prev-tc/app/composables/workers/calculoRmi.ts.

Contrato final mais usado pela UI:

interface ResultadoCalculoRmi {
  maiorRmi: number
  moeda: DadosMoeda
  linhasDescartes: ResultadoAposDescarte[]
  beneficiosMaisVantajosos: BeneficioAnalisadoComRmi[]
}

Casos relevantes:

RMI normal na DIB
RMI por alterações legislativas
RMI com descartes
RMI desvinculada, usando coeficienteInformado e tempoInformado*

3. Revisão da Vida Toda

CalculoRvt não é só uma variação pequena de CalculoRmi. Ele tem fluxo próprio, fortemente baseado em texto de carta/CNIS.

Contrato de entrada:

interface ParametrosRvt {
  nascimento: Date
  sexo: Sexo
  tipo: TipoSegurado
  encadeamento: TipoEncadeamentoAtualizacaoSalarios
  carta: string
  cnis?: string
  opcoesFiltroCnis?: OpcoesFiltroCnis
  modificadoresVinculos: Record<string, VinculoProps>
  modificadoresSalarios: Record<string, SalarioProps>
  aplicarIrsmFev94: boolean
  usarSalarioMinimo: boolean
  manterSalariosCarta: boolean
  desabilitarDivisorMinimo: boolean
  desabilitarFator: boolean
}

Fluxo:

const calculoRvt = new CalculoRvt(parametros, tabelaIndexadores?)
const resultado = calculoRvt.calcularRmiRevisada()

Contrato de saída:

interface ResultadoCalculoRvt {
  rmiRevisada: number
  indiceReposicao: number
  rmiRevisadaReajustada: number
  dadosReajuste: LinhaEvolucaoBeneficio[]
  diferenca: number
  direitoAdquirido: boolean
  dadosSalarioBeneficio: DadosSalarioBeneficio
  competenciaInicial: Date
  competenciaFinal: Date
  notasIndices: NotasCriterios
  notasMoedas: NotasCriterios
}

prev-rvt usa exatamente esse caminho, via worker, em apps/prev-rvt/app/composables/worker/calculoRvt.ts.

4. Evolução de benefício

Uso simples:

const linhas = calcularEvolucaoSimples({
  beneficio,
  servicoIndices,
  servicoLimites,
})

Uso completo:

const linhas = calcularEvolucaoCompleta({
  beneficio,
  servicoIndices,
  servicoLimites,
  servicoAdiantamentoAbono,
  inicio,
  termino,
  datasAdicionais,
})

Campos reais de LinhaEvolucaoBeneficio:

interface LinhaEvolucaoBeneficio {
  competencia: Date
  data: Date
  dataTermino?: Date
  valorAnterior: number
  indice?: number
  aplicouIndiceReposicao?: boolean
  baseReajuste: number
  valorAtualIntegral: number
  coeficiente: number
  valorComCoeficiente: number
  rateio: number
  valorComRateio: number
  proporcaoRenda: number
  valorComProporcao: number
  adicional25PorCentoIntegral: number
  adicional25PorCento: number
  valorFinal: number
  rendaComAdicional: number
  rendaParaAcumulacao: number
  computouAbono: boolean
  abono?: number
  proporcaoAbono?: number
  adiantamentoAbono?: boolean
  piso: number
  teto: number
}

Os testes de tests/Beneficio.spec.ts são a melhor referência para cenários de borda aqui.

5. Cálculo de atrasados

Fluxo-base:

const dadosAtrasados = new DadosAtrasados({
  liquidacao,
  beneficiosDevidos,
  beneficiosPagos,
  descontos,
  acrescimos,
  periodosBeneficioVantajoso,
})

const calculo = new CalculoAtrasados(dadosAtrasados, tabelaIndexadores?)
const resultado = calculo.calcular()

Nas apps, o worker monta antes um grafo de entidades:

Processo
Honorarios
Multa
Liquidacao
Beneficios
Descontoss
Acrescimos
PeriodosBeneficioVantajoso

Esse fluxo aparece em apps/prev-atrasados/app/composables/workers/calculoAtrasados.ts.

Módulos do pacote

`parametros`

Local: src/parametros/

Responsável por enums, constantes, rótulos e agrupamentos. Uma pasta por parâmetro (FormaContagem/, Sexo/, EspecieBeneficio/…): o enum no arquivo homônimo e cada auxiliar em módulo próprio, sem index.ts. As constantes de domínio que não são enum seguem a mesma forma: MarcosTemporais/marcosTemporais.ts (MARCOS_TEMPORAIS, as datas legislativas) e Pesos/pesos.ts (PESOS).

Nenhuma regra de cálculo deve nascer aqui, mas quase toda regra depende do que está aqui.

`entidades`

Local: src/entidades/

Camada de objetos do domínio. Além de armazenar dados, várias entidades validam, normalizam e precomputam estruturas.

`requisitos`

Local: src/requisitos/

Implementa os requisitos que compõem cada regra de concessão:

requisito-tempo
requisito-idade
requisito-carencia
requisito-pontos
requisito-pedagio
requisito-deficiencia
requisito-tempo-deficiencia
requisito-imediatidade

`analise-beneficios`

Local: src/analise-beneficios/

Responsável por:

gerar regras aplicáveis
apurar cumprimento
separar cumpridos, não cumpridos e possível reafirmação
calcular grupos “nas alterações”
montar blocos progressivos

Arquivos centrais:

AnaliseBeneficios.ts
RegrasConcessao.ts
Coeficiente.ts
Fundamento/ (o parâmetro Fundamento, seus rótulos e grupos)
obterRegras*.ts

Cada BeneficioAnalisado devolvido pela análise identifica a regra por dois campos: chaveFundamento (o nome do parâmetro, EC_103_ART_20, usado em filtros, agrupamentos e no cálculo de RMI por fundamento) e fundamento (a citação legal legível, EC 103, art. 20, para exibição e para as APIs).

`calculo-tc`

Local: src/calculo-tc/

Responsável por:

totalização
coincidência de períodos
carência
tempo especial
magistério
PcD
preponderância

É uma das áreas mais sensíveis para regressão.

`calculo-tc/serie-historica`

Local: src/calculo-tc/serie-historica/

A série histórica da Vida contributiva: gerarSerieHistorica(estado, progresso?) apura, competência a competência, do primeiro vínculo cadastrado até a data de apuração, o tempo simples e convertido, a carência, a carência de não programados (com a regra de perda e recuperação da qualidade de segurado, no requisito da espécie do grupo), a idade e a qualidade de segurado — contribuindo, em período de graça (com o término e as prorrogações) ou sem qualidade — com os mesmos totais e a mesma conta do demonstrativo, reapurados exatamente em cada data, sem interpolação — e os IDs dos vínculos e períodos de deficiência de cada competência, além da primeira filiação e dos marcos: perdas e reingressos de qualidade e a competência das 120 contribuições sem perda (só com o parâmetro do Tema 255/TNU ligado). Função pura, pensada para rodar em worker; carregamento sob demanda, cancelamento e cache são do consumidor.

`simulacao-por-totais`

Local: src/simulacao-por-totais/

A Simulação de Benefícios por Totais: quem tem o total de tempo apurado pelo INSS até a DER — e não os períodos que o compõem — informa esse total por marco temporal, acrescenta só os períodos que faltam (inteiros ou só pelo acréscimo da conversão) e vê se nasce direito a algum benefício. É uma metodologia alternativa, em pasta própria, que usa as classes do motor por trás sem alterá-las.

simularBeneficiosPorTotais(props) é a entrada: recebe segurado, DER, os totais absolutos até cada marco (tempo por modalidade em dias do ano de 360 e carência em contribuições; só o da DER é obrigatório) e os períodos adicionados, e devolve os grupos de benefícios programados avaliados, os marcos não informados, os totais informados normalizados e as regras não apuráveis.
Entre marcos vale o último total informado; só os períodos adicionados crescem. O total existe integralmente no marco, e o requisito que se cumpre graças a ele implementa-se ali.
Marco em branco não é um ponto da simulação: a regra que depende dele (pedágios, transições da EC 103, análises naquela data) é devolvida como não apurável, em vez de calculada com um valor que o usuário não informou.
Fora: não programadas, qualidade de segurado, RMI, atrasados e alçada — sem competências não há salário-de-benefício. O contrato de tempo das APIs não carrega a simulação.

`quadro-resumo`

Local: src/quadro-resumo/

O motor do Quadro Resumo: a lista dos benefícios que cumprem requisitos, com a RMI de cada fundamento e o valor da causa. Funções puras, pensadas para rodar em worker, sobre o motor sem alterá-lo.

analisarCandidatosQuadroResumo(estado) reapura os grupos na DER, na DER reafirmada e nas datas de possível reafirmação propostas pelo motor até a data de apuração, e devolve um candidato por fundamento cumprido e hipótese de RMI, com a origem da DIB.
calcularRmiCandidatoQuadroResumo roda a RMI com filtro de fundamento na DIB do candidato; calcularRendaCandidatoQuadroResumo reajusta essa RMI até a data de referência (a renda mensal); calcularEconomiaCandidatoQuadroResumo apura atrasados simples e, deles, o valor da causa (vencidas mais doze vincendas) com a alçada informativa. Lacuna de índices e dados faltantes voltam como pendência com o motivo, não como zero.
Fora: totalização de períodos, RMI desvinculada e demonstrativos.

`calculo-rmi`

Local: src/calculo-rmi/

Responsável por:

PBC
correção dos salários
divisor
salário de benefício
fator previdenciário
descartes
RVT

Classes principais:

CalculoRmi
CalculoRvt

`evolucao-beneficio`

Local: src/evolucao-beneficio/

Responsável por:

evolução simples
evolução completa
abono
rateio
proporcionalidade
aplicação de piso e teto

`calculo-atrasados`

Local: src/calculo-atrasados/

Responsável por:

consolidação de benefícios devidos/pagos
atualização
descontos EC 103
honorários
multa
outros débitos
vincendas
dados de alçada

concomitância — vive em `@fc/calculos-judiciais`

Não é módulo deste pacote. temConcomitancia e tirarConcomitancia mudaram para @fc/calculos-judiciais/concomitancia/* junto com a abstração de Periodo e Periodos, que os aplicam. O corte temporal da Lei 13.846/2019 continua sendo tratado no cálculo de RMI deste pacote.

`persistencia`

Local: src/persistencia/

Migra formatos serializados antigos de TC e atrasados. Cada cadeia é uma lista de Migrador (/arquivos-calc) encadeados por versão da app que gravou o arquivo: tc/migradores/migrador01…11 e atrasados/migradores/migrador01…04.

É muito usada pelas apps ao abrir arquivos .calc.

parametros-legados/ traduz os parâmetros que os .calc gravavam como ordinal (sexo: 1, formaContagem: 2, finalidade: 0…) para o vocabulário nominal atual: ORDINAIS_LEGADOS é a tabela congelada da numeração antiga, migrarParametroLegado a regra (valor válido passa; o valor legado — ordinal, ou o texto antigo, como nos parâmetros do RPPS — é traduzido; ausente fica ausente; desconhecido cai no padrão histórico dos campos obrigatórios ou segue intacto, para a validação de domínio acusar), e migrarSeguradoLegado, migrarPeriodoContribuicaoLegado, migrarPeriodoPcdLegado e migrarBeneficioLegado aplicam-na por objeto. VALORES_LEGADOS_INDICES é a tabela congelada dos textos que os .calc gravavam para os parâmetros de @fc/indices (indexador: 'inpc', taxa: 'taxaLegal', encadeamento: 'padrao'), e migrarIndexadorFlexivelLegado, migrarTaxaJurosFlexivelLegada e migrarConsectariosLegados traduzem o encadeamento configurado dos consectários. ORDINAIS_LEGADOS_JUDICIAIS faz o mesmo para os parâmetros de @fc/calculos-judiciais que os .calc de atrasados gravavam como ordinal (criterioDeducaoAlcada, honorarios.baseIncidencia, multa.baseIncidencia), aplicada por migrarHonorariosLegados e migrarMultaLegada. Os migradores tc/migrador11 (10.11.6 → atual) e atrasados/migrador04 (5.6.10 → atual) usam-nas; a cadeia do RPPS (/calculos-rpps, migrador02) e a do RVT (apps/prev-rvt) reutilizam os mesmos mapeadores pelo subpath @fc/calculos-rgps/persistencia/*.

A simulação por totais grava dados.simulacaoPorTotais no mesmo arquivo: campo opcional, sem migrador; arquivo anterior abre como sempre abriu.

`utilidades-apis`

Local: src/utilidades-apis/

Converte entre:

payloads simples de API/UI
entidades do domínio
resultados serializados

Submódulos principais:

tempo
rmi
atrasados
leitura-documentos

Em leitura-documentos, usarDadosCarta(...) adapta a Carta de Concessão para o contrato do cálculo de tempo, com DER/DIB e competências em ISO. usarDadosPap(...) reúne esse resultado aos de CNIS e RDCTC, preservando a ordem global dos documentos segmentados.

`documentos/filtros` e `documentos/plugins`

Responsáveis por interpretar e filtrar dados externos, especialmente CNIS, carta e dossiês.

Além dos filtros, documentos/plugins expõe os plugins RGPS consumidos pelo registro documentos/importacao/registroDocumentosPrevidenciarios (entregue ao importador genérico de @fc/parsers) e pelas apps. Exemplos:

PluginCnisCompleto, PluginCnisVinculos, PluginMeuINSS
PluginCartaConcessao, PluginCartaConcessaoNova
PluginHiscreSat
PluginPlanilhaGoogle
fonteIndicadoresCnis e obterIndicadorCnis

Efeitos colaterais e mutabilidade interna

Esta é uma seção crítica para quem vai mexer na biblioteca.

`DadosCalculo` não é puramente declarativo

Ao ser construído, ele:

converte datas string para Date
consolida salários
escreve em dadosSegurado.historico
chama historico.calcularMapas()

`AnaliseBeneficios.apurarGrupos()` muta e restaura estado

Durante a execução, ele altera temporariamente:

dadosSegurado.tipo
dadosCalculo.especie

e ao final restaura os valores anteriores.

Consequências:

não compartilhe a mesma instância em fluxos concorrentes
evite assumir que DadosCalculo é imutável
se for criar paralelização, clone ou reconstrua o grafo de entrada

`HistoricoRgps` acumula estado de descarte

Operações de descarte alteram mapas e listas internas. Isso é intencional para suportar cálculo iterativo de descartes na RMI.

Como as apps consomem a biblioteca

`prev-tc`

Usa a biblioteca como motor principal de:

análise de tempo
elegibilidade
RMI
abertura de arquivos .calc

Pontos importantes observados nos testes:

apurarGrupos(true) é o comportamento canônico do worker
o fluxo comum passa por desserialização de payload em entidade real
os testes afirmam fundamentos, totais, carência e marcos de alteração

Referências:

`prev-rvt`

Usa:

CalculoRvt
parsing de carta
parsing de CNIS
modificadores de vínculos e salários
validação de aplicação do fator previdenciário

Referências:

`prev-atrasados`

Usa:

evolução de benefícios
cálculo de atrasados
descontos
honorários
multa
períodos de benefício vantajoso

Referência:

apps/prev-atrasados/test/nuxt/atrasados.nuxt.spec.ts

Guia para novas regras

Nova espécie de benefício

Checklist mínimo:

adicionar no enum EspecieBeneficio
adicionar rótulo
revisar agrupamentos de espécie
criar ou adaptar obterRegras*.ts
registrar em RegrasConcessao
revisar impacto em coeficiente, fator, divisor, RVT e atrasados
revisar serializadores e migradores, se a espécie aparecer em payload salvo

Novo requisito

criar módulo em src/requisitos/requisito-<nome>/
implementar contrato RequisitoRgps
nada a exportar: o arquivo já sai por @fc/calculos-rgps/requisitos/*
plugar nas regras que o usam
verificar se o requisito participa de: paraPontosparaCoeficienteimplementadoEm análise postergada

Novo marco temporal

adicionar em MarcosTemporais
revisar paraContagemTempo quando aplicável
revisar RotulosNasAlteracoes, DatasApuracaoPorTipo e grupos progressivos quando fizer sentido

Mudança em regra existente

Sempre testar três camadas:

unidade do pacote
integração da app consumidora principal
cenário de direito adquirido ou regra anterior

Onde normalmente mexer

Mudança	Arquivos mais prováveis
nova regra de benefício	`analise-beneficios/obterRegras*.ts`
novo requisito	`requisitos/requisito-*/`
nova transição	`definirGruposProgressivas.ts`, `MarcosTemporais/marcosTemporais.ts`
mudança de coeficiente	`Coeficiente.ts`
mudança de fator	`FatorPrevidenciario.ts`, `fator-previdenciario/`
mudança de divisor/PBC	`calculo-rmi/`
mudança de evolução	`evolucao-beneficio/`
mudança de atrasados	`calculo-atrasados/`

Estratégia de testes

Preferência do repositório

Nesta biblioteca, testes mais valiosos tendem a afirmar invariantes semânticas, não snapshots amplos.

Exemplos de assertivas fortes:

fundamentos reconhecidos
tempo total apurado
carência
data de implementação
divisor
média
salário de benefício
aplicação ou não do fator
total devido em atrasados

Isso aparece tanto nos testes do pacote quanto nas apps consumidoras.

Paridade web/API a partir de `.calc`

O gerador específico do domínio fica em tests/paridade-calc/, não em @fc/test-utils. Rode primeiro em modo de inspeção:

bash

pnpm --filter @fc/calculos-rgps gerar-teste-paridade-calc -- --arquivo caminho/arquivo.calc --dry-run

O dry-run trata a saída como candidata e mostra um inventário de privacidade sem revelar valores. Ele sinaliza datas pessoais e textos livres para revisão, informa a canonização do timestamp obrigatório e bloqueia identificador, e-mail ou credencial residual. Depois de revisar os campos e o inventário, classifique a origem e gere:

bash

pnpm --filter @fc/calculos-rgps gerar-teste-paridade-calc -- --arquivo caminho/arquivo.calc --origem sintetica
# ou: --origem anonimizada-revisada

O gerador grava a fonte canônica em @fc/test-utils, reaproveita conteúdo idêntico em execuções posteriores e cria as specs de Tempo/RMI em prev-tc ou de Atrasados em prev-atrasados. Sanitização estrutural não é anonimização irreversível. A paridade dinâmica prova concordância entre superfícies; valores juridicamente validados pertencem a casos de ouro separados.

Quando usar snapshot

Snapshot pode ser útil para estruturas muito grandes e estáveis, mas não deve substituir assertivas de negócio sobre:

fundamento
datas
valores centrais
efeitos de marcos temporais

Cobertura mínima recomendada para regra nova

um cenário positivo
um cenário negativo
um cenário em marco anterior
um cenário em marco posterior
um cenário com integração real na app mais afetada

Armadilhas comuns

Não renomeie identificadores do domínio — o código usa PT-BR sem acento e os nomes refletem o contrato jurídico real.
DadosCalculo, DadosSegurado e HistoricoRgps não são imutáveis — são mutados internamente durante o fluxo de cálculo.
apurarGrupos() não é uma expansão simples — aplica filtros de concomitância, interseções e regras de marco temporal.
CalculoRmi usa generator assíncrono — não devolve resultado em uma única chamada síncrona.
Não há barrel: importe pelo subpath do arquivo que declara o símbolo. O wildcard do exports alcança também helpers internos, que não são API estável.
Ao alterar qualquer regra pós-marco temporal, preserve e teste explicitamente o comportamento pré-marco.
Antes de criar nova abstração, busque uso real nas apps (prev-tc, prev-rvt, prev-atrasados) — muitas decisões de design já estão cristalizadas lá.

Dependências externas

Pacote	O que fornece
`@fc/indices`	índices de correção, limites do RGPS, tábua de mortalidade, serviços de reajuste
`@fc/comum`	`Entidade`, `Competencia`, memoização e utilidades compartilhadas
`@fc/utils`	datas, aritmética previdenciária, predicados, truncamento e conversões
`@fc/calculos-judiciais`	suporte a liquidação judicial, honorários, multa e débitos
`@fc/parsers`	leitura de arquivos, núcleo genérico do parser por plugins e orquestração

@fc/calculos-rgps ​

Índice ​

Visão geral ​

Superfície pública do pacote ​

Como consumir ​

O que o package.json expõe ​

Superfície preferencial para entrada e saída ​

O que não deve ser tratado como API estável ​

Conceitos centrais do domínio ​

Espécies de benefício ​

Tipos de segurado ​

Marcos temporais ​

Unidade de tempo ​

Requisitos de concessão ​

Entidades principais ​

HistoricoRgps ​

DadosSegurado ​

DadosCalculo ​

Outras entidades frequentes ​

Nomes legados relevantes ​

Fluxos canônicos de uso ​

1. Análise de tempo e elegibilidade ​

2. Cálculo de RMI ​

3. Revisão da Vida Toda ​

4. Evolução de benefício ​

5. Cálculo de atrasados ​

Módulos do pacote ​

parametros ​

entidades ​

requisitos ​

analise-beneficios ​

calculo-tc ​

calculo-tc/serie-historica ​

simulacao-por-totais ​

quadro-resumo ​

calculo-rmi ​

evolucao-beneficio ​

calculo-atrasados ​

concomitância — vive em @fc/calculos-judiciais ​

persistencia ​

utilidades-apis ​

documentos/filtros e documentos/plugins ​

Efeitos colaterais e mutabilidade interna ​

DadosCalculo não é puramente declarativo ​

AnaliseBeneficios.apurarGrupos() muta e restaura estado ​

HistoricoRgps acumula estado de descarte ​

Como as apps consomem a biblioteca ​

prev-tc ​

prev-rvt ​

prev-atrasados ​

Guia para novas regras ​

Nova espécie de benefício ​

Novo requisito ​

Novo marco temporal ​

Mudança em regra existente ​

Onde normalmente mexer ​

Estratégia de testes ​

Preferência do repositório ​

Paridade web/API a partir de .calc ​

Quando usar snapshot ​

Cobertura mínima recomendada para regra nova ​

Armadilhas comuns ​

Dependências externas ​

Referências úteis ​

@fc/calculos-rgps

Índice

Visão geral

Superfície pública do pacote

Como consumir

O que o `package.json` expõe

Superfície preferencial para entrada e saída

O que não deve ser tratado como API estável

Conceitos centrais do domínio

Espécies de benefício

Tipos de segurado

Marcos temporais

Unidade de tempo

Requisitos de concessão

Entidades principais

`HistoricoRgps`

`DadosSegurado`

`DadosCalculo`

Outras entidades frequentes

Nomes legados relevantes

Fluxos canônicos de uso

1. Análise de tempo e elegibilidade

2. Cálculo de RMI

3. Revisão da Vida Toda

4. Evolução de benefício

5. Cálculo de atrasados

Módulos do pacote

`parametros`

`entidades`

`requisitos`

`analise-beneficios`

`calculo-tc`

`calculo-tc/serie-historica`

`simulacao-por-totais`

`quadro-resumo`

`calculo-rmi`

`evolucao-beneficio`

`calculo-atrasados`

concomitância — vive em `@fc/calculos-judiciais`

`persistencia`

`utilidades-apis`

`documentos/filtros` e `documentos/plugins`

Efeitos colaterais e mutabilidade interna

`DadosCalculo` não é puramente declarativo

`AnaliseBeneficios.apurarGrupos()` muta e restaura estado

`HistoricoRgps` acumula estado de descarte

Como as apps consomem a biblioteca

`prev-tc`

`prev-rvt`

`prev-atrasados`

Guia para novas regras

Nova espécie de benefício

Novo requisito

Novo marco temporal

Mudança em regra existente

Onde normalmente mexer

Estratégia de testes

Preferência do repositório

Paridade web/API a partir de `.calc`

Quando usar snapshot

Cobertura mínima recomendada para regra nova

Armadilhas comuns

Dependências externas

Referências úteis