Versioning

The wire version is encoded in the channel topic:

A breaking change bumps the version segment — chat:v2:... — and both versions run on the same socket. A client on v1 and a client on v2 can be connected at once; the server serves each its own contract. There is no flag day.

Breaking (bumps the version)

• Removing or renaming an event or a push
• Removing or renaming a field in a payload
• Changing a field's type
• Changing a sequencing guarantee (e.g. making an atomic batch non-atomic)
• Changing auth semantics for a join
• Changing the meaning of an existing capability string

Non-breaking (no bump)

• Adding an optional field to an existing event or reply
• Adding a new event type — clients ignore events they don't recognise
• Adding a new push / HTTP endpoint
• Adding a new error reason string
• Adding a new capability verb or product
• Tightening validation in a way that only rejects already-malformed input

Capability-token version

Capability tokens carry their own audience, independent of the channel version:

aud: "pingerchips:v3"

A token-format change bumps this (pingerchips:v4), and the issuer (POST /api/auth) can mint the new format while the server still accepts the old one during a transition. See Authentication.

Deprecations in flight