@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/domains/sam-coder/event-payload-design-patterns.md

@@ -0,0 +1,127 @@
+---
+title: "Event Payload Design Patterns"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["event-payload", "message-design", "data-patterns", "serialization"]
+prerequisites: ["event-fundamentals", "data-structures", "json-handling"]
+samples: "samples/event-payload-design.md"
+related_topics: ["event-bridge-pattern-al", "command-queue-pattern-al"]
+---
+
+# Event Payload Design Patterns
+
+## Overview
+
+Event Payload Design Patterns provide structured approaches for designing event data that is maintainable, extensible, and efficient. Well-designed payloads ensure events can evolve over time while maintaining compatibility with existing consumers.
+
+**Key Benefit**: Creates stable, extensible event contracts that support system evolution without breaking existing integrations.
+
+## Core Design Principles
+
+### Payload Structure Standards
+Design consistent payload structures that include essential metadata alongside business data, enabling reliable event processing and debugging.
+
+### Versioning Strategy
+Implement payload versioning that supports backward compatibility while enabling gradual migration to new payload formats.
+
+### Data Completeness
+Include sufficient data in payloads to enable consumers to process events without requiring additional data lookups when possible.
+
+## Essential Payload Patterns
+
+### Envelope Pattern
+Wrap business data in standardized envelopes that include metadata such as event type, timestamp, source system, and correlation identifiers.
+
+### Reference vs. Value Inclusion
+Balance between including complete data (values) versus references (IDs) based on payload size, security requirements, and consumer needs.
+
+### Hierarchical Data Organization
+Structure complex data hierarchically to support partial consumption and efficient serialization/deserialization operations.
+
+## Payload Evolution Strategies
+
+### Additive Changes
+Design payload evolution strategies that primarily use additive changes, ensuring new fields don't break existing consumers.
+
+### Optional Field Patterns
+Use optional fields and default values to enable payload enhancement without requiring immediate consumer updates.
+
+### Migration Support
+Implement payload transformation capabilities that can convert between different payload versions during transition periods.
+
+## Performance Optimization
+
+### Size Optimization
+Balance payload completeness with size constraints to ensure efficient network transmission and processing performance.
+
+### Serialization Efficiency
+Choose serialization formats and patterns that optimize for the primary usage scenarios (human readability vs. processing speed).
+
+### Compression Strategies
+Implement compression strategies for large payloads while considering the processing overhead of compression/decompression.
+
+## Data Integrity and Security
+
+### Validation Patterns
+- Implement payload validation at both producer and consumer sides
+- Define clear data type and format requirements
+- Support schema validation for structured payload formats
+- Provide clear error messages for validation failures
+
+### Sensitive Data Handling
+- Avoid including sensitive data in event payloads when possible
+- Implement data masking patterns for logging and debugging
+- Use references to sensitive data rather than including values directly
+- Support encryption for payloads containing sensitive information
+
+## Specialized Payload Types
+
+### Command Payloads
+Design command payloads that include all necessary information for executing operations, including parameters and execution context.
+
+### State Change Payloads
+Structure state change events to include both previous and current state information, enabling consumers to understand the nature of changes.
+
+### Batch Operation Payloads
+Design payloads for batch operations that efficiently represent collections of related changes or operations.
+
+## Integration Considerations
+
+### Cross-System Compatibility
+Design payloads that can cross system boundaries effectively, considering different serialization capabilities and data type support.
+
+### Protocol Independence
+Structure payloads to work effectively across different transport protocols and message delivery mechanisms.
+
+### Consumer Diversity
+Consider the needs of different types of consumers (real-time processors, batch systems, human operators) when designing payload structures.
+
+## Best Practices
+
+### Design Guidelines
+- Use clear, descriptive field names that convey meaning
+- Include timestamp and correlation information in all payloads
+- Implement consistent data type usage across similar fields
+- Provide comprehensive documentation for payload schemas
+
+### Documentation Standards
+- Document all payload fields with clear descriptions and examples
+- Provide schema definitions using standard formats (JSON Schema, OpenAPI)
+- Include example payloads for common scenarios
+- Maintain version history and migration guidance
+
+## Common Pitfalls
+
+### Payload Bloat
+Avoid including unnecessary data that increases payload size without providing corresponding value to consumers.
+
+### Breaking Changes
+Prevent accidental breaking changes through careful payload evolution planning and thorough testing of changes.
+
+### Inconsistent Structure
+Avoid inconsistent payload structures across similar events that create confusion and increase integration complexity.
+
+*Complete payload design examples: samples/event-payload-design.md*
+*Event routing patterns: event-bridge-pattern-al.md*
+*Command processing: command-queue-pattern-al.md*

