companies: pendências da migração v2 — enumeração bloqueada por 500 no cursor; tightening de create/update adiado

[andrenfe]

Contexto

A v5.2.0 corrigiu a paginação v1 de companies (1-based + teto de pageCount) e adicionou listV2() (API v2, cursor) com list() v1 deprecado — ver CHANGELOG e os OpenSpec changes fix-companies-pagination-1-based / migrate-companies-to-v2 no PR da release.

Esta issue rastreia o que ficou aberto após o merge.

1. 🔴 Fase 2 da migração cancelada: listAll()/listIterator() continuam no v1

O gate de paridade v1×v2 (probe ao vivo, 2026-07-14) reprovou por dois motivos independentes:

• Enumeração completa via v2 quebra: GET api.nfse.io/v2/companies responde 500 determinístico para qualquer janela contendo um registro específico ("registro-veneno"), até com limit=1. Repro (conta de teste, 352 empresas):

  GET https://api.nfse.io/v2/companies?limit=1&startingAfter=3450bc6208cb4b97a1a3616b89f77a4b → 500
  

  Formato do id do cursor não é a causa (ObjectId 24-hex e GUID 32-hex funcionam). Bug reportado ao time de backend.
• Projeções divergem: só o v1 tem specialTaxRegime, legalNature, rps*, issRate, environment, fiscalStatus, certificate…; só o v2 tem stateTaxes, municipalTaxes, type, version; e municipalTaxNumber retorna valores diferentes na mesma empresa (dado possivelmente dessincronizado — também com o backend).

Ação futura: quando o backend corrigir o 500 (e o shape for decidido), repontar listAll/listIterator para o cursor v2 (hasMore) — sem mudança de assinatura. Detalhes na Fase 2 do change migrate-companies-to-v2.

2. 🟠 Tightening das assinaturas de create/update (adiado por política de SemVer)

create(data: Omit<Company,…>) e update(id, data: Partial<Company>) aceitam payloads que a API rejeita com 400 (faltam taxRegime/address obrigatórios) — e o update é PUT (substituição total). Na v5.2.0 os JSDocs/exemplos foram corrigidos e um teste de alinhamento pina o contrato (tests/types/company-write-alignment.test-d.ts), mas as assinaturas continuam frouxas.

Ação futura: trocar para os schemas estritos já exportados (CreateCompanyResourceItem/UpdateCompanyResourceItem) — na próxima major orgânica OU junto com a migração de CRUD para o v2, uma vez só.

3. 🟡 Dependências de spec (origem nfe/docs)

Os fixes de spec da v5.2.0 (minimum: 1 no pageIndex, maximum: 50 no pageCount de /v1/companies) foram feitos na cópia local — o re-sync de specs regride se a origem não absorver. A spec contribuintes-v2 também omite hasMore na resposta do list (a API real envia; o SDK tipa à mão por cima).

---

Contratos provados ao vivo em 2026-07-13/14; evidências e método nos tasks.md dos dois changes OpenSpec.