Skip to main content

[!FROZEN] MPLP Protocol v1.0.0 Frozen Specification Freeze Date: 2025-12-03 Status: FROZEN (no breaking changes permitted) Governance: MPLP Protocol Governance Committee (MPGC) License: Apache-2.0 Note: Any normative change requires a new protocol version.

Learning Invariants Reference

1. Purpose​

This document provides the normative reference for all Learning Sample validation invariants defined in schemas/v2/invariants/learning-invariants.yaml.

Invariants are validation rules that MUST be enforced when processing LearningSample objects.

2. Core LearningSample Invariants​

These invariants apply to all LearningSample objects regardless of family.

2.1 Identifier Invariants​

Invariant IDScopePathRuleDescription
learning_sample_id_is_uuidlearning_samplesample_iduuid-v4All LearningSamples must have UUID v4 sample_id
learning_sample_family_non_emptylearning_samplesample_familynon-empty-stringLearningSample must have non-empty sample_family
learning_sample_created_at_isolearning_samplecreated_atiso-datetimecreated_at must be ISO 8601 timestamp

2.2 Required Section Invariants​

Invariant IDScopePathRuleDescription
learning_sample_has_input_sectionlearning_sampleinputexistsLearningSample must have input section
learning_sample_has_output_sectionlearning_sampleoutputexistsLearningSample must have output section

2.3 Meta Field Invariants (Conditional)​

These invariants apply only when the field is present.

Invariant IDScopePathRuleDescription
learning_sample_feedback_label_validlearning_samplemeta.human_feedback_labelenum(approved,rejected,not_reviewed)If present, must be valid enum
learning_sample_source_flow_non_emptylearning_samplemeta.source_flow_idnon-empty-stringIf present, must be non-empty

3. Intent Resolution Family Invariants​

These invariants apply only when sample_family == "intent_resolution".

Invariant IDScopePathRuleDescription
learning_intent_has_intent_idlearning_sampleinput.intent_idnon-empty-stringIntent resolution samples must have intent_id in input
learning_intent_quality_label_validlearning_sampleoutput.resolution_quality_labelenum(good,acceptable,bad,unknown)If present, quality label must be valid enum

4. Delta Impact Family Invariants​

These invariants apply only when sample_family == "delta_impact".

Invariant IDScopePathRuleDescription
learning_delta_has_delta_idlearning_sampleinput.delta_idnon-empty-stringDelta impact samples must have delta_id in input
learning_delta_scope_validlearning_sampleoutput.impact_scopeenum(local,module,system,global)Impact scope must be valid enum
learning_delta_risk_validlearning_samplestate.risk_levelenum(low,medium,high,critical)If present, risk level must be valid enum

5. Invariant Application Logic​

5.1 Conditional Application​

Some invariants are conditional based on:

  • Field existence: Applied only when the field is present
  • Sample family: Applied only for specific sample_family values
# Example from learning-invariants.yaml
- id: learning_intent_has_intent_id
  scope: learning_sample
  path: input.intent_id
  rule: non-empty-string
  description: "Intent resolution samples must have intent_id in input"
  note: "Apply when sample_family == intent_resolution"

5.2 Implementation Notes​

From the invariants file:

If the invariant engine does not support conditional application, these should be enforced at the schema level (already done in family-specific schemas) or during runtime validation. These invariants provide an additional validation layer.

6. Rule Types​

Rule TypeDescriptionExample
uuid-v4Must be a valid UUID version 4550e8400-e29b-41d4-a716-446655440000
non-empty-stringMust be a non-empty string"my-value"
iso-datetimeMust be ISO 8601 date-time2025-12-03T10:00:00Z
existsField must exist (not null/undefined){} is valid, null is not
enum(...)Must be one of the specified valuesenum(low,medium,high)

7. Validation Example​

def validate_learning_sample(sample: dict) -> list[str]:
    """
    Validate a LearningSample against invariants.
    Returns list of violation messages.
    """
    violations = []
    
    # Core invariants
    if not is_uuid_v4(sample.get('sample_id')):
        violations.append("learning_sample_id_is_uuid: sample_id must be UUID v4")
    
    if not sample.get('sample_family'):
        violations.append("learning_sample_family_non_empty: sample_family required")
    
    if not is_iso_datetime(sample.get('created_at')):
        violations.append("learning_sample_created_at_iso: created_at must be ISO 8601")
    
    if 'input' not in sample:
        violations.append("learning_sample_has_input_section: input required")
    
    if 'output' not in sample:
        violations.append("learning_sample_has_output_section: output required")
    
    # Conditional: Meta field validation
    if sample.get('meta', {}).get('human_feedback_label'):
        if sample['meta']['human_feedback_label'] not in ['approved', 'rejected', 'not_reviewed']:
            violations.append("learning_sample_feedback_label_valid: invalid enum")
    
    # Family-specific: intent_resolution
    if sample.get('sample_family') == 'intent_resolution':
        if not sample.get('input', {}).get('intent_id'):
            violations.append("learning_intent_has_intent_id: intent_id required")
    
    # Family-specific: delta_impact
    if sample.get('sample_family') == 'delta_impact':
        if not sample.get('input', {}).get('delta_id'):
            violations.append("learning_delta_has_delta_id: delta_id required")
        
        impact_scope = sample.get('output', {}).get('impact_scope')
        if impact_scope and impact_scope not in ['local', 'module', 'system', 'global']:
            violations.append("learning_delta_scope_valid: invalid impact_scope")
    
    return violations

8. References​

End of Learning Invariants Reference​

2025 Bangshi Beijing Network Technology Limited Company Licensed under the Apache License, Version 2.0.