package/embedded-knowledge/domains/sam-coder/generic-method-patterns-al.md

@@ -0,0 +1,141 @@
+---
+title: "Generic Method Patterns in AL"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "18+"
+tags: ["generic-methods", "type-safety", "code-reuse", "al-generics"]
+prerequisites: ["al-basics", "interface-implementation", "advanced-al-features"]
+samples: "samples/generic-method-patterns.md"
+related_topics: ["type-safe-operations-al", "template-method-pattern-al"]
+---
+
+# Generic Method Patterns in AL
+
+## Overview
+
+Generic Method Patterns in AL enable type-safe, reusable code by allowing methods to work with different data types while maintaining compile-time type checking. These patterns reduce code duplication and provide flexible, maintainable solutions for common algorithmic operations.
+
+**Key Benefit**: Enables creation of type-safe, reusable algorithms that work across different data types while maintaining performance and compile-time validation.
+
+## Core Generic Concepts
+
+### Type Parameter Definition
+Define generic type parameters in method signatures that can represent any compatible type, enabling flexible method implementation.
+
+### Constraint Specification
+Apply constraints to generic type parameters to ensure they meet specific requirements for the generic algorithm implementation.
+
+### Type Inference
+Leverage AL's type inference capabilities to reduce explicit type specification while maintaining type safety in generic method calls.
+
+## Essential Generic Patterns
+
+### Collection Processing Generics
+Implement generic methods for common collection operations such as filtering, mapping, and reduction that work across different data types.
+
+### Comparison and Sorting Generics
+Design generic comparison and sorting algorithms that can work with any comparable data type while maintaining efficiency.
+
+### Data Transformation Generics
+Create generic transformation methods that can convert between different data types using consistent transformation patterns.
+
+## Advanced Generic Techniques
+
+### Multi-Type Parameter Methods
+Design methods with multiple generic type parameters that can handle complex operations involving multiple related types.
+
+### Generic Factory Methods
+Implement generic factory patterns that can create instances of different types based on generic parameters and runtime conditions.
+
+### Generic Event Handlers
+Create generic event handling patterns that can process events with different payload types using consistent handling logic.
+
+## Type Safety Strategies
+
+### Constraint-Based Validation
+- Use generic constraints to ensure type parameters meet specific interface or inheritance requirements
+- Implement compile-time validation for generic type compatibility
+- Design constraint hierarchies that support complex type requirements
+- Provide clear error messages for constraint violations
+
+### Runtime Type Checking
+- Implement runtime type validation for scenarios where compile-time checking is insufficient
+- Support dynamic type discovery and validation in generic methods
+- Handle type conversion and casting safely within generic implementations
+- Provide fallback mechanisms for unsupported type scenarios
+
+## Performance Optimization
+
+### Generic Method Specialization
+Implement specialized versions of generic methods for commonly used types to optimize performance while maintaining generic interface compatibility.
+
+### Type-Specific Optimizations
+Design generic methods that can apply type-specific optimizations based on runtime type information while maintaining consistent interfaces.
+
+### Memory Efficiency
+Optimize memory usage in generic methods by avoiding unnecessary object creation and implementing efficient type-specific storage patterns.
+
+## Integration Patterns
+
+### Interface-Based Generics
+Design generic methods that work with interfaces, enabling polymorphic behavior while maintaining type safety and flexibility.
+
+### Generic Extension Methods
+Implement extension methods using generic patterns to add functionality to existing types without modification.
+
+### Generic Builder Patterns
+Create generic builder patterns that can construct complex objects of different types using consistent building interfaces.
+
+## Error Handling and Validation
+
+### Generic Exception Patterns
+Design exception handling patterns that work effectively with generic methods while providing meaningful error information.
+
+### Type Validation Strategies
+Implement comprehensive type validation that ensures generic methods receive compatible types and handle edge cases appropriately.
+
+### Constraint Violation Handling
+Handle constraint violations gracefully with clear error messages and appropriate fallback behaviors.
+
+## Testing Generic Methods
+
+### Parameterized Testing
+- Design test patterns that validate generic method behavior across multiple type parameters
+- Implement property-based testing for generic algorithms
+- Support type-specific test scenarios while maintaining generic test structure
+- Validate constraint enforcement and error handling
+
+### Type Coverage Testing
+- Ensure test coverage across all supported generic type parameters
+- Test edge cases and boundary conditions for different types
+- Validate performance characteristics across different type parameters
+- Test integration scenarios with complex generic method compositions
+
+## Best Practices
+
+### Design Principles
+- Keep generic methods focused and single-purpose
+- Use meaningful names for generic type parameters
+- Implement appropriate constraints to ensure type safety
+- Provide clear documentation for generic method usage and constraints
+
+### Performance Guidelines
+- Consider the performance implications of generic method implementation
+- Use specialized implementations for performance-critical scenarios
+- Minimize boxing and unboxing operations in generic methods
+- Profile generic method performance with different type parameters
+
+## Common Pitfalls
+
+### Over-Generalization
+Avoid creating overly generic methods that become complex and difficult to understand or maintain.
+
+### Constraint Misuse
+Prevent inappropriate use of generic constraints that unnecessarily limit method applicability or create confusing type requirements.
+
+### Performance Degradation
+Be aware of potential performance impacts from generic method overhead, especially in high-frequency scenarios.
+
+*Complete generic method examples: samples/generic-method-patterns.md*
+*Type-safe operations: type-safe-operations-al.md*
+*Template method patterns: template-method-pattern-al.md*

