feat(cli): add hinzu api-diff for cross-language public-surface conformance

[zmaril]

What

A new hinzu api-diff subcommand that takes two hinzu api reports — a SOURCE package's public API and a TARGET package's public API (typically different languages) — and emits a stable JSON conformance grade. Each source public item is classified matched / signatureMismatch / missing, plus target-only items surfaced as extra, with an overall conformance score and a per-kind breakdown. It is advisory and evidence-carrying (every pairing cites source and target id/file/line), the same ethos as port-diff.

Why

It completes the original intent behind hinzu api: knowing both the public API a port must match AND how far a target language's surface has gotten. It composes with port-diff — port-diff bands file progress by graph structure; api-diff grades the actual public-surface conformance. They're complementary, not redundant.

How

A pure hinzu_core::apidiff::build_api_diff(source, target, rules) (no I/O — passes the self-check pure-region policy) does name+kind matching and structural shape comparison; the CLI reads the two JSON reports and the port config.

• It reuses port-diff's exact naming rules (kebab→snake files, camelCase→snake_case fns, PascalCase types kept, SCREAMING consts kept) plus field-name normalization, so convention renames don't false-miss.
• Kind-equivalence classes (Callable / Type / Const / Namespace) let TS interface↔Rust struct and function↔method match across languages; cross-kind pairings are noted.
• Classification is driven by structural facts that survive cross-language rendering (param arity, field-name sets, variant-name sets). Rendered type strings are compared only within a language and are advisory across languages — a signatureMismatch is a signal, not a proof.

Validated on the real pi→pidgin pair (the ai package)

Source pi ai (TypeScript) vs target pidgin ai (Rust). Grade: conformance 0.32 — matched 124, missing 206, signatureMismatch 58, extra 527 (388 source public items).

Spot-checked examples verified against pidgin source:

• matched — calculateCost→calculate_cost; AssistantMessage fields align snake_case.
• signatureMismatch — completeSimple TS 3 params → Rust 4, splitting out Option<&AbortSignal>.
• missing — anthropicProvider factory fns (pidgin uses registries); ANTHROPIC_MODELS const (pidgin exposes via methods) — genuinely unported as that shape, grep-confirmed.
• extra — 527 target-only, mostly Rust inherent methods a structurally-typed TS module never declares.

During validation two convention false-misses were caught and fixed (field-name normalization; PascalCase function names now snake-fold).

Honest limitations

• Cross-language type strings are advisory, not classification drivers.
• Optional/overloaded params make arity approximate (hinzu api captures only the first overload).
• A concept ported to a different shape reads as missing.

Docs

• notes/api-diff.md — schema, matching + naming rules + kind-equivalence table, composition with port-diff, the pi→pidgin result.
• notes/api.md — links the follow-up.
• notes/port-pi-pidgin.toml — the atilla→pidgin-renamed port config.

Gate (all green locally)

• cargo fmt --all --check
• cargo clippy --all-targets -- -D warnings
• cargo test — 93 core (incl. 8 new apidiff) + lsp/dbsp/integration, 0 failed
• hinzu check self-check pure-region policy
• straitjacket v0.2.3 on a clean clone — 0 findings in 123 files
• codespell clean

It's a DRAFT — not for merge without review.