05_01_01_composition_rules - El Código Legal¶

🎯 Propósito¶

Implementación de las reglas formales que gobiernan cómo los módulos pueden componerse en AudioLab DSP. Este es el "código legal" de la arquitectura - las leyes que hacen cumplir la jerarquía L0→L1→L2→L3.

📂 Estructura¶

05_01_01_composition_rules/
├── include/
│   └── composition_rules.hpp      # Header principal (API completa)
│
├── src/
│   ├── composition_rule_base.cpp  # Clase base y utilities
│   ├── axiom_rules.cpp            # 4 axiomas fundamentales
│   ├── level_specific_rules.cpp   # Reglas por nivel (L1/L2/L3)
│   └── rule_engine.cpp            # Motor de evaluación
│
├── tests/
│   └── test_composition_rules.cpp # Suite completa (>90% coverage)
│
├── docs/
│   └── RULE_CATALOG.md            # Catálogo de reglas documentado
│
├── CMakeLists.txt
└── README.md

🚀 Quick Start¶

Compilar¶

mkdir build && cd build
cmake ..
cmake --build .

Ejecutar tests¶

./test_composition_rules

💻 Uso Básico¶

Validar un módulo¶

#include <audiolab/hierarchy/composition_rules.hpp>

using namespace audiolab::hierarchy;

// Obtener engine global (viene con reglas por defecto)
auto& engine = global_rule_engine();

// Tu módulo
ModuleMetadata my_module{
    "SVF_Filter",
    ModuleLevel::L1_ATOM,
    {"mul_kernel", "add_kernel"},  // Dependencies
    "1.0.0",
    "State Variable Filter"
};

// Todos los módulos del sistema
std::map<std::string, ModuleMetadata> all_modules{
    {"SVF_Filter", my_module},
    {"mul_kernel", /* L0 kernel */},
    {"add_kernel", /* L0 kernel */}
};

// Validar todas las reglas
auto result = engine.check_all(my_module, all_modules);

if (result.passed) {
    std::cout << "✅ Module is valid!\n";
} else {
    std::cout << "❌ Violations found:\n";
    for (const auto& violation : result.violations) {
        std::cout << violation.to_string();
    }
}

Utility function rápida¶

bool valid = is_valid_composition(my_module, all_modules);
if (!valid) {
    std::cout << "Module violates composition rules\n";
}

📊 Reglas Implementadas¶

🔴 Axiomas (4 reglas - ERROR severity)¶

AXIOM_001: Acyclicity
No circular dependencies (A→B→C→A forbidden)
AXIOM_002: Strict Hierarchy
Modules can only depend on lower levels
Enforcea la matriz de dependencias 4x4
AXIOM_003: L0 Foundational
L0 kernels must have zero AudioLab dependencies
AXIOM_004: Transitivity
Hierarchy preserved transitively (if A→B→C, then level(C) < level(B) < level(A))

🔵 Level-Specific (3 reglas - ERROR severity)¶

LEVEL_L1_001: L1 No Horizontal
L1_ATOM cannot depend on other L1_ATOM
LEVEL_L2_001: L2 No Cycles
L2_CELL can depend on L2 but without cycles
LEVEL_L3_001: L3 No Horizontal
L3_ENGINE cannot depend on other L3_ENGINE

🟡 Quality (1 regla - WARNING severity)¶

QUALITY_001: Max Dependencies
Enforces recommended dependency counts per level

Total: 8 reglas por defecto

🔑 Clases Principales¶

`CompositionRule` (abstract base)¶

Clase base para todas las reglas.

class CompositionRule {
    virtual RuleCheckResult check(
        const ModuleMetadata& metadata,
        const std::map<std::string, ModuleMetadata>& all_modules
    ) const = 0;
};

`RuleEngine`¶

Orquesta la ejecución de reglas.

RuleEngine engine;

// Agregar reglas
engine.add_rule(std::make_unique<MyCustomRule>());

// O usar reglas por defecto
engine.register_default_rules();

// Validar módulo
auto result = engine.check_all(module, all_modules);

// Validar regla específica
auto result = engine.check_rule("AXIOM_001_ACYCLICITY", module, all_modules);

`RuleCheckResult`¶

Resultado de validación.

struct RuleCheckResult {
    bool passed;
    std::vector<RuleViolation> violations;
    std::string details;

    bool has_errors() const;
    bool has_warnings() const;
    size_t error_count() const;
    size_t warning_count() const;
};

📚 Documentación¶

Lectura Recomendada¶

RULE_CATALOG.md ⭐ IMPORTANTE
Catálogo completo de todas las reglas
Ejemplos de violación y corrección
Justificación de cada regla
tests/test_composition_rules.cpp
Ejemplos de uso en tests
Casos edge documentados

🎯 Ejemplos de Violaciones Comunes¶

❌ Violación 1: L1 horizontal dependency¶

// ❌ BAD
class L1_Filter {
    L1_Oscillator osc_;  // L1 → L1 forbidden!
};

