API update

[ziflex]

This pull request introduces two new metadata retrieval methods to the API: Plan.Params(ctx) and Runtime.Version(ctx). Both methods now require a non-nil context and may involve remote I/O, with clear semantics for cancellation and error handling. Additionally, a new opaque Version type is defined for version reporting, and the documentation and tests are updated accordingly.

API Additions and Changes:

• Added Plan.Params(ctx context.Context) ([]string, error) to the Plan interface, replacing the old parameterless Params method. This new method requires a non-nil context, supports cancellation, and distinguishes between empty parameter lists and metadata retrieval errors. [1] [2] [3] [4]
• Added Runtime.Version(ctx context.Context) (Version, error) to the Runtime interface. This method reports the runtime's version (as an opaque value), requires a non-nil context, and supports cancellation. [1] [2] [3] [4]

Type and Implementation Updates:

• Introduced a new Version type as an opaque string-backed value, with a String() method that preserves the original value.
• Updated test fixtures and contract tests to implement and validate the new Params(ctx) and Version(ctx) methods, ensuring context-awareness and error handling. [1] [2] [3] [4]

Documentation Improvements:

• Expanded documentation in README.md and doc.go to clarify the semantics, error handling, and context requirements for the new metadata methods. [1] [2] [3] [4] [5]

These changes make the API more robust and future-proof by standardizing metadata retrieval and version reporting with clear context and error semantics.

[Copilot]

Copilot review overview

🟢 Approval recommended

The API contracts, fixtures, tests, and documentation are consistently updated.

Review effort: Balanced
Findings: None

What changed in this PR

Adds context-aware metadata retrieval for plans and runtimes.

Changes:

• Updates Plan.Params to accept a context.
• Adds Runtime.Version and the opaque Version type.
• Updates documentation, contract tests, and fixtures.

File	Description
version.go	Defines Version and its string representation.
version_test.go	Tests preservation of opaque version values.
runtime.go	Adds context-aware version retrieval.
runtime_contract_test.go	Verifies the new runtime method signature.
plan.go	Makes parameter retrieval context-aware.
plan_contract_test.go	Verifies the updated plan method signature.
output_contract_fixture_test.go	Updates the runtime test fixture.
README.md	Documents metadata retrieval semantics.
doc.go	Extends package-level API documentation.

---

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