Spec canónica de protocols/schema-versioning/README.md, copiada sin reescribir.
protocols/schema-versioning/README.mdPágina generada desde
protocols/schema-versioning/README.md. No se edita a mano:bun run docs:genla regenera ybun run docs:checkfalla si difiere.
Definir las reglas de evolución de esquemas para todos los contratos del sistema Styx: mensajes del bus NATS (cmd/qry/evt), mensajes IPC (Bun ↔ Zig), y contratos de serialización de media.
MKS2508/spire spec/ENVELOPE_V2.md): su primer byte es la versión del sobre (2) y cada
mensaje lleva el contract_version (u16 ≥ 1) de su contrato.packages/api-contracts/src/bus/*.ts: requestContract / eventContract) declara
su version, independiente del sobre. Un cambio incompatible de un contrato es una versión
nueva del contrato; un cambio del formato del sobre es una versión nueva del sobre, nunca una
extensión.Un schema nuevo (v2) debe poder leer mensajes escritos con el schema viejo (v1).
Un schema viejo (v1) debe poder leer mensajes escritos con schema nuevo (v2) sin crash.
| Formato | Política |
|---|---|
| JSON | MUST ignore, MUST NOT crash, MAY log warning, MUST discard al re-serializar. |
| Protobuf | MUST ignore, MUST NOT crash, MUST preserve al re-serializar (protobuf wire format retiene unknown fields). |
| Contratos del bus (spire) | Objetos cerrados (additionalProperties: false): un campo desconocido es invalid_request. Un campo nuevo es una versión de contrato nueva, que emisor y receptor despliegan a la vez (la tabla de rutas es una sola). |
@deprecated en JSDoc + log warning).MessageEnvelope v1 al sobre de spire lo aprobó el lock del 2026-09-28, dec-0119/dec-0120).validate() del espejo generado en Zig).