🔄 05_14_01_serialization_engine - Transformación Bidireccional¶

PROPÓSITO¶

El Serialization Engine es el traductor universal que convierte estados vivos en memoria a formatos persistentes y viceversa. Como un teletransportador molecular, debe desarmar completamente un objeto, transmitirlo, y reconstruirlo exactamente igual al otro lado.

La diferencia entre una serialización mediocre y una excelente es la diferencia entre presets que "casi" suenan igual y presets que son idénticos bit por bit.

CONCEPTOS CLAVE¶

Estrategias de Serialización¶

serialization_formats = {
    'binary': {
        'pros': ['Rápido', 'Compacto', 'Eficiente'],
        'cons': ['No human-readable', 'Platform-dependent'],
        'use_for': ['Cache', 'Temp storage', 'Fast switching']
    },
    'json': {
        'pros': ['Human-readable', 'Universal', 'Debuggable'],
        'cons': ['Verbose', 'Slower parsing'],
        'use_for': ['User presets', 'Sharing', 'Version control']
    },
    'xml': {
        'pros': ['Estándar industria', 'Validación robusta'],
        'cons': ['Muy verbose', 'Parse lento'],
        'use_for': ['DAW integration', 'Legacy support']
    },
    'protobuf': {
        'pros': ['Eficiente', 'Strongly typed', 'Versioned'],
        'cons': ['Requiere schemas compilados'],
        'use_for': ['Network transfer', 'Cloud sync']
    }
}

Serialización Selectiva¶

serialization_layers:
  essential:      # Siempre incluido
    - parameter_values
    - routing_matrix

  optional:       # Según contexto
    - undo_history
    - automation_data

  excluded:       # Nunca serializado
    - audio_buffers
    - temp_calculations
    - cache_data

ARQUITECTURA¶

Strategy Pattern¶

                  ┌─────────────────┐
                  │   Serializer    │
                  │   (Abstract)    │
                  └────────┬────────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │   JSON    │   │  Binary   │   │    XML    │
    │Serializer │   │Serializer │   │Serializer │
    └───────────┘   └───────────┘   └───────────┘

Optimizaciones¶

Lazy Loading: Cargar recursos grandes on-demand
Differential Saves: Solo guardar cambios
Compression: zlib/lz4 para preset banks
Parallel Processing: Multi-thread para banks grandes
Memory Pools: Reutilizar buffers de serialización

ESTRUCTURA¶

05_14_01_serialization_engine/
├── include/
│   ├── serializer.hpp              # Interface base
│   ├── json_serializer.hpp         # JSON implementation
│   ├── binary_serializer.hpp       # Binary implementation
│   ├── xml_serializer.hpp          # XML implementation
│   ├── protobuf_serializer.hpp     # Protobuf implementation
│   ├── compression.hpp             # Compression utilities
│   ├── lazy_loader.hpp             # Lazy loading system
│   └── serialization_context.hpp   # Context y configuración
│
├── src/
│   ├── serializer.cpp
│   ├── json_serializer.cpp
│   ├── binary_serializer.cpp
│   ├── xml_serializer.cpp
│   ├── compression.cpp
│   └── lazy_loader.cpp
│
├── tests/
│   ├── test_json_serializer.cpp
│   ├── test_binary_serializer.cpp
│   ├── test_compression.cpp
│   ├── test_round_trip.cpp
│   └── test_performance.cpp
│
├── benchmarks/
│   ├── benchmark_serialization.cpp
│   └── benchmark_compression.cpp
│
└── examples/
    ├── serialize_to_formats.cpp
    └── compress_preset_bank.cpp

API PRINCIPAL¶

namespace audiolab::preset {

// Interface base
class Serializer {
public:
    enum class Format {
        JSON,
        Binary,
        XML,
        Protobuf,
        MessagePack
    };

    virtual ~Serializer() = default;

    // Serialization
    virtual std::vector<uint8_t> serialize(
        const PresetSchema& preset) = 0;

    // Deserialization
    virtual PresetSchema deserialize(
        const std::vector<uint8_t>& data) = 0;

