clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/templates/balanced.yaml

@@ -0,0 +1,253 @@
+# Balanced Expectations Template for CLM
+# This template defines the WHY dimension - the verification proofs and test cases
+
+# Test Cases (BDD Format)
+test_cases:
+  # Behavior-Driven Development test cases
+  # Each test case follows Given-When-Then structure
+  
+  # Example test cases:
+  - given: "A valid input is provided"
+    when: "The transform operation is executed"
+    then:
+      output: "The input is transformed according to specification"
+      status: "success"
+      execution_time_ms: "< 50"
+  
+  - given: "An empty input is provided"
+    when: "The transform operation is executed"
+    then:
+      output: "Empty input is returned"
+      status: "success"
+      execution_time_ms: "< 10"
+  
+  - given: "Invalid input data is provided"
+    when: "The transform operation is executed"
+    then:
+      error: "ValidationError is raised"
+      error_message: "Input validation failed"
+      status: "error"
+
+# Performance Expectations
+expectations:
+  performance:
+    # Expected performance characteristics
+    latency:
+      p50_ms: 10
+      p90_ms: 25
+      p99_ms: 50
+      max_ms: 100
+    
+    throughput:
+      operations_per_second: 100
+      batch_size: 10
+      parallel_workers: 4
+    
+    resource_usage:
+      memory_mb:
+        min: 5
+        max: 50
+        typical: 15
+      cpu_percent:
+        min: 1
+        max: 25
+        typical: 5
+  
+  quality:
+    # Quality expectations and metrics
+    correctness:
+      accuracy_percent: 100
+      error_rate_percent: 0
+      data_integrity: true
+    
+    reliability:
+      availability_percent: 99.9
+      mean_time_between_failures_hours: 1000
+      recovery_time_seconds: 10
+    
+    maintainability:
+      code_coverage_percent: 95
+      cyclomatic_complexity_max: 10
+      documentation_coverage_percent: 80
+
+# Validation Criteria
+validation:
+  # Criteria for validating implementation against specification
+  input_validation:
+    # Input validation rules
+    required_fields: []
+    optional_fields: []
+    field_constraints:
+      # Example:
+      # string_field:
+      #   type: "string"
+      #   min_length: 1
+      #   max_length: 1000
+      #   pattern: "^[a-zA-Z0-9]+$"
+  
+  output_validation:
+    # Output validation rules
+    required_fields: []
+    field_constraints:
+      # Similar to input_validation but for outputs
+      pass
+  
+  business_rules:
+    # Business logic validation
+    rules:
+      # Example:
+      # - name: "data_integrity"
+      #   description: "Output must be derived from input"
+      #   validation: "output_contains_input_elements"
+      # - name: "format_compliance"
+      #   description: "Output must match required format"
+      #   validation: "output_matches_schema"
+
+# Edge Cases and Boundary Conditions
+edge_cases:
+  # Specific edge cases to test
+  boundary_values:
+    # Example:
+    # - input: "empty string"
+    #   expected: "empty output"
+    # - input: "maximum size string"
+    #   expected: "successful transformation"
+    # - input: "special characters only"
+    #   expected: "successful transformation"
+  
+  error_conditions:
+    # Example:
+    # - condition: "null input"
+    #   expected: "ValidationError"
+    # - condition: "invalid type"
+    #   expected: "TypeError"
+    # - condition: "oversized input"
+    #   expected: "SizeError"
+  
+  concurrency:
+    # Concurrent execution scenarios
+    scenarios:
+      # Example:
+      # - scenario: "multiple simultaneous executions"
+      #   expected: "no race conditions"
+      # - scenario: "shared resource access"
+      #   expected: "proper synchronization"
+
+# Regression Tests
+regression:
+  # Regression test suite
+  test_suite:
+    # Example regression tests
+    - name: "basic_functionality_test"
+      description: "Verify basic transformation works"
+      test_data: "sample_input.txt"
+      expected_output: "expected_output.txt"
+    
+    - name: "performance_regression_test"
+      description: "Ensure performance doesn't degrade"
+      benchmark_time_ms: 50
+      tolerance_percent: 20
+  
+  baseline_metrics:
+    # Baseline metrics for regression detection
+    version: "1.0.0"
+    performance_baseline:
+      mean_latency_ms: 10
+      p99_latency_ms: 50
+      throughput_ops_per_sec: 100
+
+# Integration Tests
+integration:
+  # Integration test scenarios
+  dependencies:
+    # Test with actual dependencies
+    # Example:
+    # - name: "database_integration"
+    #   description: "Test with real database"
+    #   setup: "create_test_database"
+    #   teardown: "cleanup_test_database"
+  
+  api_compatibility:
+    # API compatibility tests
+    # Example:
+    # - endpoint: "transform"
+    #   method: "POST"
+    #   request_schema: "transform_request.json"
+    #   response_schema: "transform_response.json"
+
+# Security Tests
+security:
+  # Security-related test cases
+  vulnerabilities:
+    # Example:
+    # - type: "injection"
+    #   test_input: "malicious_string'; DROP TABLE users; --"
+    #   expected_behavior: "rejected or sanitized"
+    # - type: "buffer_overflow"
+    #   test_input: "very_long_string_repeated_10000_times"
+    #   expected_behavior: "graceful handling"
+  
+  access_control:
+    # Access control tests
+    # Example:
+    # - role: "unauthorized_user"
+    #   action: "execute"
+    #   expected: "access_denied"
+    # - role: "authorized_user"
+    #   action: "execute"
+    #   expected: "success"
+
+# Compliance and Audit
+compliance:
+  # Compliance requirements and tests
+  standards:
+    # Example:
+    # - standard: "GDPR"
+    #   requirement: "data_protection"
+    #   test: "verify_no_pii_exposure"
+    # - standard: "SOC2"
+    #   requirement: "audit_trail"
+    #   test: "verify_execution_logging"
+  
+  audit_requirements:
+    # Audit trail requirements
+    logging:
+      - "execution_start"
+      - "execution_success"
+      - "execution_failure"
+      - "performance_metrics"
+    
+    retention:
+      logs_retention_days: 90
+      audit_data_retention_days: 365
+
+# Continuous Monitoring
+monitoring:
+  # Runtime monitoring expectations
+  alerts:
+    # Example:
+    # - metric: "error_rate"
+    #   threshold: "> 5%"
+    #   severity: "warning"
+    # - metric: "latency_p99"
+    #   threshold: "> 100ms"
+    #   severity: "critical"
+  
+  dashboards:
+    # Required monitoring dashboards
+    # Example:
+    # - name: "performance_dashboard"
+    #   metrics: ["latency", "throughput", "error_rate"]
+    # - name: "quality_dashboard"
+    #   metrics: ["accuracy", "availability", "resource_usage"]
+
+# Version History
+version_history:
+  # Track changes and their impact on expectations
+  current_version: "1.0.0"
+  changes:
+    # Example:
+    # - version: "1.0.0"
+    #   date: "2024-01-01"
+    #   changes: ["initial_release"]
+    #   impact: "baseline_expectations_established"

