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

Generated Bindings DesignCopiar enlace

PropósitoCopiar enlace

Diseñar el enfoque para generar bindings TS/Swift/Zig desde un schema canónico. Esto permite mantener un único source of truth para los contratos y derivar tipos en todos los lenguajes.

Estado (2026-09-30, dec-0116 + dec-0120): resuelto para TS↔Zig. La fuente de verdad son los JSON Schema (TypeBox 1.x) de @styx/api-contracts (dec-0116: Arktype fuera). El segundo binding ya existe: @spire/bus/codegen genera structs Zig con validate() desde los mismos schemas (bun run gen:bus → native/zig/media-daemon/ipc/contracts.generated.zig; check:bus falla si lo versionado difiere) y la conformidad TS↔Zig la fijan los vectores y el fuzz diferencial de spire. El formato del IPC Bun↔Zig es el sobre binario de spire con payload JSON del contrato, no protobuf. Lo de abajo queda como registro de las opciones que se evaluaron; Swift sigue abierto (tras F-FUSION).

OpcionesCopiar enlace

Opción A: Arktype como source of truth (actual)Copiar enlace

• Pros: Ya existe, funcionando, tipos TS nativos.
• Contras: Arktype es una librería TS. Generar Swift/Zig desde Arktype requiere un codegen custom.
• Veredicto: Suficiente para F0. Para F1 evaluar si se necesita codegen.

Opción B: Protobuf IDL como source of truthCopiar enlace

• Pros: IDL independiente del lenguaje, codegen nativo para TS/Swift/Zig/C/Rust. Probado en producción.
• Contras: Añade protoc al toolchain. Los tipos generados no son tan ergonómicos como los TS nativos.
• Veredicto: Opción recomendada para F1 si los contratos se estabilizan y se necesita interoperabilidad cross-language.

Opción C: Custom codegen desde TypeScript typesCopiar enlace

• Pros: Mantiene TS como source of truth. Puede generar tipos exactos.
• Contras: Requiere mantener un codegen custom. Riesgo de divergencia.
• Veredicto: No recommended — demasiado esfuerzo de mantenimiento para un proyecto personal.

Diseño propuesto (F1)Copiar enlace

┌──────────────────────┐
│  protobuf IDL (.proto)│  ← Source of truth
└──────────┬───────────┘
           │
    ┌──────┴──────┐
    │  protoc     │  ← Codegen tool
    └──────┬──────┘
           │
    ┌──────┴──────┬──────────┐
    ▼             ▼          ▼
  TS types     Swift      Zig
  (ts-proto)   (swift-protobuf) (zig-protobuf)

Decisiones diferidasCopiar enlace

• Cuándo migrar: Cuando el segundo binding (Swift o Zig) necesite los mismos contratos. Hasta entonces, Arktype + TS es suficiente.
• Formato IPC: protobuf es el candidato natural para el IPC Bun↔Zig (r07). Evaluar en F0.B.1.
• Mantenimiento: Si solo hay 2 lenguajes (TS + Zig), mantener tipos a mano puede ser más barato que el overhead de protoc.