Protocol Stability Policy

Aster capability protocols are SDK promises. They are not string labels and not transport versions: each protocol module carries an ID, semver version, compatibility range, operation schemas, settings schema, authority statement, and conformance expectations.

This policy applies to @aster/services/protocols. Gate contracts and wire protocols have their own versioning rules.

Version Identity

Protocol versions use plain major.minor.patch semver. A typed protocol ref carries:

{
  id: "aster.evidence-search",
  version: "1.0.0",
  range: "^1.0.0",
}

The S105 mechanical rule is intentionally small: ^x.y.z accepts registry versions with the same major and a version greater than or equal to the floor. It rejects older minors/patches and every different major.

Additive Changes

An additive change may land in the same major when existing conforming providers and consumers keep working without runtime fallback code.

Examples:

• Clarifying summaries, docs, examples, or conformance wording.
• Loosening a request schema while preserving existing behavior.
• Adding an optional settings field with a default that preserves current behavior.
• Adding an optional response field only when existing consumers tolerate it and the field is not required for existing semantics.
• Adding conformance coverage for behavior every already-conforming provider must satisfy.

Breaking Changes

A breaking change requires a new major. Do not land it in place.

Examples:

• Removing, renaming, or changing the meaning of an operation.
• Adding a required request, response, or settings field.
• Narrowing a request or response schema.
• Changing defaults or side effects in a way that changes existing behavior.
• Adding declared authority, provider rights, or isolation demands.
• Adding a new required operation to a protocol providers must implement.
• Tightening conformance in a way that rejects existing conforming providers.

Deprecation

Deprecation is a support promise, not compatibility code.

A deprecated operation, field, or major can remain documented and supported until the policy says it is removed, but the runtime must not grow dual readers, fallback decoders, or “accept both shapes” branches. A major that changes shape is a distinct protocol major with its own schemas, refs, requirements, providers, and conformance kit.

Removal requires a zero-binding query once plan/apply and binding history can answer it. Until then, a deprecated major remains explicitly present or the breaking change does not land.

Provider And Consumer Ranges

Providers declare the protocol ref they implement. Consumers declare the range they require through space requirements, bundle dependencies, or generated provider metadata.

The resolver accepts a provider only when the provider’s implemented version and the consumer’s required range satisfy the S105 range rule. It fails closed on unknown protocols, incompatible majors, or versions below the declared floor.

Worked Deprecation Example

Suppose aster.evidence-search v1 has:

resetIndex({ generation: number })

and the platform wants a clearer v2 request:

resetIndex({ generation: number, reason: "rebuild" | "provider_switch" })

The allowed cycle is:

1. Document the v1 request as deprecated for v1 consumers.
2. Add a v2 Evidence Search protocol major with the new request schema and its own conformance kit.
3. Migrate providers by implementing v2 directly.
4. Migrate consumers by changing their requirement range to the v2 major and emitting only the v2 request shape.
5. Remove v1 only after the zero-binding query proves no declarations or installed bundles still require it.

The forbidden cycle is adding a runtime decoder that accepts both reset shapes under one protocol entry.

Support Matrix

Surface	Policy
Current major	Supported for all conforming providers and consumers.
Deprecated current-major field or operation	Supported until the documented removal major; no new runtime dual-shape handling.
Prior major	Supported only as its own protocol major while bindings still exist.
Future major	Rejected by current resolvers until the registry contains that major.
Unknown protocol ID	Rejected.