Core Architecture

Documentation Structure Classification

KERI protocol documentation employs a dual-classification system for content organization:

Protocol Specification
├── Normative Sections
│   ├── MUST requirements (RFC 2119)
│   ├── SHOULD recommendations with compliance implications
│   ├── Protocol message formats
│   ├── Cryptographic algorithm specifications
│   └── Interoperability requirements
└── Non-Normative Sections
    ├── Implementation guidance
    ├── Usage examples
    ├── Security considerations (advisory)
    ├── Performance optimization suggestions
    └── Historical context and rationale

Content Categorization Framework

Non-normative content in KERI specifications typically includes:

1. Explanatory Material

   • Background information on cryptographic primitives
   • Historical context for design decisions
   • Comparison with alternative approaches
   • Educational content for protocol understanding

2. Implementation Guidance

   • Suggested algorithms for non-critical operations
   • Performance optimization techniques
   • Code examples and pseudocode
   • Best practices that don't affect interoperability

3. Security Considerations

   • Threat model discussions
   • Attack vector analysis
   • Risk mitigation strategies
   • Cryptographic agility recommendations

4. Operational Considerations

   • Deployment architecture suggestions
   • Monitoring and observability guidance
   • Troubleshooting procedures
   • Maintenance recommendations

RFC 2119 Compliance Framework

KERI specifications follow RFC 2119 keyword usage patterns:

Normative Keywords:
- MUST / MUST NOT (absolute requirements)
- REQUIRED / SHALL / SHALL NOT (absolute requirements)
- SHOULD / SHOULD NOT (strong recommendations)
- RECOMMENDED / NOT RECOMMENDED (qualified recommendations)
- MAY / OPTIONAL (truly optional features)

Non-Normative Indicators:
- "for example" / "e.g." / "such as"
- "typically" / "usually" / "often"
- "might" / "could" / "possibly"
- "consider" / "suggest" / "recommend" (without SHOULD)

Protocol Mechanics

Specification Parsing Requirements

Implementers must distinguish between normative and non-normative content through:

1. Section Labeling

   ## 4.1 Key Event Structure (Normative)
   ## 4.2 Implementation Examples (Non-Normative)
   ## Appendix A: Security Considerations (Non-Normative)
   

2. Explicit Markers

   • "This section is non-normative"
   • "The following examples are illustrative only"
   • "Implementation note: ..."

3. Content Context Analysis

   • Protocol message format definitions → Normative
   • Example JSON payloads → Non-normative
   • Algorithm specifications → Normative
   • Performance benchmarks → Non-normative

Interoperability Impact Assessment

Non-normative content by definition cannot:

• Create interoperability requirements
• Establish mandatory protocol behaviors
• Define required message formats
• Specify cryptographic algorithm parameters
• Impose implementation constraints

Impact on Protocol Compliance:

Compliance Test Framework:
├── Normative Requirements Testing
│   ├── Message format validation
│   ├── Cryptographic operation verification
│   ├── Protocol state machine compliance
│   └── Interoperability testing
└── Non-Normative Guidance Evaluation
    ├── Implementation quality assessment
    ├── Security posture evaluation
    ├── Performance characteristic analysis
    └── Best practices adherence (optional)

Cryptographic Foundation

Security Model Implications

Non-normative security guidance in KERI specifications includes:

1. Threat Model Discussions

   • Analysis of potential attack vectors
   • Risk assessment methodologies
   • Mitigation strategy recommendations
   • Cryptographic agility planning

2. Implementation Security Considerations

   Non-Normative Security Guidance:
   - Key storage recommendations
   - Random number generation best practices
   - Side-channel attack mitigation
   - Timing attack prevention techniques
   

3. Cryptographic Algorithm Guidance

   • Recommended parameter choices (beyond minimum requirements)
   • Future-proofing strategies
   • Quantum resistance considerations
   • Performance vs. security trade-offs

Formal Verification Boundaries

Normative specifications are subject to formal verification and mathematical proof, while non-normative content represents:

• Heuristic guidance
• Empirical observations
• Practical recommendations
• Implementation experience

Implementation Specifications

API Design Patterns

Non-normative API guidance in KERI implementations:

# Non-normative: Suggested API design pattern
class KERIController:
    def __init__(self, config: Optional[Dict] = None):
        """Initialize controller with optional configuration.
        
        Note: This API design is non-normative and may vary
        between implementations while maintaining protocol compliance.
        """
        pass
    
    def rotate_keys(self, next_keys: List[str]) -> KeyEvent:
        """Perform key rotation operation.
        
        The specific API signature is implementation-dependent,
        but the underlying protocol operation must conform to
        normative KERI key rotation specifications.
        """
        pass

Configuration Management

Non-normative configuration guidance:

# Example configuration (non-normative)
keri:
  witness:
    threshold: 2  # Normative: must be >= 1
    timeout: 30s  # Non-normative: implementation choice
  storage:
    backend: "leveldb"  # Non-normative: implementation choice
    path: "/var/lib/keri"  # Non-normative: deployment choice
  logging:
    level: "info"  # Non-normative: operational choice

Error Handling Strategies

Non-normative error handling recommendations:

1. Error Classification

   • Protocol violations (normative handling required)
   • Implementation errors (non-normative handling)
   • Operational issues (non-normative handling)

2. Recovery Procedures

   • Suggested retry mechanisms
   • Fallback strategies
   • Graceful degradation approaches

Technical Relationships

Documentation Ecosystem Integration

Non-normative content relationships within KERI ecosystem:

KERI Protocol Stack Documentation:
├── Core KERI Specification
│   ├── Normative: Protocol mechanics
│   └── Non-Normative: Implementation guidance
├── ACDC Specification
│   ├── Normative: Credential format
│   └── Non-Normative: Usage patterns
├── CESR Specification
│   ├── Normative: Encoding rules
│   └── Non-Normative: Performance optimization
└── Implementation Guides
    └── Entirely Non-Normative: Best practices

Cross-Reference Management

Non-normative sections may reference normative content but cannot:

• Override normative requirements
• Create new normative obligations
• Modify protocol specifications
• Establish interoperability constraints

Performance Analysis

Computational Complexity Considerations

Non-normative performance guidance includes:

1. Algorithm Complexity Analysis

   Key Event Log Verification:
   - Normative: O(n) verification requirement
   - Non-normative: O(log n) optimization suggestions
   

2. Memory Usage Optimization

   • Suggested caching strategies
   • Memory pool management
   • Garbage collection considerations

3. Network Performance

   • Bandwidth optimization techniques
   • Latency reduction strategies
   • Connection pooling recommendations

Benchmarking Methodologies

Non-normative benchmarking guidance:

• Performance measurement techniques
• Baseline establishment procedures
• Regression testing strategies
• Scalability assessment methods

Edge Cases & Error Handling

Failure Mode Analysis

Non-normative failure analysis includes:

1. System Resilience Patterns

   • Circuit breaker implementations
   • Bulkhead isolation strategies
   • Timeout and retry policies

2. Data Consistency Considerations

   • Eventual consistency handling
   • Conflict resolution strategies
   • State synchronization approaches

3. Network Partition Handling

   • Split-brain prevention
   • Partition tolerance strategies
   • Recovery procedures

Boundary Condition Management

Non-normative boundary handling:

# Non-normative: Suggested input validation
def validate_key_event(event: Dict) -> bool:
    """Validate key event structure.
    
    This validation logic is non-normative and may vary
    between implementations. Normative validation rules
    are specified in the protocol specification.
    """
    # Implementation-specific validation logic
    return True

Standards & Specifications

RFC Compliance Framework

Non-normative content in KERI specifications aligns with:

• RFC 2119: Requirement levels terminology
• RFC 8174: Ambiguity of uppercase/lowercase
• RFC 7322: RFC style guide compliance

Version Management

Non-normative versioning guidance:

1. Semantic Versioning

   • Major version: normative changes
   • Minor version: non-normative additions
   • Patch version: clarifications and corrections

2. Backward Compatibility

   • Non-normative changes don't break compatibility
   • Implementation guidance evolution
   • Best practices updates

Standardization Process

Non-normative content lifecycle:

Specification Development:
├── Draft Stage
│   ├── Normative requirements identification
│   └── Non-normative guidance development
├── Review Stage
│   ├── Normative requirement validation
│   └── Non-normative content review
└── Publication Stage
    ├── Normative specification finalization
    └── Non-normative guidance publication

Production Considerations

Deployment Architecture

Non-normative deployment guidance includes:

1. Infrastructure Patterns

   • High availability configurations
   • Load balancing strategies
   • Disaster recovery procedures

2. Security Hardening

   • Network security configurations
   • Access control implementations
   • Audit logging requirements

3. Monitoring and Observability

   • Metrics collection strategies
   • Alerting configurations
   • Performance monitoring

Operational Procedures

Non-normative operational guidance:

# Non-normative: Suggested monitoring script
#!/bin/bash
# Monitor KERI witness availability
# This script is illustrative and not required for compliance

for witness in $WITNESS_LIST; do
    if ! curl -f "$witness/health"; then
        echo "Warning: Witness $witness unavailable"
    fi
done

Maintenance Strategies

Non-normative maintenance includes:

• Update procedures
• Backup strategies
• Performance tuning
• Capacity planning

These operational considerations support protocol implementation but don't affect interoperability or compliance with normative KERI specifications.