forge_descriptor_audit.hpp

Go to the documentation of this file.

#pragma once
 
// The descriptor lifecycle check.
//
// A descriptor that drifts from its DSP is worse than no descriptor: it reads
// as authoritative while naming a parameter that moved or vanished. This audit
// joins each descriptor against the node it annotates and fails closed in both
// directions — a newly baked parameter with no descriptor is as much a failure
// as a descriptor for a parameter that was removed.
//
// Everything here is structural. It needs no per-family knowledge, so a new
// catalog pack is covered the moment it is indexed.
 
#include <pulp/host/forge_param_descriptor.hpp>
#include <pulp/host/custom_node_type.hpp>
 
#include <algorithm>
#include <string>
#include <vector>
 
namespace pulp::host {
 
enum class ForgeAuditFault {
    missing_catalog_node,    
    unexpected_catalog_node, 
    missing_realization,     
    unexpected_realization,  
    mismatched_type_id,      
    duplicate_type_id,       
    duplicate_axis,          
    duplicate_realization,   
    missing_axis_setting,    
    unexpected_axis_setting, 
    unknown_axis_value,      
    undescribed_param,       
    stale_descriptor,        
    duplicate_key,           
    duplicate_id,            
    missing_choices,         
    duplicate_choice,        
    choices_on_continuous,   
    choice_out_of_range,     
    unknown_realization,     
    empty_field,             
    no_realizations          
};
 
struct ForgeAuditFinding {
    ForgeAuditFault fault = ForgeAuditFault::undescribed_param;
    std::string node;    
    std::string subject; 
    std::string detail;
};
 
const char* forge_audit_fault_name(ForgeAuditFault fault);

std::vector<ForgeAuditFinding>
audit_forge_descriptor(const ForgeNodeDescriptor& descriptor,
                       const std::vector<CustomNodeBakedParam>& baked,
                       std::string_view realization_mode = {});

std::vector<ForgeAuditFinding>
audit_forge_catalog_membership(const std::vector<ForgeNodeDescriptor>& descriptors,
                               const std::vector<std::string_view>& expected_node_keys);

std::string describe_forge_audit_finding(const ForgeAuditFinding& finding);
 
} // namespace pulp::host