clm/layer0/templates/concrete.yaml

@@ -0,0 +1,172 @@
+# Concrete Implementation Template for CLM
+# This template defines the HOW dimension - the implementation details
+
+# Operation Type
+operation: "transform"  # Type of operation (e.g., "transform", "validate", "compute", "identity")
+
+# Implementation Details
+implementation:
+  # Core implementation logic
+  # Example:
+  # algorithm: "map_transform"
+  # steps:
+  #   - "validate_input"
+  #   - "apply_transformation"
+  #   - "validate_output"
+  
+  # Input handling
+  inputs:
+    # Map abstract inputs to concrete parameters
+    # Example:
+    # data:
+    #   parameter_name: "input_data"
+    #   validation: "validate_utf8"
+    #   transformation: "normalize_line_endings"
+  
+  # Output handling  
+  outputs:
+    # Map concrete outputs to abstract specifications
+    # Example:
+    # result:
+    #   source: "processed_data"
+    #   format: "json"
+    #   encoding: "utf-8"
+
+# Algorithm Specification
+algorithm:
+  # Detailed algorithm description
+  name: ""  # Algorithm name
+  complexity: ""  # Time/space complexity (e.g., "O(n)", "O(n log n)")
+  
+  # Step-by-step process
+  steps:
+    # Example:
+    # - name: "validate_input"
+    #   description: "Check input data validity"
+    #   implementation: "validate_utf8_length"
+    # - name: "transform_data"
+    #   description: "Apply transformation function"
+    #   implementation: "apply_transformation_function"
+    # - name: "format_output"
+    #   description: "Format output according to specification"
+    #   implementation: "format_as_json"
+
+# Transform Function
+transform_function: ""  # Name of transformation function
+# Pre-defined options: "upper_case", "lower_case", "count_bytes", "identity", "reverse", "sort"
+
+# Custom Implementation
+custom_code:
+  # For custom Python code (when transform_function is "custom")
+  enabled: false
+  code: ""  # Python code string
+  dependencies: []  # Required imports
+
+# Error Handling
+error_handling:
+  # How errors are handled
+  strategy: "raise"  # Options: "raise", "return_error", "log_continue"
+  
+  # Error types and handling
+  error_types:
+    # Example:
+    # validation_error:
+    #   action: "raise"
+    #   message: "Input validation failed"
+    # runtime_error:
+    #   action: "log_continue"
+    #   message: "Runtime error, returning None"
+  
+  # Fallback behavior
+  fallback:
+    enabled: false
+    action: "return_none"  # Options: "return_none", "return_default", "retry"
+
+# Resource Requirements
+resources:
+  # System resource requirements
+  memory:
+    min: "10MB"
+    max: "100MB"
+    strategy: "proportional_to_input"  # Options: "fixed", "proportional_to_input"
+  
+  cpu:
+    cores: 1
+    intensity: "low"  # Options: "low", "medium", "high"
+  
+  io:
+    disk_access: false
+    network_access: false
+    max_bandwidth: "1MB/s"
+
+# Performance Characteristics
+performance:
+  # Expected performance metrics
+  execution_time:
+    min_ms: 1
+    max_ms: 100
+    typical_ms: 10
+  
+  throughput:
+    operations_per_second: 100
+    unit: "items"
+  
+  scalability:
+    linear: true  # Whether performance scales linearly with input size
+    max_input_size: "1MB"
+
+# Security Considerations
+security:
+  # Security-related implementation details
+  input_validation: true
+  output_sanitization: true
+  resource_limits: true
+  
+  # Access control
+  permissions:
+    read: true
+    execute: true
+    modify: false
+    delete: false
+  
+  # Sandboxing
+  sandbox_required: false
+  isolation_level: "process"  # Options: "process", "thread", "none"
+
+# Testing Support
+testing:
+  # Testing-specific implementation details
+  mock_enabled: true
+  deterministic: true  # Whether results are deterministic
+  
+  # Test data requirements
+  test_data:
+    generators:
+      - "random_string"
+      - "fixed_example"
+    sizes:
+      - "small: 1KB"
+      - "medium: 10KB"
+      - "large: 100KB"
+
+# Monitoring and Observability
+monitoring:
+  # Metrics and logging configuration
+  metrics_enabled: true
+  logging_level: "INFO"
+  
+  # Custom metrics
+  custom_metrics:
+    - "transformation_time"
+    - "input_size"
+    - "output_size"
+
+# Version Information
+implementation_version: "1.0.0"
+compatibility_matrix:
+  # Compatible versions and features
+  min_ptr_version: "0.1.0"
+  supported_features:
+    - "caching"
+    - "batch_processing"
+    - "async_execution"