    // Metadata
    virtual Format getFormat() const = 0;
    virtual std::string getFormatName() const = 0;
    virtual bool isHumanReadable() const = 0;
};

// Factory
class SerializerFactory {
public:
    static std::unique_ptr<Serializer> create(
        Serializer::Format format);

    static Serializer::Format detectFormat(
        const std::vector<uint8_t>& data);
};

// JSON Serializer (ya implementado en TAREA 1)
class JsonSerializer : public Serializer {
public:
    struct Options {
        bool pretty_print = true;
        int indent = 2;
        bool include_metadata = true;
        bool include_checksum = true;
    };

    explicit JsonSerializer(const Options& opts = {});

    std::vector<uint8_t> serialize(
        const PresetSchema& preset) override;

    PresetSchema deserialize(
        const std::vector<uint8_t>& data) override;
};

// Binary Serializer
class BinarySerializer : public Serializer {
public:
    struct Header {
        uint32_t magic;      // 'ALPP' (AudioLab Preset)
        uint16_t version;
        uint16_t format;
        uint32_t size;
        uint32_t checksum;
    };

    std::vector<uint8_t> serialize(
        const PresetSchema& preset) override;

    PresetSchema deserialize(
        const std::vector<uint8_t>& data) override;

private:
    void writeHeader(std::ostream& os, const Header& header);
    Header readHeader(std::istream& is);
};

// Compression
class Compression {
public:
    enum class Algorithm {
        None,
        Zlib,
        LZ4,
        Zstd
    };

    static std::vector<uint8_t> compress(
        const std::vector<uint8_t>& data,
        Algorithm algo = Algorithm::Zlib,
        int level = 6);

    static std::vector<uint8_t> decompress(
        const std::vector<uint8_t>& data,
        Algorithm algo = Algorithm::Zlib);

    static size_t getCompressedSize(
        const std::vector<uint8_t>& data,
        Algorithm algo);
};

} // namespace audiolab::preset

EJEMPLOS DE USO¶

Serializar a múltiples formatos¶

PresetSchema preset = /* ... */;

// JSON (human-readable)
JsonSerializer json_ser;
auto json_data = json_ser.serialize(preset);
saveToFile("preset.json", json_data);

// Binary (fast)
BinarySerializer bin_ser;
auto bin_data = bin_ser.serialize(preset);
saveToFile("preset.albp", bin_data);  // AudioLab Binary Preset

// Comprimir
auto compressed = Compression::compress(bin_data);
saveToFile("preset.albp.lz4", compressed);

Factory pattern¶

// Auto-detect format
auto format = SerializerFactory::detectFormat(data);
auto serializer = SerializerFactory::create(format);
auto preset = serializer->deserialize(data);

Round-trip test¶

// Original
PresetSchema original = /* ... */;

// Serialize
auto data = serializer.serialize(original);

// Deserialize
auto restored = serializer.deserialize(data);

// Verify
assert(original == restored);

MÉTRICAS DE ÉXITO¶

✅ Serializers para 4+ formatos (JSON, Binary, XML, Protobuf)
✅ Performance <50ms para presets típicos
✅ Compression ratio >60% para banks
✅ Zero data loss en round-trip
✅ Benchmarks comparativos documentados

FORMATO BINARIO SPECIFICATION¶

AudioLab Binary Preset Format (.albp)

Header (16 bytes):
  [0-3]   Magic:    'ALPP' (0x41 0x4C 0x50 0x50)
  [4-5]   Version:  uint16 (e.g., 0x0100 = v1.0)
  [6-7]   Flags:    uint16 (compressed, encrypted, etc.)
  [8-11]  Size:     uint32 (uncompressed size)
  [12-15] Checksum: uint32 (CRC32)

Data:
  Version block
  Header block
  Parameters block
  Resources block
  Metadata block
  Checksum (SHA256)

PRÓXIMOS PASOS¶

Implementar JsonSerializer (wrapper de TAREA 1)
Implementar BinarySerializer
Implementar Compression
Tests exhaustivos
Performance benchmarks
Documentación completa