package/embedded-knowledge/domains/sam-coder/manual-binding-conditional-subscribers.md

@@ -0,0 +1,66 @@
+---
+title: "Manual Binding for Conditional Event Subscribers"
+domain: "sam-coder"
+difficulty: "advanced"
+bc_versions: "16+"
+tags: ["events", "binding", "conditional", "runtime"]
+prerequisites: ["event-subscriber-basics", "binding-patterns"]
+samples: "samples/manual-binding.md"
+---
+# Manual Binding for Conditional Event Subscribers
+
+## Overview
+
+Manual binding enables runtime control over event subscriber activation, allowing conditional subscriber registration based on business logic, configuration, or environmental factors. This pattern provides architectural flexibility beyond static EventSubscriber attribute declarations.
+
+Manual binding requires explicit subscriber registration and deregistration through the BC event management framework. This approach trades development simplicity for runtime control and dynamic event handling capabilities.
+
+The pattern is essential for scenarios requiring conditional event processing, multi-tenant customizations, or feature-flag-controlled functionality where static binding creates unnecessary overhead or conflicts.
+
+## Architectural Benefits
+
+Manual binding enables conditional event processing based on runtime criteria such as user permissions, feature flags, or business configuration. Subscribers only activate when actually needed, reducing unnecessary event processing overhead.
+
+Dynamic binding supports multi-tenant scenarios where different tenants require different event handling logic. The same codebase can provide tenant-specific event processing without static coupling to all possible variations.
+
+Feature toggles and A/B testing scenarios benefit from manual binding's ability to enable or disable event handlers without code deployment. Business logic changes can control event processing behavior dynamically.
+
+## Implementation Patterns
+
+Manual binding requires implementing custom registration logic typically executed during application startup or feature activation. The registration code must handle both binding and unbinding scenarios appropriately.
+
+Conditional binding logic should evaluate business rules, configuration settings, or environmental factors to determine when subscribers should be active. The evaluation timing and frequency impact system performance and behavior consistency.
+
+Error handling becomes critical in manual binding scenarios since registration failures can silently disable expected functionality. Robust error handling and logging ensure binding issues are detected and resolved promptly.
+
+## Lifecycle Management
+
+Manual binding requires explicit lifecycle management for subscriber registration and deregistration. Unlike static subscribers, manually bound subscribers need active management throughout their operational lifetime.
+
+Registration timing affects when events begin processing through manual subscribers. Early registration ensures events are captured from system startup, while delayed registration may miss early system events.
+
+Deregistration becomes necessary when conditional criteria change or features deactivate. Failed deregistration can lead to unexpected event processing and potential system conflicts.
+
+## Configuration Integration
+
+Manual binding integrates naturally with configuration management systems, allowing business users to control event processing behavior without technical intervention. Configuration changes can enable or disable event handlers dynamically.
+
+Configuration-driven binding requires robust validation to ensure only valid subscribers are registered and conflicting configurations are detected early. Invalid configurations should fail safely without disrupting other system functions.
+
+Runtime configuration changes need careful handling to avoid inconsistent states where some events are processed by newly configured handlers while others use previous configurations.
+
+## Performance Considerations
+
+Manual binding introduces registration overhead during application startup or feature activation. The registration cost must be balanced against the flexibility benefits, particularly in high-frequency event scenarios.
+
+Conditional evaluation logic adds processing overhead to determine when subscribers should be active. Efficient evaluation algorithms minimize performance impact while providing necessary flexibility.
+
+Dynamic binding and unbinding during system operation can create temporary inconsistencies where some events are processed differently than others. Timing considerations ensure consistent event processing behavior.
+
+## Testing Strategies
+
+Manual binding requires comprehensive testing of both bound and unbound states to ensure correct behavior under all configuration scenarios. Test suites must validate conditional binding logic and edge cases.
+
+Integration testing becomes more complex with manual binding since the same codebase behaves differently based on binding configuration. Test environments must exercise all possible binding combinations.
+
+Performance testing must account for binding overhead and conditional evaluation impact on overall system performance, particularly during startup and configuration change scenarios.

