fix: resolve entity local references before inlining (#72)

[damaz91]

Description

When preprocessing UCP schemas, entity_def (ucp.json#/$defs/entity) is extracted and inlined into schemas that compose it (capability.json, service.json, and payment_handler.json).

Prior to this fix, same-document references within the entity definition (specifically "version": { "$ref": "#/$defs/version" }) were copied verbatim into the target schemas. Because the destination schemas do not define $defs/version, these pointers failed to resolve against the destination document, leading to:

1. Preprocessed output with dangling local $ref pointers to #/$defs/version.
2. Eager JSON schema validators failing with referencing.exceptions.PointerToNowhere: '/$defs/version' does not exist.
3. datamodel-codegen falling back to Version = TypeAliasType("Version", Any), leaving version unvalidated across capability.py, service.py, and payment_handler.py.

This change adds resolve_local_refs to recursively resolve and inline local $ref pointers in schema fragments against their origin document at extraction time. The entity definition is thus made self-contained before being inlined into consuming schemas, without introducing document-level reference cycles or modifying the external reference graph.

Category (Required)

Please select one or more categories that apply to this change.

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

Fixes #72

Checklist

• I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Screenshots / Logs (if applicable)

N/A

[damaz91]

@chaz8081 @vishkaty PTAL, thanks!

[vishkaty]

Verified at cbf46f8: regenerated from the pinned 2026-04-08 spec and re-ran the probes from #72, and all 21 entity-derived version fields across capability, service, and payment_handler now reject bad values with string_pattern_mismatch while valid 2026-04-08 baselines pass. Local suite is green (85 tests, up from 79 on main), regeneration byte-reproduces the committed models, and the only generated deltas beyond version are reordered but identical Config and Extends alias blocks.