fix(types): recipient publica a união que o contrato sempre exigiu (core#128)

[fabianocruz]

Closes #128.

codespar_pay.recipient era publicado como type: "string" e a própria descrição mandava passar um OBJETO de conta bancária — com a frase "the tool-call argument type, not this schema's declared string type, is what determines routing". O schema contradizia a si mesmo, por escrito.

Prosa não conserta schema. Um cliente que ENFORÇA o declarado — MCP com validação estrita, OpenAI strict tool mode, um gateway rodando ajv — rejeita o objeto antes de sair da máquina, ou coage para string, que a mesma descrição proíbe. O Pix cash-out MANUAL e o destino do method=ted ficam indisponíveis exatamente nos clientes bem-comportados.

Medido antes de mexer

No documento que a produção serve, hoje:

GET /v1/meta-tools.json
  codespar_pay.recipient   type=string   enum=None
  codespar_pay.action      enum=[boleto_quote, dda_list_due, dda_status, dda_subscribe,
                                 dda_unsubscribe, dict_claim_cancel, ... 18 ações]

A segunda linha é uma boa notícia que eu não procurava: o enum de action já foi ampliado. A metade "ações vivas que o schema não anuncia" do levantamento de 08/09 fechou antes. Sobrou esta.

A união vai para o schema

MetaToolInputProperty ganha anyOf, e type vira opcional — exatamente um dos dois está presente. anyOf e não array de tipos porque é o que os modos estritos aceitam na prática. O ramo de objeto declara bank, account, branch, tax_id, name e account_type campo a campo, onde antes havia uma frase entre chaves.

O trabalho de verdade foi ensinar a conformidade a enxergar união

• O caminhante de prosa e o de vocabulário descem nos ramos. Sem isso, a descrição do ramo de conta bancária ficaria invisível para todo portão de prosa — a classe que esses portões existem para pegar, criada por mim.
• O comparador entre runtimes compara assinatura de forma, não o campo type cru. Com os dois lados em anyOf, comparar type daria undefined dos dois lados e passaria calado.

Três controles, e um achou defeito meu

controle	resultado
runtime achata a união de volta para um tipo	reprova, nomeando as duas formas
ramos escritos em outra ordem	passa — união é conjunto, e portão que reprova reordenação é portão que se aprende a ignorar
runtime TIRA um campo do ramo de objeto	passava calado

O terceiro era buraco real: o comparador só lia properties do nível de cima, e os campos de uma união moram um nível abaixo, dentro dos ramos. Mesmo buraco, mais fundo. Fechado na mesma mudança.

E o teste que escrevi para a CLI pegou outro defeito meu: uma chave Pix de 11 dígitos (um CPF) é JSON válido, então o parse cru transformava a chave no número 12345678901. O parse agora só vale quando cai num ramo estruturado.

FICA DE FORA — e é metade do conserto

O codespar-enterprise publica o seu próprio input_schema em packages/api/src/meta-tools.ts:136, e é dele que sai o /v1/meta-tools.json que os clientes leem. Enquanto ele não subir a mesma união, o documento servido continua dizendo type: "string".

Esse PR tem duas dependências, nesta ordem: este aqui publicado, e o pino de @codespar/types no enterprise — hoje em 0.10.14, três versões atrás do que está no npm — subindo junto, porque o teste de conformidade de lá compara contra as definições publicadas.

Versões

types minor (o type opcional é quebra de tipo para quem o lia como string, e a forma de recipient muda), sdk minor porque reexporta o contrato, cli minor pela mudança de comportamento do --arg, e os 13 adapters em patch só pela faixa de peer. 18 suítes verdes, typecheck limpo, portão de deriva sem deriva nova.

🤖 Generated with Claude Code