feat(types): publish all 15 meta-tool definitions; conformance sees enums and embedded shapes (ent#933)

[fabianocruz]

Core-side item of codespar/codespar-enterprise#933 (drift triplo between the runtime schema and @codespar/types). Built on the final runtime schemas at enterprise origin/main, after ent#932 / enterprise PR #943 landed.

What changed

1. @codespar/types aligned with the runtime

• codespar_pay method vocabulary is the ent#932 decision — pix, card, boleto, wire as a structured enum; sepa/usdc/ted are gone from the published surface (usdc redirects to codespar_crypto_pay in prose, per the runtime).
• recipient publishes the runtime's dual capability: a Pix key string OR a bank-account object for manual Pix cash-out (the capability the audit found homologated but unpublished), with a test pinning it.
• Managed-only extras (boleto_quote, the DICT claim lifecycle, expected_amount_minor) stay out of the shared baseline by design — they are the enterprise conformance test's allowlisted extras.

2. SHARED_META_TOOL_DEFINITIONS publishes the full 15-tool surface (was 3)
All fifteen agent-facing tools, including codespar_wallet (cash-in B.5) and codespar_kyc (B.1), which previously had no published definition at all. Property sets, per-property types, and required arrays mirror the runtime exactly, so the enterprise conformance loop passes over all 15 on the next types bump. Provider-routing prose was kept runtime-agnostic (definitions carry no routing).

3. Conformance now sees enums and embedded shapes — prose can no longer hide drift

• Closed vocabularies (rails, actions, channels, check types) moved from prose-only into structured enum arrays, mirrored into contract.enums; embedded object shapes (e.g. counterparty.country) into nested properties.
• New meta-tool-definition-conformance.ts:
  • definitionViolations() — contract/schema drift, enum well-formedness, enum-vs-prose agreement (every enum value must be visible in the property description), and a ghost-rail sweep (sepa/ted banned in all published prose; usdc only enum-owned or inside a codespar_crypto_pay redirect sentence).
  • sharedDefinitionConformanceReasons() — the cross-runtime comparator: the historical structural check plus shared-enum honoring (a runtime may extend a vocabulary, never shrink it, and its prose may not hide a shared value), embedded-shape matching, and a retired-rail sweep over runtime prose (this is what would have flagged the pre-#932 TED advertisement living in the runtime's recipient description).
• Tripwire tests reproduce the exact audit drift (including the old pix, card, usdc, boleto, sepa, wire prose) and prove each check fails on it, with positive controls for the allowed cases.

Verification

• packages/types: tsc --noEmit clean; vitest run 142/142.
• Full workspace: turbo run build 18/18, turbo run test 36/36.
• Enterprise runtime prose at origin/main swept for \bsepa\b/\bted\b: clean, so the comparator is adoptable enterprise-side without false positives.

Out of scope (left on ent#933)

• Enterprise bumping its @codespar/types pin and (optionally) adopting sharedDefinitionConformanceReasons in meta-tool-conformance.test.ts.
• pay.mdx docs (repo web) and the checkout coercer accepting card/boleto that die in no_eligible_providers (flagged in the ent#933 adendo).

Part of codespar/codespar-enterprise#933.

Generated with Claude Code
https://claude.ai/code/session_01BtvPxidmzsA22yoVJSWdba

[fabianocruz]

ATENÇÃO LANE DE REVISÃO: tratar como changes_needed. Revisão de alto nível (high effort) rodada em paralelo pela sessão dispatcher; achados 1-3 PROVADOS POR EXECUÇÃO contra os schemas do runtime em origin/main. Oito achados; o 4 e o 8 seguram o merge, o 1-3 esvaziam o propósito do PR.

BLOCKER 4 — contrato autocontraditório em recipient (meta-tool-definitions.ts:219): publicado como type string com descrição mandando passar OBJETO ('do not JSON-stringify it'). Cliente que valida schema (MCP estrito, OpenAI strict mode, gateway ajv) rejeita exatamente o uso correto — a capability manchete que este PR existe pra publicar morre nos clientes bem-comportados — e o check de igualdade de tipo do comparator agora OBRIGA todo runtime a manter a mentira. Fix: expressar a união de verdade (evoluir MetaToolInputProperty para oneOf/type múltiplo, com o runtime junto) ou publicar recipient como object com os campos nomeados e um campo alternativo para a forma string; o que não pode é type e prosa se contradizerem.

BLOCKER 8 — lockfile bumpa dependências alheias num PR de types (hono 4.12.32→4.13.5, fast-uri, ip-address, qs, nanoid 3.3.16→3.3.18). O precedente é o outage de 02/09 (nanoid, CI verde, 15h fora). Regenerar o lock sem os floating updates, ou separar num chore próprio revisado.

Esvaziam o propósito (provados por execução):

1. Comparator não varre usdc (só RETIRED_RAIL_TOKENS sepa/ted): runtime re-anunciando usdc no pay passa com zero reasons — metade exata do drift do ent#933. Incluir usdc na regra runtime-side (com o allowance do redirect pro crypto_pay).
2. Honra de enum gated em 'if (toolProp.enum)': runtime que DELETA o enum estruturado (regredindo ao estado prose-only que causou o ent#933) passa limpo. Flagrar runtime sem enum estruturado quando o contrato compartilhado declara um.
3. Visibilidade de prosa por substring: 'pixel-perfect cardholder boletos wired' satisfaz pix/card/boleto/wire. Usar o wordRegex \b que o próprio arquivo já tem.

Também aplicar: 5. duas fontes de verdade DENTRO do próprio packages/types (MANAGE_CONNECTIONS_CONTRACT diz closed set de 3 actions; a definition publica 7) sem teste cruzando META_TOOL_CONTRACTS x SHARED_META_TOOL_DEFINITIONS — adicionar o teste de consistência + corrigir o comentário; 6. checagem de shape aninhado é unidirecional (extra aninhado do runtime não é policiado — o drift publicado-sem-implementação se esconde um nível abaixo); 7. sentence splitter do usdc-redirect quebra em 'e.g.' (falso fail) e não quebra em '!'/'?' (falso pass) — usar segmentação melhor ou janela por token.

Positivo confirmado pra ninguém re-litigar: as 15 definitions passam definitionViolations com zero violações, o runtime de origin/main passa o comparator nas 15, sem colisão de exports, Python sem vocabulário espelhado, e sem version bump é o processo normal do repo.

Convertendo em DRAFT até 4 e 8 saírem; ao resolver, gh pr ready 126 e fluxo normal.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BtvPxidmzsA22yoVJSWdba

[fabianocruz]

Revisão adversarial (protocolo): APROVADO com um fix adicionado na branch.

Verificado contra o runtime em codespar-enterprise origin/main:

• Os 15 nomes, property sets, tipos por propriedade, required arrays e shapes embutidos conferem com COMMERCE_META_TOOLS — rodei sharedDefinitionConformanceReasons sobre o array real do runtime: ALL 15 CONFORM, com apenas os extras managed-only do pay (boleto_quote/expected_amount_minor + lifecycle DICT) em allowlist.
• Sweep \bsepa\b/\bted\b na prosa do runtime: limpo (comparator adotável sem falso positivo).
• Tripwires reproduzem o drift do audit e cada check falha nele; controles positivos cobrem os casos permitidos.

Fix adicionado (commit 6d050b3): os wire-shape types do MESMO pacote contradiziam as definições recém-publicadas — PayArgs.method anunciava "wallet" (vocabulário do charge, nunca um rail do pay) e escondia "wire"; PayArgs.recipient era string-only (sem o objeto bank-account do cash-out manual); KycArgs.check_type escondia onboarding/onboarding-business/status; ChargeArgs/ChargeMethod escondiam "wallet". Alinhados + testes de pin bidirecionais (Record<Union, true> vs enum publicado) para pay/charge/kyc/ship/ledger/issue/shop.

CI: ci/gitleaks/smoke/3 validates verdes. Os 4 validate-example vermelhos são ambientais e pré-existentes — provado pelo PR de controle #127 (empty commit, tree idêntico ao main): os MESMOS 4 jobs falham no tree de main hoje (imagem externa ghcr.io/codespar/codespar:main não fica saudável), e o ci de main também falha no audit que o bump de lockfile deste PR conserta. Mergeando conforme o protocolo.