Stabilize public API, SDK, and extension contracts for beta

[drew]

Summary

Before the OpenShell Beta release, review and stabilize every public API, SDK, and extension contract. This is the final planned opportunity to make coordinated breaking changes before those surfaces are treated as stable.

The outcome should be a coherent, documented public contract that we are comfortable supporting through the beta lifecycle, together with clear rules and tooling for future compatibility and deprecation.

Parent roadmap: #1904.

Scope

Contract inventory and review

Create an inventory of all externally consumed contracts and identify an owner for each surface, including:

• Gateway gRPC services, messages, methods, status/error behavior, and transport metadata
• SDK APIs and generated client types across supported languages
• CLI- or configuration-facing representations derived from public API types
• Extension contracts, including gateway interceptors, supervisor middleware, compute drivers, credential drivers, and other supported extension points
• Serialization formats, enum behavior, identifiers, pagination, optionality/defaults, version negotiation, and capability discovery

For every contract, review naming, structure, semantics, consistency, extensibility, error handling, and compatibility risks. Explicitly classify each surface as public/stable, public/experimental, or internal.

Final pre-beta breaking-change pass

• Resolve the contract changes identified by the review as one coordinated pre-beta stabilization effort.
• Remove or replace APIs that we do not intend to support during beta.
• Align equivalent concepts and behaviors across gRPC, SDKs, CLI/configuration, and extension surfaces.
• Regenerate affected clients and fixtures and update all in-repository consumers.
• Publish migration notes that enumerate every breaking change and show consumers how to update.
• Establish a cutoff after which public beta contracts follow the compatibility policy below.

gRPC service documentation

Provide user-facing documentation for OpenShell's public gRPC services. The documentation should be generated from, or automatically validated against, the protobuf definitions so it cannot silently drift.

At minimum, document:

• Services, RPC methods, request and response messages, and fields
• Field semantics, required/optional behavior, defaults, validation rules, and lifecycle constraints
• Authentication and transport metadata
• Error model and status codes
• Pagination, idempotency, retries, timeouts, and streaming behavior where applicable
• Stability classification and version/deprecation status

Breaking-change and backwards-compatibility policy

Document and adopt guidance that defines:

• What counts as a breaking change for protobuf/gRPC, SDKs, CLI/configuration, and extensions
• Which surfaces receive compatibility guarantees and which remain experimental
• The versioning strategy for APIs, SDKs, schemas, and extension protocols
• The review and approval process for proposed breaking changes
• Deprecation annotations, communication requirements, migration guides, and minimum support windows
• How additive changes, removals, renames, enum evolution, field reuse, and behavioral changes are handled
• Rules for protobuf field/tag reservation and unknown-field/unknown-enum behavior
• How servers and clients negotiate or detect supported capabilities and versions
• The supported client/server compatibility matrix and how long older clients remain supported
• Required automated checks, compatibility tests, and release gates
• The emergency exception process for security or correctness issues

Deliverables

• A reviewed inventory of every public API, SDK, configuration, and extension contract, with owners and stability classifications
• Approved decisions for the final pre-beta contract formats and semantics
• The final coordinated set of breaking changes implemented across protobuf definitions, SDKs, extensions, and in-repository consumers
• Migration notes covering every beta-boundary breaking change
• Published gRPC reference documentation generated from or validated against protobuf definitions
• Published API stability, versioning, deprecation, and backwards-compatibility policy
• A documented client/server and extension compatibility matrix
• Automated compatibility checks and release gates for protected public contracts

Definition of Done

• API, SDK, and extension owners have signed off on the stabilized contracts.
• Each public surface has an explicit stability designation and owner.
• No known pre-beta breaking contract changes remain unaddressed or undocumented.
• All supported SDKs and in-repository consumers work against the stabilized API definitions.
• Public gRPC documentation is complete, published, and checked for drift in CI.
• Compatibility and deprecation guidance is published and linked from contributor/release documentation.
• CI detects prohibited protobuf/schema changes and exercises the supported compatibility matrix.
• Beta release notes clearly announce the stability boundary and link to migration guidance.

Non-goals

• Guaranteeing indefinite compatibility for contracts explicitly designated experimental or internal
• Adding new product capabilities unrelated to stabilizing existing public contracts
• Preserving accidental or undocumented implementation details as supported APIs