package/embedded-knowledge/domains/sam-coder/nested-compound-best-practices.md

@@ -0,0 +1,96 @@
+---
+title: "AL Nested Compound Statement Best Practices"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["nested-statements", "code-organization", "readability", "complexity-management"]
+prerequisites: ["compound-statement-readability", "al-control-flow"]
+samples: "samples/nested-compound-best-practices.md"
+---
+# AL Nested Compound Statement Best Practices
+
+## Overview
+
+Nested compound statements in AL require careful organization to maintain readability and prevent excessive complexity that impairs code maintenance. While compound statements enhance individual construct clarity, deep nesting can create cognitive overload that negates readability benefits.
+
+Effective nested compound statement management balances structural clarity with complexity control through strategic indentation, logical grouping, and complexity reduction techniques. Professional AL development emphasizes readable nesting patterns that support both immediate comprehension and long-term maintainability.
+
+The challenge lies in preserving the benefits of compound statements while managing the visual and cognitive complexity that emerges from multiple levels of nested begin-end blocks. Successful approaches combine consistent formatting with architectural patterns that minimize nesting depth.
+
+## Complexity Management Principles
+
+### Depth Limitation Strategies
+
+Establish practical limits on nesting depth to prevent excessive complexity that overwhelms developer comprehension. Most experienced AL developers find that more than three levels of nesting create significant cognitive load during code reading and maintenance.
+
+When nesting depth approaches problematic levels, consider extracting nested logic into separate procedures or functions. This extraction reduces visual complexity while maintaining logical organization and creating reusable code components.
+
+Apply the principle that each level of nesting should represent a meaningful logical distinction rather than arbitrary grouping. Each nested level should serve a clear purpose that justifies the additional complexity it introduces.
+
+### Logical Organization
+
+Structure nested compound statements to follow natural business logic flow rather than purely technical organization. Group related operations within the same nesting level to create coherent logical blocks that match business process understanding.
+
+Use consistent patterns for similar types of nested logic throughout the AL codebase. Establish standard approaches for common scenarios like validation cascades, error handling hierarchies, and data processing workflows.
+
+Organize nested statements to minimize the cognitive distance between related operations. Keep logically connected statements within the same visual scope to reduce mental mapping requirements during code comprehension.
+
+### Visual Structure Enhancement
+
+Apply consistent indentation patterns that clearly communicate nesting relationships without creating excessive horizontal space consumption. Balance clarity with practical line length constraints imposed by development environments.
+
+Use strategic whitespace and commenting to create visual separation between different logical blocks within nested structures. This separation helps developers parse complex nesting without losing track of scope boundaries.
+
+Consider using meaningful variable names and procedure names that communicate the purpose of nested blocks, reducing the need to parse nested logic to understand overall intent.
+
+## Implementation Patterns
+
+### Validation Cascades
+
+Implement cascading validation logic through structured nesting that creates clear decision trees. Each level of nesting should represent a distinct validation concern that builds upon previous validation results.
+
+Structure validation nesting to fail fast and minimize unnecessary processing when early validation steps fail. This approach improves both performance and code clarity by establishing clear exit conditions.
+
+Use compound statements to group related validation operations within each nesting level, creating logical units that can be understood independently while contributing to overall validation flow.
+
+### Error Handling Hierarchies
+
+Organize error handling through nested compound statements that create layered exception handling appropriate to different error types and severity levels. Each nesting level should handle errors at the appropriate abstraction level.
+
+Implement error handling nesting that provides specific error responses at the appropriate scope level while maintaining general error handling at outer levels. This layered approach ensures comprehensive error coverage without excessive complexity.
+
+Use nested error handling to implement graceful degradation patterns where different levels of functionality can continue operating even when specific subsystems encounter errors.
+
+### Business Process Workflows
+
+Structure business process implementation through nested compound statements that mirror actual business workflow steps. Each nesting level should represent a significant business decision point or process phase.
+
+Organize workflow nesting to support process modification and extension without requiring restructuring of existing nested logic. This approach facilitates business requirement changes that commonly occur in AL applications.
+
+Use nested compound statements to implement approval workflows, document processing chains, and other multi-step business processes that require clear state management and decision tracking.
+
+## Readability Optimization
+
+### Strategic Extraction
+
+Identify nested logic candidates for extraction into separate procedures or functions based on complexity metrics and logical cohesion. Extract nested blocks that serve distinct purposes or could be reused in different contexts.
+
+Use extraction to reduce visual complexity while preserving logical relationships between different parts of nested operations. Extracted procedures should have clear interfaces and well-defined responsibilities.
+
+Apply extraction selectively to avoid creating excessive procedure fragmentation that makes code navigation difficult. Balance nested complexity reduction with overall code organization and discoverability.
+
+### Commenting Strategies
+
+Use strategic comments to explain the purpose and context of nested compound statements without cluttering the code with excessive documentation. Focus comments on business logic rationale rather than technical implementation details.
+
+Apply header comments to complex nested sections that explain the overall purpose and expected outcomes. These comments help developers understand the intent before diving into detailed nested logic.
+
+Use inline comments sparingly within nested structures to explain non-obvious business rules or technical constraints that affect the nested logic implementation.
+
+### Formatting Consistency
+
+Establish and maintain consistent formatting patterns for nested compound statements across the entire AL codebase. This consistency reduces the cognitive overhead of parsing different formatting styles.
+
+Use automated formatting tools where possible to ensure consistent indentation and spacing within nested structures. Manual formatting variations can create confusion and reduce readability benefits.
+
+Apply consistent patterns for handling edge cases like empty nested blocks, single-statement nested blocks, and mixed nesting scenarios that commonly arise during development.