clm/layer0/type_registry.py

@@ -0,0 +1,223 @@
+import contextlib
+import json
+import os
+import re
+from typing import Any
+
+import yaml
+
+from .exceptions import TypeValidationError
+
+
+class TypeRegistry:
+    def __init__(self, clm_root: str):
+        self.clm_root = clm_root
+        self.types_dir = os.path.join(clm_root, "types")
+        self.registry: dict[str, dict[str, Any]] = {}
+        self.content_types: dict[str, dict[str, Any]] = {}
+        self.transport_types: dict[str, dict[str, Any]] = {}
+        self.load_registry()
+
+    def load_registry(self):
+        if not os.path.exists(self.types_dir):
+            return
+
+        subdirs = ["meta", "primitives", "runtime", "content", "transport", "codegen"]
+        for subdir in subdirs:
+            subdir_path = os.path.join(self.types_dir, subdir)
+            if not os.path.exists(subdir_path):
+                continue
+            for fname in os.listdir(subdir_path):
+                if fname.endswith(".yaml") or fname.endswith(".yml"):
+                    name = os.path.splitext(fname)[0]
+                    fpath = os.path.join(subdir_path, fname)
+                    try:
+                        with open(fpath, encoding="utf-8") as f:
+                            data = yaml.safe_load(f)
+                        inner = data.get("clm", data)
+                        concrete = inner.get("concrete_impl", {})
+
+                        universe_level = concrete.get("universe_level", 0)
+                        schema = concrete.get("schema", {})
+
+                        type_info = {
+                            "name": name,
+                            "path": fpath,
+                            "universe_level": int(universe_level),
+                            "schema": schema,
+                            "concrete": concrete
+                        }
+
+                        self.registry[name.lower()] = type_info
+
+                        # Content types
+                        if subdir == "content":
+                            ct = concrete.get("content_type", {})
+                            mime = ct.get("mime")
+                            if mime:
+                                self.content_types[mime] = type_info
+
+                        # Transport types
+                        if subdir == "transport":
+                            tp = concrete.get("transport", {})
+                            proto = tp.get("protocol")
+                            if proto:
+                                self.transport_types[name.lower()] = type_info
+
+                    except Exception:
+                        pass
+
+    def get_type_info(self, type_name: str) -> dict[str, Any] | None:
+        return self.registry.get(type_name.lower())
+
+    def validate(self, type_name: str, value: Any, parent_level: int = 999):
+        type_info = self.get_type_info(type_name)
+        if not type_info:
+            raise TypeValidationError(f"Unknown type '{type_name}'")
+
+        level = type_info["universe_level"]
+        if level > parent_level:
+            raise TypeValidationError(
+                f"STRATIFICATION_ERROR: Type '{type_name}' at Level {level} cannot be nested inside a Level {parent_level} parent type context."
+            )
+
+        schema = type_info["schema"]
+
+        # Parse string value to JSON if the type expects structured data and value is a string
+        parsed_val = value
+        if isinstance(value, str):
+            val_trimmed = value.strip()
+            if (val_trimmed.startswith("{") and val_trimmed.endswith("}")) or \
+               (val_trimmed.startswith("[") and val_trimmed.endswith("]")):
+                with contextlib.suppress(Exception):
+                    parsed_val = json.loads(val_trimmed)
+
+        style = _detect_style(schema)
+        fn = _SCHEMA_STYLE_DISPATCH[style]
+        fn(self, type_name, value, parsed_val, schema, level)
+
+
+# ---------------------------------------------------------------------------
+# Sprint 133.5: Dispatch table for schema-style validation
+# ---------------------------------------------------------------------------
+
+def _detect_style(schema: dict) -> str:
+    """Detect which schema style the type uses."""
+    if schema.get("constraints"):
+        return "primitive"
+    if schema.get("required_fields") is not None or schema.get("optional_fields") is not None:
+        return "field_list"
+    if schema.get("required") is not None or schema.get("properties") is not None:
+        return "json_schema"
+    return "primitive"
+
+
+def _validate_primitive(registry, type_name, value, parsed_val, schema, level):
+    """Validate primitive types (pattern + type_check constraints)."""
+    constraints = schema.get("constraints", {})
+    pattern = constraints.get("pattern")
+    type_check = constraints.get("type_check")
+
+    if pattern and pattern != "null" and not re.search(pattern, str(value)):
+        raise TypeValidationError(f"Value '{value}' violates pattern '{pattern}' for type '{type_name}'")
+
+    if type_check and type_check != "null":
+        if type_check == "is_integer":
+            if not re.match(r"^-?[0-9]+$", str(value)):
+                raise TypeValidationError(f"Value '{value}' is not a valid integer for type '{type_name}'")
+        elif type_check == "is_boolean":
+            if str(value).lower() not in ("true", "false"):
+                raise TypeValidationError(f"Value '{value}' is not a valid boolean for type '{type_name}'")
+        elif type_check == "is_string":
+            if isinstance(parsed_val, dict | list):
+                raise TypeValidationError(f"Structural payload is not a valid string for type '{type_name}'")
+            if re.match(r"^-?[0-9]+(\.[0-9]+)?$", str(value)) or str(value).lower() in ("true", "false"):
+                raise TypeValidationError(f"Value '{value}' is not a valid string for type '{type_name}'")
+        elif type_check == "is_list":
+            if not isinstance(parsed_val, list):
+                raise TypeValidationError(f"Value '{value}' is not a valid list structure for type '{type_name}'")
+        elif type_check == "is_map":
+            if not isinstance(parsed_val, dict):
+                raise TypeValidationError(f"Value '{value}' is not a valid map structure for type '{type_name}'")
+        elif type_check == "is_process_payload" and not isinstance(parsed_val, dict | list):
+            raise TypeValidationError(f"Value '{value}' is not a valid process payload (must be map or list) for type '{type_name}'")
+
+
+def _validate_field_list(registry, type_name, value, parsed_val, schema, level):
+    """Validate using required_fields / optional_fields style."""
+    if not isinstance(parsed_val, dict):
+        raise TypeValidationError(f"Value is not a map/object structure required by type '{type_name}'")
+
+    required_fields = schema.get("required_fields") or []
+    optional_fields = schema.get("optional_fields") or []
+
+    for field in required_fields:
+        f_name = field.get("name")
+        f_type = field.get("type")
+        if f_name not in parsed_val:
+            raise TypeValidationError(f"Missing required field '{f_name}' of type '{f_type}' in type '{type_name}'")
+
+        f_val = parsed_val[f_name]
+        registry.validate(f_type, f_val, level)
+
+        f_enum = field.get("enum")
+        if f_enum and str(f_val) not in [str(e) for e in f_enum]:
+            raise TypeValidationError(f"Value '{f_val}' is not in enum {f_enum} for field '{f_name}' in type '{type_name}'")
+
+    for field in optional_fields:
+        f_name = field.get("name")
+        f_type = field.get("type")
+        if f_name in parsed_val:
+            f_val = parsed_val[f_name]
+            if f_val is not None and str(f_val) != "null":
+                registry.validate(f_type, f_val, level)
+
+                f_enum = field.get("enum")
+                if f_enum and str(f_val) not in [str(e) for e in f_enum]:
+                    raise TypeValidationError(f"Value '{f_val}' is not in enum {f_enum} for field '{f_name}' in type '{type_name}'")
+
+
+def _validate_json_schema(registry, type_name, value, parsed_val, schema, level):
+    """Validate using JSON Schema style (required / properties)."""
+    if not isinstance(parsed_val, dict):
+        raise TypeValidationError(f"Value is not a map/object structure required by type '{type_name}'")
+
+    required_props = schema.get("required") or []
+    properties = schema.get("properties") or {}
+
+    for f_name in required_props:
+        if f_name not in parsed_val:
+            raise TypeValidationError(f"Missing required field '{f_name}' in type '{type_name}'")
+
+        f_val = parsed_val[f_name]
+        f_info = properties.get(f_name, {})
+        f_type = f_info.get("type")
+        f_pattern = f_info.get("pattern")
+
+        if f_pattern and not re.search(f_pattern, str(f_val)):
+            raise TypeValidationError(f"Field '{f_name}' value '{f_val}' violates pattern '{f_pattern}' in type '{type_name}'")
+
+        if f_type:
+            resolved_type = f_type
+            if f_type == "array":
+                resolved_type = "list"
+            elif f_type == "object":
+                resolved_type = "map"
+            registry.validate(resolved_type, f_val, level)
+
+
+_SCHEMA_STYLE_DISPATCH = {
+    "primitive": _validate_primitive,
+    "field_list": _validate_field_list,
+    "json_schema": _validate_json_schema,
+}
+
+
+def load_clm_features(clm_root: str | None = None) -> dict[str, Any]:
+    """Loads the SSOT Type Lattice functional features from types/lattice/clm_features.yaml."""
+    if clm_root is None:
+        clm_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../.."))
+    features_path = os.path.join(clm_root, "types", "lattice", "clm_features.yaml")
+    with open(features_path, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+