Resolve tool schema $refs before MLX chat template rendering

[Adi2K]

Any tool with a nested-object parameter currently fails every Gemma request with runtime("upper filter requires string"), before a token is generated.

GenerationSchema encodes a nested tool parameter as a bare $ref into $defs, and withResolvedRoot() resolves only the top-level root reference, so the nested part reaches the chat template as a typeless stub. For a tool search_records(filter: { q: String }):

// before — Gemma's format_parameters does `value['type'] | upper`, which throws
"properties": { "filter": { "$ref": "#/$defs/Filter" } }

// after — inlined, so the template renders and the model can target filter.q
"properties": { "filter": { "type": "object", "properties": { "q": { "type": "string" } } } }

Cloud backends accept $ref because they dereference server-side; on-device templates dereference nothing, so the MLX tool path has to resolve before rendering. convertToolToMLXSpec now runs normalizeToolSchemaTypes(resolveToolSchemaRefs(_:)). Draft-07 definitions resolve alongside $defs, since Pydantic v1 and many MCP servers emit those.

Expansion is bounded, because these schemas can come from third-party MCP servers: cycles, unfollowable pointers, and anything past the depth (64) or node (5,000) cap collapse to {"type": "string"} rather than throwing. The node cap is the load-bearing one — a definition referenced twice by one parent is a DAG rather than a cycle, so a cycle guard alone still re-inlines every shared subtree, and a 2 KB 22-level diamond expands to ~21M nodes. llama.cpp hits the same wall and sidesteps it by emitting a named grammar rule per $ref, which isn't available here since a template needs a literal schema tree.

Resolution walks every subschema slot (including additionalProperties, prefixItems, patternProperties and tuple-form items, which Pydantic emits for Dict[str, Model] and Tuple[...] fields), and a residual sweep guarantees no $ref survives anywhere else — dropping the definition table while leaving a pointer behind would be worse than not resolving at all. Slots carrying instance data rather than subschemas (const, default, enum, examples) pass through untouched, since a $ref key there is a literal value.

Well-formed schemas pass through byte-identical, and cloud backends are untouched.

Two things I'd value your opinion on:

• Degradation is silent. A schema past the bounds is flattened with no diagnostic, which matches the existing dangling-ref behavior. I didn't add logging because the package has none today, but I'm happy to add a counter or a strict mode if you'd want one.
• Unresolvable refs become {"type": "string"}, which asserts a type that may not be true. A permissive {} would be more honest, but templates that index value['type'] need the key present.