package/embedded-knowledge/domains/sam-coder/samples/al-blank-line-organization.md

@@ -0,0 +1,161 @@
+# AL Blank Line Organization - Code Examples
+
+## Good Examples
+
+### Logical Section Separation
+```al
+codeunit 50100 "Customer Management"
+{
+    procedure CreateCustomer(Name: Text[100]; Email: Text[80]): Code[20]
+    var
+        Customer: Record Customer;
+        CustomerNo: Code[20];
+    begin
+        // Input validation section
+        if Name = '' then
+            Error('Customer name cannot be empty');
+        if Email = '' then
+            Error('Customer email cannot be empty');
+
+        // Customer creation section
+        Customer.Init();
+        CustomerNo := NoSeriesMgt.GetNextNo(SalesSetup."Customer Nos.", 0D, true);
+        Customer."No." := CustomerNo;
+        Customer.Name := Name;
+        Customer."E-Mail" := Email;
+
+        // Database operation section
+        Customer.Insert(true);
+
+        // Return result
+        exit(CustomerNo);
+    end;
+}
+```
+
+### Function Group Separation
+```al
+codeunit 50101 "Order Processing"
+{
+    // Validation functions
+    procedure ValidateOrderHeader(var SalesHeader: Record "Sales Header")
+    begin
+        if SalesHeader."Sell-to Customer No." = '' then
+            Error('Customer number is required');
+    end;
+
+    procedure ValidateOrderLines(var SalesLine: Record "Sales Line")
+    begin
+        if SalesLine.Quantity <= 0 then
+            Error('Quantity must be greater than zero');
+    end;
+
+    // Processing functions
+    procedure ProcessOrder(var SalesHeader: Record "Sales Header")
+    begin
+        ValidateOrderHeader(SalesHeader);
+        CalculateTotals(SalesHeader);
+        UpdateInventory(SalesHeader);
+    end;
+
+    procedure CalculateTotals(var SalesHeader: Record "Sales Header")
+    begin
+        SalesHeader.CalcFields("Amount Including VAT");
+    end;
+}
+```
+
+## Bad Examples
+
+### No Logical Separation
+```al
+codeunit 50102 "Bad Organization"
+{
+    procedure ProcessData()
+    var
+        Customer: Record Customer;
+        Item: Record Item;
+        SalesLine: Record "Sales Line";
+    begin
+        if Customer.FindFirst() then
+            Customer.Modify();
+        Item.SetRange(Blocked, false);
+        if Item.FindSet() then
+            repeat
+                Item."Unit Price" := Item."Unit Price" * 1.1;
+                Item.Modify();
+            until Item.Next() = 0;
+        SalesLine.SetRange("Document Type", SalesLine."Document Type"::Order);
+        SalesLine.SetRange("Shipment Date", Today);
+        if SalesLine.FindSet() then
+            SalesLine.DeleteAll();
+        Message('Processing complete');
+    end;
+}
+```
+
+### Excessive Blank Lines
+```al
+codeunit 50103 "Excessive Spacing"
+{
+    procedure BadSpacing()
+    var
+        Customer: Record Customer;
+
+
+        Item: Record Item;
+
+
+        Result: Boolean;
+    begin
+
+
+        Customer.FindFirst();
+
+
+        Item.FindFirst();
+
+
+        Result := true;
+
+
+    end;
+
+
+}
+```
+
+### Missing Function Separation
+```al
+codeunit 50104 "No Function Separation"
+{
+    procedure ValidateCustomer(CustomerNo: Code[20]): Boolean
+    begin
+        exit(CustomerNo <> '');
+    end;
+    procedure CreateItem(ItemNo: Code[20]; Description: Text[100])
+    var
+        Item: Record Item;
+    begin
+        Item.Init();
+        Item."No." := ItemNo;
+        Item.Description := Description;
+        Item.Insert();
+    end;
+    procedure DeleteOrder(OrderNo: Code[20])
+    var
+        SalesHeader: Record "Sales Header";
+    begin
+        SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo);
+        SalesHeader.Delete(true);
+    end;
+}
+```
+
+## Best Practices
+
+1. **Separate logical sections** within procedures with single blank lines
+2. **Separate functions** with single blank lines between procedure declarations
+3. **Group related functions** together without excessive spacing
+4. **Use consistent spacing** throughout the codeunit
+5. **Avoid excessive blank lines** that disrupt reading flow