Fix:

// ✅ GOOD
class L2_SynthVoice {
    L1_Filter filter_;
    L1_Oscillator osc_;  // Compose in L2
};

❌ Violación 2: Upward dependency¶

// ❌ BAD
class L0_Kernel {
    L1_Atom atom_;  // L0 → L1 forbidden!
};

Fix:

// ✅ GOOD
class L1_Atom {
    // uses L0 kernels only
};

❌ Violación 3: Circular dependency¶

// ❌ BAD
class ModuleA { ModuleB b_; };
class ModuleB { ModuleA a_; };  // Cycle!

Fix:

// ✅ GOOD
class SharedLogic {};
class ModuleA { SharedLogic shared_; };
class ModuleB { SharedLogic shared_; };

🛠️ Crear Regla Custom¶

class MyCustomRule : public CompositionRule {
public:
    MyCustomRule()
        : CompositionRule(
            "CUSTOM_001",
            "My Custom Rule",
            "Description of what it checks",
            RuleSeverity::WARNING
        )
    {}

    RuleCheckResult check(
        const ModuleMetadata& metadata,
        const std::map<std::string, ModuleMetadata>& all_modules
    ) const override {
        RuleCheckResult result;
        result.passed = true;

        // Your validation logic here
        if (/* violation detected */) {
            result.passed = false;
            result.violations.push_back(create_violation(
                metadata.module_name,
                "What went wrong",
                "How to fix it"
            ));
        }

        return result;
    }
};

// Usar la regla
auto& engine = global_rule_engine();
engine.add_rule(std::make_unique<MyCustomRule>());

✅ Tests¶

Ejecutar suite completa¶

cd build
./test_composition_rules

Cobertura esperada¶

Target: >90% code coverage
Framework: Catch2 v3
Test cases: 40+ test sections

Categorías de tests¶

[axiom] - Tests de axiomas
[level] - Tests level-specific
[quality] - Tests de calidad
[engine] - Tests de RuleEngine
[integration] - Tests de integración

🔗 Dependencias¶

Runtime¶

level_definitions (subsistema 00)
C++20 compiler
STL

Build-time¶

CMake 3.20+
Catch2 v3 (auto-fetched)

📋 API Reference¶

Severidades¶

enum class RuleSeverity : uint8_t {
    ERROR   = 0,  // Blocks compilation/merge
    WARNING = 1,  // Generates alert
    INFO    = 2   // Informational only
};

RuleViolation¶

struct RuleViolation {
    std::string rule_id;
    std::string rule_name;
    RuleSeverity severity;
    std::string module_name;
    std::string description;
    std::string suggestion;

    std::string to_string() const;
};

❓ FAQ¶

P: ¿Cuántas reglas se ejecutan por defecto? R: 8 reglas (4 axiomas + 3 level-specific + 1 quality).

P: ¿Las reglas se ejecutan en orden específico? R: No, todas se ejecutan independientemente. El resultado es la unión de todas las violaciones.

P: ¿Puedo desactivar una regla? R: En desarrollo sí (crea tu propio RuleEngine). En producción usa el Exemption System (subsistema 07).

P: ¿Qué pasa si violo una regla WARNING? R: Genera alerta pero no bloquea. Las ERROR bloquean merge/compilación.

P: ¿Cómo añado mi propia regla? R: Hereda de CompositionRule, implementa check(), y añádela al engine.

📌 Próximos Pasos¶

Después de completar este módulo:

05_01_02_validation_engine - Motor de validación completo
05_01_06_enforcement_system - Enforcement multi-nivel

Status: ✅ Completado Cobertura: >90% Última actualización: 2025-10-10

05_01_01_composition_rules - El Código Legal¶

🎯 Propósito¶

📂 Estructura¶

🚀 Quick Start¶

Compilar¶

Ejecutar tests¶

💻 Uso Básico¶

Validar un módulo¶

Utility function rápida¶

📊 Reglas Implementadas¶

🔴 Axiomas (4 reglas - ERROR severity)¶

🔵 Level-Specific (3 reglas - ERROR severity)¶

🟡 Quality (1 regla - WARNING severity)¶

🔑 Clases Principales¶

CompositionRule (abstract base)¶

RuleEngine¶

RuleCheckResult¶

📚 Documentación¶

Lectura Recomendada¶

🎯 Ejemplos de Violaciones Comunes¶

❌ Violación 1: L1 horizontal dependency¶

❌ Violación 2: Upward dependency¶

❌ Violación 3: Circular dependency¶

🛠️ Crear Regla Custom¶

✅ Tests¶

Ejecutar suite completa¶

Cobertura esperada¶

Categorías de tests¶

🔗 Dependencias¶

Runtime¶

Build-time¶

📋 API Reference¶

Severidades¶

RuleViolation¶

❓ FAQ¶

📌 Próximos Pasos¶

`CompositionRule` (abstract base)¶

`RuleEngine`¶

`RuleCheckResult`¶