clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/collection_manager.py

@@ -0,0 +1,553 @@
+"""
+Collection Manager - Dynamic CLM assembly using MCard Collections
+
+Manages the dynamic assembly of CLM specifications from individual
+components stored in MCard Collections, providing a high-level interface
+for PTR operations.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from clm.layer0.algebra import AssembledCLM, CLMAssembler
+from clm.layer0.loader import YAMLTemplateLoader
+from clm.layer2.card_collection import CardCollection
+
+from .storage import MCardStorage
+
+
+@dataclass
+class CollectionStats:
+    """Statistics for a managed collection"""
+
+    total_cards: int
+    pcard_count: int
+    vcard_count: int
+    clm_component_count: int
+    assembled_clm_count: int
+    last_updated: datetime
+
+
+class CollectionManager:
+    """
+    High-level manager for PTR operations using MCard Collections.
+
+    This class provides:
+    - Dynamic CLM assembly from components
+    - PCard and VCard management
+    - Template loading and storage
+    - Search and discovery capabilities
+    - Statistics and monitoring
+    """
+
+    def __init__(self, collection: CardCollection = None):
+        self.logger = logging.getLogger(__name__)
+        self.collection = collection or CardCollection()
+
+        # Initialize sub-components
+        self.storage = MCardStorage(self.collection)
+        self.template_loader = YAMLTemplateLoader(storage_collection=self.collection)
+        self.clm_assembler = CLMAssembler(
+            storage_collection=self.collection, template_loader=self.template_loader
+        )
+
+        self.logger.info("Collection Manager initialized")
+
+    def create_pcard_from_templates(
+        self,
+        abstract_template: str,
+        concrete_template: str,
+        balanced_template: str,
+        name: str = None,
+        metadata: dict[str, Any] = None,
+    ) -> dict[str, Any]:
+        """
+        Create a complete PCard from YAML templates.
+
+        Args:
+            abstract_template: YAML content for abstract dimension
+            concrete_template: YAML content for concrete dimension
+            balanced_template: YAML content for balanced dimension
+            name: Optional name for the PCard
+            metadata: Additional metadata
+
+        Returns:
+            Dictionary with creation results and hashes
+        """
+        try:
+            # Parse templates
+            import yaml
+
+            abstract_data = yaml.safe_load(abstract_template)
+            concrete_data = yaml.safe_load(concrete_template)
+            balanced_data = yaml.safe_load(balanced_template)
+
+            # Create PCard content
+            pcard_content = {
+                "abstract": abstract_data,
+                "concrete": concrete_data,
+                "balanced": balanced_data,
+            }
+
+            # Add metadata
+            pcard_metadata = {
+                "name": name
+                or f"PCard_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}",
+                "created_from": "templates",
+                "template_count": 3,
+            }
+            if metadata:
+                pcard_metadata.update(metadata)
+
+            # Store PCard
+            storage_result = self.storage.store_pcard(pcard_content, pcard_metadata)
+
+            if not storage_result.success:
+                raise ValueError(
+                    f"Failed to store PCard: {storage_result.error_message}"
+                )
+
+            self.logger.info(f"Created PCard from templates: {storage_result.hash}")
+
+            return {
+                "success": True,
+                "pcard_hash": storage_result.hash,
+                "metadata": storage_result.metadata,
+                "components": {
+                    "abstract": abstract_data,
+                    "concrete": concrete_data,
+                    "balanced": balanced_data,
+                },
+            }
+
+        except (yaml.YAMLError, ValueError, TypeError, KeyError) as e:
+            self.logger.error(
+                f"Failed to create PCard from templates: {str(e)}", exc_info=True
+            )
+            return {"success": False, "error_message": str(e)}
+
+    def create_pcard_from_clm_assembly(
+        self,
+        assembled_clm: AssembledCLM,
+        name: str = None,
+        metadata: dict[str, Any] = None,
+    ) -> dict[str, Any]:
+        """
+        Create a PCard from an assembled CLM.
+
+        Args:
+            assembled_clm: AssembledCLM object
+            name: Optional name for the PCard
+            metadata: Additional metadata
+
+        Returns:
+            Dictionary with creation results
+        """
+        try:
+            # Extract CLM content from assembly
+            pcard_content = {
+                "abstract": assembled_clm.abstract.content,
+                "concrete": assembled_clm.concrete.content,
+                "balanced": assembled_clm.balanced.content,
+            }
+
+            # Create metadata
+            pcard_metadata = {
+                "name": name or assembled_clm.name,
+                "created_from": "clm_assembly",
+                "assembly_hash": assembled_clm.assembly_hash,
+                "validation": {
+                    "is_valid": assembled_clm.validation_result.is_valid,
+                    "errors": assembled_clm.validation_result.errors,
+                    "warnings": assembled_clm.validation_result.warnings,
+                },
+            }
+            if metadata:
+                pcard_metadata.update(metadata)
+
+            # Store PCard
+            storage_result = self.storage.store_pcard(pcard_content, pcard_metadata)
+
+            if not storage_result.success:
+                raise ValueError(
+                    f"Failed to store PCard: {storage_result.error_message}"
+                )
+
+            self.logger.info(f"Created PCard from CLM assembly: {storage_result.hash}")
+
+            return {
+                "success": True,
+                "pcard_hash": storage_result.hash,
+                "metadata": storage_result.metadata,
+                "assembly_hash": assembled_clm.assembly_hash,
+            }
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(
+                f"Failed to create PCard from CLM assembly: {str(e)}", exc_info=True
+            )
+            return {"success": False, "error_message": str(e)}
+
+    def assemble_clm_from_components(
+        self,
+        abstract_name: str,
+        concrete_name: str,
+        balanced_name: str,
+        assembly_name: str = None,
+    ) -> dict[str, Any]:
+        """
+        Assemble a complete CLM from individual component templates.
+
+        Args:
+            abstract_name: Name of abstract template
+            concrete_name: Name of concrete template
+            balanced_name: Name of balanced template
+            assembly_name: Optional name for the assembled CLM
+
+        Returns:
+            Dictionary with assembly results
+        """
+        try:
+            # Load templates
+            abstract_template = self.template_loader.get_template(
+                "abstract", abstract_name
+            )
+            concrete_template = self.template_loader.get_template(
+                "concrete", concrete_name
+            )
+            balanced_template = self.template_loader.get_template(
+                "balanced", balanced_name
+            )
+
+            if not abstract_template:
+                raise ValueError(f"Abstract template not found: {abstract_name}")
+            if not concrete_template:
+                raise ValueError(f"Concrete template not found: {concrete_name}")
+            if not balanced_template:
+                raise ValueError(f"Balanced template not found: {balanced_name}")
+
+            # Create components from templates
+            abstract_component = self.clm_assembler.create_component_from_template(
+                "abstract", abstract_name, abstract_template.content
+            )
+            concrete_component = self.clm_assembler.create_component_from_template(
+                "concrete", concrete_name, concrete_template.content
+            )
+            balanced_component = self.clm_assembler.create_component_from_template(
+                "balanced", balanced_name, balanced_template.content
+            )
+
+            # Assemble CLM
+            assembled_clm = self.clm_assembler.assemble_clm(
+                abstract_component.mcard_hash,
+                concrete_component.mcard_hash,
+                balanced_component.mcard_hash,
+                assembly_name,
+            )
+
+            self.logger.info(
+                f"Assembled CLM: {assembled_clm.name} (valid: {assembled_clm.validation_result.is_valid})"
+            )
+
+            return {
+                "success": True,
+                "assembly_hash": assembled_clm.assembly_hash,
+                "assembly_name": assembled_clm.name,
+                "validation": {
+                    "is_valid": assembled_clm.validation_result.is_valid,
+                    "errors": assembled_clm.validation_result.errors,
+                    "warnings": assembled_clm.validation_result.warnings,
+                },
+                "components": {
+                    "abstract": abstract_component.mcard_hash,
+                    "concrete": concrete_component.mcard_hash,
+                    "balanced": balanced_component.mcard_hash,
+                },
+            }
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(f"Failed to assemble CLM: {str(e)}", exc_info=True)
+            return {"success": False, "error_message": str(e)}
+
+    def find_executable_pcards(
+        self, filters: dict[str, Any] = None
+    ) -> list[dict[str, Any]]:
+        """
+        Find PCards that are ready for execution (valid CLM assembly).
+
+        Args:
+            filters: Optional filters to apply
+
+        Returns:
+            List of executable PCard information
+        """
+        try:
+            # Search for PCards
+            search_results = self.storage.search_pcards("PCard", filters)
+            executable_pcards = []
+
+            for result in search_results:
+                if not result.success:
+                    continue
+
+                metadata = result.metadata
+                content = result.content
+
+                # Check if it has all CLM dimensions
+                has_all_dimensions = (
+                    "abstract" in content
+                    and "concrete" in content
+                    and "balanced" in content
+                )
+
+                # Check validation status
+                validation = metadata.get("validation", {})
+                is_valid = validation.get(
+                    "is_valid", True
+                )  # Assume valid if not specified
+
+                if has_all_dimensions and is_valid:
+                    executable_pcards.append(
+                        {
+                            "hash": result.metadata.get("hash", "unknown"),
+                            "name": metadata.get("name", "unnamed"),
+                            "created_at": metadata.get("created_at"),
+                            "validation": validation,
+                            "dimensions": list(content.keys()),
+                        }
+                    )
+
+            self.logger.info(f"Found {len(executable_pcards)} executable PCards")
+
+            return executable_pcards
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(
+                f"Failed to find executable PCards: {str(e)}", exc_info=True
+            )
+            return []
+
+    def get_clm_components_by_type(
+        self, dimension: str, filters: dict[str, Any] = None
+    ) -> list[dict[str, Any]]:
+        """
+        Get CLM components by dimension type.
+
+        Args:
+            dimension: CLM dimension ('abstract', 'concrete', or 'balanced')
+            filters: Optional filters
+
+        Returns:
+            List of component information
+        """
+        try:
+            # Find compatible components
+            components = self.clm_assembler.find_compatible_components(
+                dimension, filters
+            )
+
+            component_list = []
+            for component in components:
+                component_list.append(
+                    {
+                        "hash": component.mcard_hash,
+                        "name": component.name,
+                        "dimension": component.dimension,
+                        "version": component.version,
+                        "dependencies": component.dependencies,
+                    }
+                )
+
+            self.logger.info(f"Found {len(component_list)} {dimension} components")
+
+            return component_list
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(
+                f"Failed to get {dimension} components: {str(e)}", exc_info=True
+            )
+            return []
+
+    def create_verification_vcard(
+        self,
+        pcard_hash: str,
+        target_hash: str,
+        verification_result: dict[str, Any],
+        execution_output: Any = None,
+    ) -> dict[str, Any]:
+        """
+        Create a verification VCard as audit evidence.
+
+        Args:
+            pcard_hash: Hash of the executed PCard
+            target_hash: Hash of the target MCard/VCard
+            verification_result: CLM verification results
+            execution_output: Output from execution
+
+        Returns:
+            Dictionary with VCard creation results
+        """
+        try:
+            # Create VCard content
+            vcard_content = {
+                "type": "VerificationVCard",
+                "subject": {"pcard_hash": pcard_hash, "target_hash": target_hash},
+                "verifier": "ptr_collection_manager",
+                "evidence": {
+                    "clm_verification": verification_result,
+                    "execution_output": (
+                        str(execution_output) if execution_output else None
+                    ),
+                    "verification_timestamp": datetime.now(timezone.utc).isoformat(),
+                },
+            }
+
+            # Create metadata
+            vcard_metadata = {
+                "verification_type": "execution",
+                "pcard_hash": pcard_hash,
+                "target_hash": target_hash,
+                "created_at": datetime.now(timezone.utc).isoformat(),
+            }
+
+            # Store VCard
+            storage_result = self.storage.store_vcard(vcard_content, vcard_metadata)
+
+            if not storage_result.success:
+                raise ValueError(
+                    f"Failed to store VCard: {storage_result.error_message}"
+                )
+
+            self.logger.info(f"Created VerificationVCard: {storage_result.hash}")
+
+            return {
+                "success": True,
+                "vcard_hash": storage_result.hash,
+                "metadata": storage_result.metadata,
+            }
+
+        except (ValueError, TypeError, KeyError) as e:
+            self.logger.error(
+                f"Failed to create VerificationVCard: {str(e)}", exc_info=True
+            )
+            return {"success": False, "error_message": str(e)}
+
+    def get_collection_statistics(self) -> CollectionStats:
+        """
+        Get comprehensive statistics for the managed collection.
+
+        Returns:
+            CollectionStats object with detailed statistics
+        """
+        try:
+            # Get basic storage statistics
+            storage_stats = self.storage.get_storage_statistics()
+
+            # Count CLM components
+            clm_component_count = 0
+            for dimension in ["abstract", "concrete", "balanced"]:
+                components = self.clm_assembler.find_compatible_components(dimension)
+                clm_component_count += len(components)
+
+            # Count assembled CLMs
+            assembled_clms = self.clm_assembler.list_assembled_clms()
+            assembled_clm_count = len(assembled_clms)
+
+            # Create stats object
+            stats = CollectionStats(
+                total_cards=storage_stats.get("total_cards", 0),
+                pcard_count=storage_stats.get("by_type", {}).get("pcard", 0),
+                vcard_count=storage_stats.get("by_type", {}).get("vcard", 0),
+                clm_component_count=clm_component_count,
+                assembled_clm_count=assembled_clm_count,
+                last_updated=datetime.now(timezone.utc),
+            )
+
+            return stats
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(
+                f"Failed to get collection statistics: {str(e)}", exc_info=True
+            )
+            return CollectionStats(
+                total_cards=0,
+                pcard_count=0,
+                vcard_count=0,
+                clm_component_count=0,
+                assembled_clm_count=0,
+                last_updated=datetime.now(timezone.utc),
+            )
+
+    def search_collection(
+        self, query: str, card_type: str = "all"
+    ) -> list[dict[str, Any]]:
+        """
+        Search across the entire collection.
+
+        Args:
+            query: Search query
+            card_type: Type of cards to search ('all', 'pcard', 'vcard', 'component')
+
+        Returns:
+            List of search results
+        """
+        try:
+            all_results = []
+
+            if card_type in ["all", "pcard"]:
+                pcard_results = self.storage.search_pcards(query)
+                for result in pcard_results:
+                    if result.success:
+                        all_results.append(
+                            {
+                                "type": "pcard",
+                                "hash": result.metadata.get("hash", "unknown"),
+                                "name": result.metadata.get("name", "unnamed"),
+                                "metadata": result.metadata,
+                            }
+                        )
+
+            if card_type in ["all", "vcard"]:
+                vcard_results = self.storage.search_vcards(query)
+                for result in vcard_results:
+                    if result.success:
+                        all_results.append(
+                            {
+                                "type": "vcard",
+                                "hash": result.metadata.get("hash", "unknown"),
+                                "verification_type": result.metadata.get(
+                                    "verification_type", "unknown"
+                                ),
+                                "metadata": result.metadata,
+                            }
+                        )
+
+            if card_type in ["all", "component"]:
+                # Search for CLM components
+                for dimension in ["abstract", "concrete", "balanced"]:
+                    components = self.clm_assembler.find_compatible_components(
+                        dimension
+                    )
+                    for component in components:
+                        if query.lower() in component.name.lower():
+                            all_results.append(
+                                {
+                                    "type": "component",
+                                    "dimension": dimension,
+                                    "hash": component.mcard_hash,
+                                    "name": component.name,
+                                    "version": component.version,
+                                }
+                            )
+
+            self.logger.info(
+                f"Search for '{query}' found {len(all_results)} results (type: {card_type})"
+            )
+
+            return all_results
+
+        except (ValueError, TypeError, KeyError, AttributeError) as e:
+            self.logger.error(f"Failed to search collection: {str(e)}", exc_info=True)
+            return []

clm/layer4/commands/__init__.py

@@ -0,0 +1,81 @@
+"""CLM Layer 4 Universal Subcommand Grammar Registry and Dispatcher.
+
+Sprint 412 / DEL-412-04.
+Normative Spec: docs/spec/30-interfaces/universal_subcommand_grammar.md
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+
+from clm.layer4.commands.action_cmd import action_cmd, workflow_cmd
+from clm.layer4.commands.check_cmd import check_cmd
+from clm.layer4.commands.envelope import format_error, format_failure, format_success
+from clm.layer4.commands.evaluate_cmd import (
+    assess_equivalence_subcmd,
+    compose_conditions_subcmd,
+    directory_fs_scan_subcmd,
+    directory_to_db_subcmd,
+    evaluate_subcmd,
+    remote_handle_resolver_subcmd,
+    route_handle_subcmd,
+)
+from clm.layer4.commands.mcard_cmd import mcard_cmd
+from clm.layer4.commands.petri_cmd import petri_run_net_cmd
+from clm.layer4.commands.tridb_cmd import (
+    init_tridb_cmd,
+    memorize_mcard_cmd,
+    register_handle_cmd,
+    resolve_handle_cmd,
+    resolve_handle_hash_cmd,
+    sql_cmd,
+)
+from clm.layer4.commands.version_cmd import version_cmd
+
+# Registry mapping all USG and backward-compatible subcommands to their handlers
+COMMAND_REGISTRY: dict[str, Callable[[list[str]], int]] = {
+    # 12 Canonical USG Subcommands
+    "evaluate": evaluate_subcmd,
+    "petri-run-net": petri_run_net_cmd,
+    "run-net": petri_run_net_cmd,  # Alias
+    "init-tridb": init_tridb_cmd,
+    "memorize-mcard": memorize_mcard_cmd,
+    "resolve-handle": resolve_handle_cmd,
+    "sql": sql_cmd,
+    "mcard": mcard_cmd,
+    "compose-conditions": compose_conditions_subcmd,
+    "action": action_cmd,
+    "workflow": workflow_cmd,
+    "check": check_cmd,
+    "version": version_cmd,
+    # Extended & Backward-Compatibility Commands
+    "resolve-handle-hash": resolve_handle_hash_cmd,
+    "register-handle": register_handle_cmd,
+    "assess-equivalence": assess_equivalence_subcmd,
+    "directory-fs-scan": directory_fs_scan_subcmd,
+    "directory-to-db": directory_to_db_subcmd,
+    "route-handle": route_handle_subcmd,
+    "remote-handle-resolver": remote_handle_resolver_subcmd,
+}
+
+KNOWN_COMMANDS: set[str] = set(COMMAND_REGISTRY.keys())
+
+
+def dispatch_command(command: str, args: list[str]) -> int:
+    """Dispatch a command string and arguments to its registered handler."""
+    handler = COMMAND_REGISTRY.get(command)
+    if handler is None:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        return 1
+    return handler(args)
+
+
+__all__ = [
+    "COMMAND_REGISTRY",
+    "KNOWN_COMMANDS",
+    "dispatch_command",
+    "format_success",
+    "format_failure",
+    "format_error",
+]

