[ziflex]

This pull request updates the Ferret Wire client and documentation to support and require the Unified API v1.0.0-alpha.20 runtime version in the Connect handshake. It introduces new methods for accessing the runtime version and plan parameters, ensures stricter validation of Connect responses, and updates related documentation for clarity and accuracy.

Protocol and API contract updates:

• Updated the target Unified API version to v1.0.0-alpha.20 throughout the documentation and codebase, replacing all references to alpha.19. [1] [2] [3] [4]
• The Connect handshake now requires a present runtime_version field (even if empty), and clarifies the distinction between protocol identity, runtime version, and host-supplied identity in both documentation and implementation. [1] [2] [3] [4]

Client implementation changes:

• Added runtimeVersion to the client struct, and a new Version(ctx context.Context) method on remoteRuntime to expose the immutable runtime version captured during Connect. [1] [2] [3]
• The client now strictly validates that runtime_version is present in Connect responses; missing this field causes handshake failure. [1] [2] [3]
• Updated the remotePlan.Params method to require a context and to validate/cancel appropriately, matching the new API contract.
• Added interface assertions for the new method signatures in tests.

Test and documentation updates:

• Updated all relevant tests, test servers, and documentation to include or check for the new runtime_version field in Connect responses. [1] [2] [3]
• Improved documentation for Plan.Params(ctx) and Runtime.Version(ctx), clarifying context requirements, snapshot semantics, and error handling. [1] [2] [3]

These changes ensure the client is compatible with the stricter requirements of the Unified API alpha.20 and provide more robust and explicit handling of runtime versioning and parameter metadata.

[Copilot]

Copilot review overview

🟡 Changes recommended

The protocol encoding, nested dependency graph, and deleted-document references contain unresolved issues.

Review effort: Balanced
Findings: 2 · 3

Open (5)

• Nested ferret module is not synchronized with gRPC v1.84.0 · New
• Opaque invalid UTF-8 versions fail protobuf response marshaling · New
• README links to deleted uapi-audit.md · New
• Architecture documentation links to deleted uapi-audit.md · New
• Client guide links to deleted uapi-audit.md · New

What changed in this PR

Updates Wire to Unified API alpha.20, adding runtime-version handshaking and context-aware metadata snapshots.

Changes:

• Adds required-present runtime_version handshake metadata and cached Runtime.Version.
• Updates Plan.Params context handling, cancellation, cleanup, tests, and benchmarks.
• Upgrades dependencies and revises protocol/client documentation.

Static review and final self-review completed; validation commands were not run.

File	Description
test/​integration/​README.md	Documents alpha.20 integration coverage.
test/​integration/​plan_test.go	Passes context to Params.
test/​integration/​metadata_test.go	Tests metadata caching and cancellation.
test/​integration/​harness/​runtime.go	Adds runtime-version spy behavior.
test/​integration/​harness/​plan.go	Makes metadata retrieval context-aware.
test/​integration/​api_contract_test.go	Expands metadata failure coverage.
test/​ferret/​runtime_test.go	Updates parameter calls.
test/​ferret/​README.md	Documents native metadata coverage.
test/​ferret/​metadata_test.go	Adds native metadata round trips.
test/​ferret/​harness_test.go	Supplies the native runtime version.
test/​ferret/​go.sum	Updates nested dependency checksums.
test/​ferret/​go.mod	Upgrades API and Ferret dependencies.
server/​runtime_spy_test.go	Implements Version on the spy.
server/​runtime_adapter_runtime_fake_test.go	Updates runtime contract fake.
server/​runtime_adapter_plan_fake_test.go	Updates context-aware plan fake.
server/​protocol_contract_test.go	Verifies runtime-version field presence.
server/​plan_spy_test.go	Updates plan spy signature.
server/​metadata_benchmark_test.go	Adds metadata-path benchmarks.
server/​internal/​grpcserver/​runtime_service.go	Retrieves and publishes runtime version.
server/​internal/​grpcserver/​runtime_service_test.go	Tests handshake metadata behavior.
server/​internal/​grpcserver/​plan_service_test.go	Tests metadata cancellation cleanup.
server/​internal/​grpcserver/​handshake.go	Clarifies host identity semantics.
server/​internal/​core/​runtime_spy_test.go	Implements runtime version contract.
server/​internal/​core/​plan_spy_test.go	Supports contextual metadata hooks.
server/​internal/​core/​component_boundary_test.go	Updates panic-boundary fixture.
server/​internal/​core/​compile.go	Passes allocation context to metadata.
server/​internal/​core/​compile_metadata_test.go	Tests cancellation and cleanup.
server/​internal/​core/​api.go	Adapts contextual Plan.Params.
server/​integration_test.go	Updates parameter invocation.
README.md	Documents alpha.20 behavior.
proto/​ferret/​wire/​v1/​runtime.proto	Adds runtime-version protocol field.
go.sum	Refreshes root dependency checksums.
go.mod	Upgrades API and gRPC dependencies.
gen/​ferret/​wire/​v1/​runtime.pb.go	Regenerates runtime bindings.
docs/​uapi-benchmarks.md	Removes historical benchmarks.
docs/​uapi-audit.md	Removes the alpha.19 audit.
docs/​protocol.md	Documents alpha.20 metadata semantics.
docs/​client.md	Documents cached metadata APIs.
docs/​architecture.md	Updates handshake architecture.
client/​runtime.go	Implements cached Version.
client/​runtime_contract_test.go	Asserts alpha.20 method signatures.
client/​remote_plan.go	Implements contextual cached Params.
client/​ownership_test.go	Adds version to test handshakes.
client/​lifecycle_test.go	Adds version to lifecycle fixtures.
client/​constructor_test.go	Rejects missing runtime versions.
client/​client.go	Validates and stores runtime version.
client/​client_test.go	Updates default handshake fixture.

Files not reviewed (1)

• gen/ferret/wire/v1/runtime.pb.go: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.