Versioning

Harmovela Versioning

> Status: draft. Part of the Harmovela 0.2 core specification. > Category: core

Purpose

Define how Harmovela versions protocol assets and how implementations negotiate compatibility.

Migration decisions for legacy public identifiers are tracked in the compatibility matrix. That matrix is decision input only and does not authorize identifier changes.

Versioned Assets

Harmovela versions four distinct assets independently:

Asset	Version Field	Example	Scope	Category
Protocol envelope	`spec_version`	`"0.2"`	Envelope field set, required fields, semantic rules	core
Event type families	Event type registry	—	Standard event type names and semantics	core
Payload schemas	`payload_schema` (URI)	`https://schemas.axisrobo.com/tool.call.progress.v1.json`	Per-event payload structure	profile
Transport bindings	Transport spec	—	stdio framing, WebSocket subprotocol, etc.	profile

Core assets are required by every conformant implementation. Profile assets may be adopted independently and carry their own conformance requirements.

Protocol Envelope Versioning

Format

The spec_version field uses MAJOR.MINOR format (e.g., "0.2").

Compatibility Rules

Within a minor version:

Existing required envelope fields must not be removed.
Existing field semantics must not change.
New optional fields may be added.
Existing optional fields may become required in the next minor version.

Across major versions:

Required fields may change.
Envelope structure may differ.
Implementations must reject envelopes with an unsupported major version with unsupported_version.

Negotiation

During session initialization (session.opened / session.ready), peers declare their supported protocol version via capabilities.spec_version. Both sides must agree on a version before the session becomes ready. A peer that cannot negotiate a compatible version should send session.error with code unsupported_version.

Event Type Registry Versioning

The standard event type registry (the set of type string values defined in design/protocol/) follows these rules:

New event types may be added in any minor version.
Existing event type names must not be removed within a minor version.
Existing event type semantics must not change in incompatible ways within a minor version.
Implementations must reject unknown event types with event.rejected (code unknown_event_type). This is an intentional divergence from the earlier draft that suggested opaque forwarding.

Payload Schema Versioning

Each event type family may define one or more payload schemas. A payload schema is identified by a URI in the payload_schema field:

{
  "type": "memory.fact.added",
  "payload_schema": "https://schemas.axisrobo.com/memory.fact.added.v1.json",
  "payload": { ... }
}

Rules:

Payload schemas version independently of the protocol envelope.
A payload schema URI should embed the schema version (e.g., ...v1, ...v2).
Changing a payload schema in a backward-incompatible way requires a new URI.
Implementations may validate payloads against schemas when payload_schema is present.

Transport Binding Versioning

Each transport binding (stdio, WebSocket, HTTP SSE, etc.) versions independently of the protocol envelope. A transport binding specification defines:

Framing rules (e.g., newline-delimited JSON for stdio)
Connection lifecycle
Error handling for transport-level failures
Subprotocol identifiers (e.g., WebSocket subprotocol names)

Current transport binding documents: see design/protocol/transport-stdio.md, design/protocol/transport-websocket.md, design/protocol/transport-sse.md, design/protocol/transport-grpc.md, design/protocol/transport-nats.md, design/protocol/transport-kafka.md, design/protocol/transport-redis-streams.md. Transports are profile assets and may be adopted independently from core.

Forward Compatibility

Implementations should follow these forward-compatibility practices:

1. Ignore unknown fields in envelopes and payloads. 2. Reject unknown event types with event.rejected (code unknown_event_type). Unknown event types are not forwarded. 3. Downgrade gracefully when a peer declares an older version — use only features available in that version. 4. Log, don't crash on protocol features you don't recognize.

Deprecation Policy

Harmovela follows a no-surprise deprecation policy:

1. Deprecation notice: A field, event type, or feature is marked deprecated in a minor version release. 2. Support window: The deprecated item is supported for at least one additional minor version. 3. Removal: The item is removed in the next major version.

Deprecation notices appear in the protocol specification changelog and the relevant spec document.

Implementation Notes

Implementations must include spec_version in every envelope.
The legacy field name aep_version is rejected everywhere. Implementations must reject envelopes that use aep_version instead of spec_version.
Version mismatch should result in event.rejected with code unsupported_version and details.supported listing accepted versions.
Payload schema URIs are not validated by the protocol layer itself; they are metadata for schema-aware consumers.