Make canonical tools provider-agnostic and keep their identity

[rokoss21]

Prerequisite for ROADMAP item 3, found while starting the first adapter.

Two problems in the object the adapter translates

The canonical payload carried OpenAI's envelope. The struct in the renderer was literally documented as "Tool definition following OpenAI function calling format" — inside the object §18.1 defines as provider-agnostic and §18 positions as the boundary between FACET and any vendor. An adapter written against that isn't translating a neutral form; it's reshaping one vendor's form into another's.

The tool name was the bare function name. Two interfaces each declaring get:

@interface WeatherAPI
  fn get(city: string) -> string (effect="read")

@interface StockAPI
  fn get(ticker: string) -> string (effect="read")

produced two entries in canonical.tools both named get. Policy matches on the canonical Interface.fn form (§16.2.6), so with WeatherAPI.get allowed and StockAPI.get denied, an incoming get call has no honest mapping — and the allow rule would answer for the call the deny rule was written for.

Change

canonical.tools entries are now:

{ "name": "WeatherAPI.get", "description": "...", "parameters": { "type": "object", ... } }

Providers that restrict tool names to [A-Za-z0-9_-] — which is most of them — must mangle this and map back before the guard sees the call. That is an adapter obligation, and it is only expressible because the canonical name now survives to the boundary.

Breaking for anything parsing canonical.tools; recorded as such in the changelog. Updated in scripts/spec_matrix_examples.sh and the renderer tests.

Verification

• new regression test builds the colliding-interfaces contract and asserts both WeatherAPI.get and StockAPI.get appear, in Resolved Source Form order, with no vendor wrapper
• 490 tests, smoke, matrix, doc-examples all green; coverage 57 → 60

🤖 Generated with Claude Code