clm/layer4/commands/action_cmd.py

@@ -0,0 +1,42 @@
+"""Action and Workflow Subcommand Handlers.
+
+Sprint 412 / DEL-412-04.
+Normative Spec: docs/spec/30-interfaces/universal_subcommand_grammar.md §2.9 - §2.10
+"""
+
+from __future__ import annotations
+
+import sys
+
+from clm.layer4.action_commands import handle_action_cli, handle_workflow_cli
+
+
+def action_cmd(args: list[str]) -> int:
+    """Handle 'action' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm action <apply|run|validate|diff|list> <spec.yaml> [options]")
+        return 0
+
+    if not args:
+        print("Usage: clm action <apply|run|validate|diff|list> <spec.yaml> [options]", file=sys.stderr)
+        return 2
+
+    # Translate USG 'apply' to existing 'run' subcommand
+    translated = list(args)
+    if translated and translated[0] == "apply":
+        translated[0] = "run"
+
+    return handle_action_cli(translated)
+
+
+def workflow_cmd(args: list[str]) -> int:
+    """Handle 'workflow' subcommand."""
+    if "--help" in args or "-h" in args:
+        print("Usage: clm workflow <run|validate|status> <dag.yaml> [options]")
+        return 0
+
+    if not args:
+        print("Usage: clm workflow <run|validate|status> <dag.yaml> [options]", file=sys.stderr)
+        return 2
+
+    return handle_workflow_cli(args)