Página generada desde protocols/schema-versioning/FIXTURES.md. No se edita a mano: bun run docs:gen la regenera y bun run docs:check falla si difiere.

Golden Fixtures StrategyCopiar enlace

PropósitoCopiar enlace

Las golden fixtures son archivos JSON canónicos que representan mensajes de cada versión de los contratos. Sirven para verificar que todos los bindings (TS, Swift, Zig) parsean y serializan exactamente el mismo formato.

UbicaciónCopiar enlace

fixtures/contracts/
  v1/
    envelope.json           # Envelope básico
    cmd.catalog.scanAsset.json
    evt.catalog.assetIndexed.json
  v2/
    ...

ReglasCopiar enlace

1. Cada binding debe pasar todas las fixtures de todas las versiones soportadas.
2. Conformance tests: comparan output de cada binding contra las fixtures.
3. Nueva versión: nueva fixture en fixtures/contracts/v<N>/. Las viejas no se modifican.
4. Regeneración: cuando un schema cambia, regenerar fixtures y correr todos los conformance tests.

Formato de fixtureCopiar enlace

Cada fixture es un archivo JSON que representa un mensaje serializado completo (envelope + payload).

{
  "_meta": {
    "schema": "envelope",
    "version": 1,
    "generatedAt": "2026-06-21T00:00:00Z",
    "description": "Envelope básico con payload ScanAssetCommand"
  },
  "messageId": "00000000-0000-0000-0000-000000000001",
  "schemaVersion": 1,
  "correlationId": "corr-001",
  "payload": {
    "path": "/media/movie.mkv"
  }
}

Cross-language testingCopiar enlace

Cuando se implementen bindings Swift y Zig:

1. El binding TS lee la fixture y la valida con Arktype.
2. El binding Swift deserializa la misma fixture y verifica que los campos coinciden.
3. El binding Zig deserializa la misma fixture y produce el mismo output.
4. Cada binding serializa un mensaje de prueba y se compara byte a byte con la fixture.

HerramientasCopiar enlace

• Para TS: Vitest + JSON.parse + Arktype.
• Para Swift: JSONDecoder + tests unitarios.
• Para Zig: std.json + tests.
• No implementar tooling de conformance ahora (F0). Documentar para F1.