clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/model/compatibility.py

@@ -0,0 +1,60 @@
+"""
+Compatibility layer for the refactored interpreter.
+
+This module provides backward compatibility for the original interpreter.py
+while allowing gradual migration to the new modular architecture.
+"""
+
+import warnings
+
+# Import the original ValidationError for compatibility
+from .validators.base_validator import ValidationError
+
+# Re-export ValidationError at module level for backward compatibility
+__all__ = ["ValidationError"]
+
+
+def deprecated_method(old_name: str, new_location: str):
+    """Decorator to mark methods as deprecated."""
+
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            warnings.warn(
+                f"{old_name} is deprecated. Use {new_location} instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+class LegacyContentTypeInterpreter:
+    """
+    Legacy wrapper for the original ContentTypeInterpreter interface.
+
+    This class provides the same interface as the original while delegating
+    to the new modular components. It includes deprecation warnings to guide
+    users toward the new architecture.
+    """
+
+    def __init__(self):
+        from .interpreter_refactored import ContentTypeInterpreter
+
+        self._interpreter = ContentTypeInterpreter()
+
+    @deprecated_method("LegacyContentTypeInterpreter", "ContentTypeInterpreter")
+    def detect_content_type(self, content: str | bytes, file_extension: str = None):
+        """Legacy method - use ContentTypeInterpreter.detect_content_type instead."""
+        return self._interpreter.detect_content_type(content, file_extension)
+
+    @deprecated_method(
+        "LegacyContentTypeInterpreter.validate_content", "validation_registry.validate"
+    )
+    def validate_content(self, content: str | bytes) -> None:
+        """Legacy method - use validation_registry.validate instead."""
+        return self._interpreter.validate_content(content)
+
+    # Add other legacy methods as needed...

clm/layer0/model/dictionary.py

@@ -0,0 +1,46 @@
+from enum import Enum
+from pathlib import Path
+
+import yaml
+
+
+class DataSemanticType(str, Enum):
+    StringValue = "StringValue"
+    PathReference = "PathReference"
+    UrlReference = "UrlReference"
+    HashPointer = "HashPointer"
+
+
+class ClmReservedWords:
+    """Python implementation of the Metamodel Dictionary."""
+
+    def __init__(
+        self,
+        version: str,
+        description: str,
+        valid_types: list[str],
+        dictionary: dict[str, DataSemanticType],
+    ):
+        self.version = version
+        self.description = description
+        self.valid_types = valid_types
+        self.dictionary = dictionary
+
+    @classmethod
+    def load_from_file(cls, path: str | Path) -> "ClmReservedWords":
+        """Loads the explicitly defined Reserved Words schema configuration mapping into Python natively."""
+        with open(path, encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        return cls(
+            version=data.get("version", "0.0.0"),
+            description=data.get("description", ""),
+            valid_types=data.get("valid_types", []),
+            dictionary={
+                k: DataSemanticType(v) for k, v in data.get("dictionary", {}).items()
+            },
+        )
+
+    def lookup(self, key: str) -> DataSemanticType:
+        """Retrieve the data type for a given domain key, defaulting to a regular StringValue if unknown."""
+        return self.dictionary.get(key, DataSemanticType.StringValue)

clm/layer0/model/dots.py

@@ -0,0 +1,331 @@
+"""DOTS Vocabulary Types - Double Operadic Theory of Systems.
+
+This module defines the core vocabulary from the DOTS framework,
+which provides a minimal, mathematically grounded language for describing
+any compositional system, including MVP Cards architecture.
+
+DOTS Vocabulary
+===============
+
+The DOTS vocabulary consists of 9 fundamental terms that form a
+complete language for describing compositional systems:
+
++----------+--------------------+-----------------------------+
+| Term     | Definition         | MVP Cards Mapping           |
++----------+--------------------+-----------------------------+
+| Arena    | Container for IO   | VCard (boundary/gatekeeper) |
+| Lens     | Bidirectional map  | PCard (CLM transformations) |
+| Chart    | Category positions | CLM YAML specification      |
+| Target   | Design space       | CLM Abstract/Balanced/Conc  |
+| Carrier  | Actual systems     | MCard (content-addressable) |
+| Tight    | Vertical/∧ ops     | Prerequisite dependencies   |
+| Loose    | Horizontal/∨ ops   | Alternative options         |
+| Action   | Morphism in Car    | CardCollection.add()        |
+| Unit     | Identity element   | Empty MCard / null content  |
++----------+--------------------+-----------------------------+
+
+Polynomial Functor Foundation
+=============================
+
+The DOTS vocabulary is grounded in **polynomial functor algebra**:
+
+    p(y) = Σ(s:S) y^{d(s)}
+
+Where:
+- S = positions (types/states)
+- d(s) = directions from each position (transitions)
+
+This maps to MVP Cards as:
+
+    MVP(y) = Interface × y^Operations
+
+Which expresses: "For each interface, we have a set of possible operations."
+
+See Also:
+    - docs/WorkingNotes/Hub/Theory/Integration/DOTS Vocabulary as Efficient Representation for ABC Curriculum.md
+    - docs/WorkingNotes/Permanent/Projects/PKC Kernel/MCard.md
+    - docs/WorkingNotes/Permanent/Projects/PKC Kernel/PCard.md
+    - docs/WorkingNotes/Permanent/Projects/PKC Kernel/VCard.md
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class DOTSRole(Enum):
+    """The 9 fundamental DOTS vocabulary terms.
+
+    From the Double Operadic Theory of Systems, these terms provide
+    a complete language for describing any compositional system.
+    """
+
+    CARRIER = "Carrier"
+    """The category of actual systems (data artifacts).
+
+    In MVP Cards: MCard instances - immutable, content-addressable objects.
+    Mathematically: Objects and morphisms in Car(S).
+    """
+
+    LENS = "Lens"
+    """Bidirectional transformations between systems.
+
+    In MVP Cards: PCard transformations that map input → output.
+    Mathematically: Chart composed with an arena map.
+    """
+
+    CHART = "Chart"
+    """Category positions and interface definitions.
+
+    In MVP Cards: CLM YAML specifications defining the transformation.
+    Mathematically: Functor specifying positions in the Target category.
+    """
+
+    ARENA = "Arena"
+    """Container for input/output operations; the system boundary.
+
+    In MVP Cards: VCard - the sovereign gatekeeper for all IO.
+    Mathematically: A polynomial functor p with sum and product types.
+    """
+
+    ACTION = "Action"
+    """Morphisms in the Carrier category; state transitions.
+
+    In MVP Cards: CardCollection.add() - produces new MCards.
+    Mathematically: Loose(I) ⊛ Car(S) → Car(S).
+    """
+
+    TARGET = "Target"
+    """The design space; categories of possible interfaces.
+
+    In MVP Cards: CLM Abstract/Balanced/Concrete triad.
+    Mathematically: Category of polynomials Poly.
+    """
+
+    TIGHT = "Tight"
+    """Vertical composition; prerequisite dependencies (∧).
+
+    In MVP Cards: Sequential execution, dependency chains.
+    Mathematically: Product types, conjunction.
+    """
+
+    LOOSE = "Loose"
+    """Horizontal composition; alternative options (∨).
+
+    In MVP Cards: Parallel execution, polyglot consensus.
+    Mathematically: Sum types, disjunction.
+    """
+
+    UNIT = "Unit"
+    """Identity element; the starting point.
+
+    In MVP Cards: Empty collection, null content.
+    Mathematically: Terminal object 1 in the category.
+    """
+
+
+class EOSRole(Enum):
+    """Experimental-Operational Symmetry roles.
+
+    Each MVP Card type plays a specific role in maintaining the
+    symmetry between experimental (development) and operational
+    (production) environments.
+    """
+
+    INVARIANT_CONTENT = "InvariantContent"
+    """MCard: The Galois root - same content = same hash everywhere.
+
+    This is the "Joint Reality" P(H,E) = P(E,H) in Bayesian terms.
+    Hash computation is a pure function with no side effects.
+    """
+
+    GENERATIVE_LENS = "GenerativeLens"
+    """PCard: The dynamic lens - pure function transformations.
+
+    PCard transformations must be deterministic and reproducible.
+    Same input + same PCard = same output in any environment.
+    """
+
+    SOVEREIGN_DECISION = "SovereignDecision"
+    """VCard: The gatekeeper - authorized IO and value exchange.
+
+    VCard manages credentials, authorization, and controlled side effects.
+    Only VCard can break symmetry; it documents when and why.
+    """
+
+
+class CardPlane(Enum):
+    """MVP Cards architectural planes.
+
+    The triadic architecture separates concerns into three planes,
+    each with distinct responsibilities and DOTS vocabulary mappings.
+    """
+
+    DATA = "Data"
+    """MCard plane: Immutable, content-addressable storage.
+
+    DOTS Role: Carrier
+    Responsibilities: Store, hash, retrieve content
+    """
+
+    CONTROL = "Control"
+    """PCard plane: Polynomial functor composition.
+
+    DOTS Role: Lens + Chart
+    Responsibilities: Transform, compose, verify
+    """
+
+    APPLICATION = "Application"
+    """VCard plane: Value exchange and authorization.
+
+    DOTS Role: Arena + Action
+    Responsibilities: AuthN/AuthZ, IO gatekeeper, credentials
+    """
+
+
+@dataclass
+class PolynomialFunctor:
+    """Representation of a polynomial functor p(y) = Σ(s:S) y^{d(s)}.
+
+    Polynomial functors are the mathematical foundation for DOTS.
+    They capture the notion of "interface + operations" in a precise way.
+
+    Attributes:
+        positions: List of position names (S = set of states/types)
+        directions: Dict mapping position → list of direction names
+
+    Example:
+        A simple boolean functor:
+        >>> p = PolynomialFunctor(
+        ...     positions=['true', 'false'],
+        ...     directions={'true': ['stay', 'flip'], 'false': ['stay', 'flip']}
+        ... )
+    """
+
+    positions: list[str]
+    directions: dict  # position → list of directions
+
+
+@dataclass
+class DOTSMetadata:
+    """DOTS vocabulary metadata for a card.
+
+    This dataclass captures the DOTS role information for any card,
+    enabling programmatic identification of the card's role in the
+    compositional system.
+
+    Attributes:
+        role: Primary DOTS role (Carrier, Lens, Chart, Arena, etc.)
+        eos_role: Experimental-Operational Symmetry role
+        plane: MVP Cards architectural plane
+        polynomial: Optional polynomial functor representation
+        tight_refs: Prerequisite hash references (vertical composition)
+        loose_refs: Alternative hash references (horizontal composition)
+    """
+
+    role: DOTSRole
+    eos_role: EOSRole | None
+    plane: CardPlane
+    polynomial: PolynomialFunctor | None = None
+    tight_refs: list[str] | None = None
+    loose_refs: list[str] | None = None
+
+
+def create_mcard_dots_metadata(
+    tight_refs: list[str] | None = None, loose_refs: list[str] | None = None
+) -> DOTSMetadata:
+    """Create DOTS metadata for an MCard.
+
+    MCard is always a CARRIER in the DATA plane with INVARIANT_CONTENT role.
+
+    Args:
+        tight_refs: Optional prerequisite hash references
+        loose_refs: Optional alternative hash references
+
+    Returns:
+        DOTSMetadata configured for MCard
+
+    Example:
+        >>> meta = create_mcard_dots_metadata()
+        >>> meta.role
+        <DOTSRole.CARRIER: 'Carrier'>
+        >>> meta.plane
+        <CardPlane.DATA: 'Data'>
+    """
+    return DOTSMetadata(
+        role=DOTSRole.CARRIER,
+        eos_role=EOSRole.INVARIANT_CONTENT,
+        plane=CardPlane.DATA,
+        polynomial=PolynomialFunctor(
+            positions=["content"], directions={"content": ["hash", "get", "text"]}
+        ),
+        tight_refs=tight_refs,
+        loose_refs=loose_refs,
+    )
+
+
+def create_pcard_dots_metadata(
+    spec_hash: str | None = None,
+    tight_refs: list[str] | None = None,
+    loose_refs: list[str] | None = None,
+) -> DOTSMetadata:
+    """Create DOTS metadata for a PCard.
+
+    PCard is LENS + CHART in the CONTROL plane with GENERATIVE_LENS role.
+
+    Args:
+        spec_hash: Optional hash of the CLM specification
+        tight_refs: Sequential execution dependencies
+        loose_refs: Parallel/polyglot alternatives
+
+    Returns:
+        DOTSMetadata configured for PCard
+    """
+    return DOTSMetadata(
+        role=DOTSRole.LENS,
+        eos_role=EOSRole.GENERATIVE_LENS,
+        plane=CardPlane.CONTROL,
+        polynomial=PolynomialFunctor(
+            positions=["abstract", "balanced", "concrete"],
+            directions={
+                "abstract": ["specification"],
+                "balanced": ["parse", "verify", "execute"],
+                "concrete": ["code", "runtime", "result"],
+            },
+        ),
+        tight_refs=tight_refs or ([spec_hash] if spec_hash else None),
+        loose_refs=loose_refs,
+    )
+
+
+def create_vcard_dots_metadata(
+    credential_hash: str | None = None,
+    tight_refs: list[str] | None = None,
+    loose_refs: list[str] | None = None,
+) -> DOTSMetadata:
+    """Create DOTS metadata for a VCard.
+
+    VCard is ARENA + ACTION in the APPLICATION plane with SOVEREIGN_DECISION role.
+
+    Args:
+        credential_hash: Optional hash of the credential/certificate
+        tight_refs: Authorization chain dependencies
+        loose_refs: Alternative authorization paths
+
+    Returns:
+        DOTSMetadata configured for VCard
+    """
+    return DOTSMetadata(
+        role=DOTSRole.ARENA,
+        eos_role=EOSRole.SOVEREIGN_DECISION,
+        plane=CardPlane.APPLICATION,
+        polynomial=PolynomialFunctor(
+            positions=["ingress", "egress", "internal"],
+            directions={
+                "ingress": ["authenticate", "authorize", "admit"],
+                "egress": ["sign", "encrypt", "emit"],
+                "internal": ["store", "retrieve", "delete"],
+            },
+        ),
+        tight_refs=tight_refs or ([credential_hash] if credential_hash else None),
+        loose_refs=loose_refs,
+    )

clm/layer0/model/event_producer.py

@@ -0,0 +1,88 @@
+import json
+
+from clm.cross_cutting.config.config_constants import (
+    COLLISION_EVENT_TYPE,
+    COLLISION_TIME,
+    CONTENT_SIZE,
+    DUPLICATE_EVENT_TYPE,
+    DUPLICATE_TIME,
+    FIRST_G_TIME,
+    HASH,
+    TYPE,
+    UPGRADED_FUNCTION,
+    UPGRADED_HASH,
+)
+from clm.layer0.model.card import MCard
+from clm.layer0.model.g_time import GTime
+from clm.layer0.model.hash.constants import HASH_ALGORITHM_HIERARCHY
+from clm.layer0.model.hash.enums import HashAlgorithm
+from clm.layer0.model.hash.validator import HashValidator
+
+
+def next_hash_function(current_hash_function: str | HashAlgorithm) -> str:
+    """Get the next hash function in the hierarchy.
+
+    Args:
+        current_hash_function: Current hash function name or enum
+
+    Returns:
+        str: Name of the next hash function to use
+    """
+    # Convert enum to string if needed
+    if isinstance(current_hash_function, HashAlgorithm):
+        current_hash_function = current_hash_function.value
+    elif isinstance(current_hash_function, str):
+        current_hash_function = current_hash_function.lower()
+
+    # Convert to HashAlgorithm enum
+    try:
+        current_algo = HashAlgorithm(current_hash_function)
+    except ValueError:
+        return HashAlgorithm.SHA1.value
+
+    # Get stronger algorithms for current algorithm
+    stronger_algos = HASH_ALGORITHM_HIERARCHY.get(current_algo, set())
+
+    # Return the first stronger algorithm, or SHA1 if none exist
+    for algo in [HashAlgorithm.SHA1, HashAlgorithm.SHA256, HashAlgorithm.SHA512]:
+        if algo in stronger_algos:
+            return algo.value
+
+    return HashAlgorithm.SHA1.value
+
+
+def compute_content_size(card: MCard) -> int:
+    """Compute the size of a card's content.
+
+    Args:
+        card: The card to compute size for
+
+    Returns:
+        int: Size of content in bytes
+    """
+    return len(card.content)
+
+
+def generate_collision_event(card: MCard) -> str:
+    """Generate a collision event for the given card."""
+    next_algo = next_hash_function(GTime.get_hash_function(card.g_time))
+    collision_event = {
+        TYPE: COLLISION_EVENT_TYPE,
+        HASH: str(card.hash),
+        FIRST_G_TIME: str(card.g_time),
+        COLLISION_TIME: str(card.g_time),
+        CONTENT_SIZE: len(card.content),
+        UPGRADED_FUNCTION: next_algo,
+        UPGRADED_HASH: HashValidator.compute_hash(card.content, next_algo),
+    }
+    return json.dumps(collision_event)
+
+
+def generate_duplication_event(card: MCard) -> str:
+    """Generate a duplication event for the given card."""
+    duplication_event = {
+        TYPE: DUPLICATE_EVENT_TYPE,
+        HASH: str(card.hash),
+        DUPLICATE_TIME: str(card.g_time),
+    }
+    return json.dumps(duplication_event)

clm/layer0/model/g_time.py

@@ -0,0 +1,89 @@
+from datetime import datetime, timezone
+
+from clm.layer0.model.hash.enums import HashAlgorithm
+
+
+class GTime:
+    @staticmethod
+    def stamp_now(
+        hash_function: str | HashAlgorithm, locale_or_did: str = "UTC"
+    ) -> str:
+        """Get current timestamp in ISO format with hash function and locale_or_did.
+        Format: ALGORITHM|TIMESTAMP|LOCALE_OR_DID
+        Representing the mathematical coordinate (a,b,c) for an event signature.
+        """
+        if hash_function is None:
+            raise ValueError("hash_function cannot be None")
+
+        # Convert string to HashAlgorithm if needed
+        if isinstance(hash_function, str):
+            try:
+                hash_function = HashAlgorithm(hash_function.lower())
+            except ValueError as e:
+                raise ValueError(f"Invalid hash function: {hash_function}") from e
+
+        return f"{hash_function.value}|{datetime.now(timezone.utc).isoformat()}|{locale_or_did}"
+
+    @staticmethod
+    def get_algorithm(string_value: str) -> HashAlgorithm:
+        """Get the hash algorithm from the formatted string (Coordinate 'a')."""
+        hash_function_str = string_value.split("|")[
+            0
+        ].lower()  # Get the part before the first '|'
+
+        try:
+            return HashAlgorithm(hash_function_str)
+        except ValueError as e:
+            raise ValueError(f"Invalid hash function: {hash_function_str}") from e
+
+    @staticmethod
+    def get_hash_function(string_value: str) -> HashAlgorithm:
+        """Alias for backward compatibility."""
+        return GTime.get_algorithm(string_value)
+
+    @staticmethod
+    def get_timestamp(string_value: str) -> str:
+        """Get the timestamp from the formatted string (Coordinate 'b')."""
+        return string_value.split("|")[1]
+
+    @staticmethod
+    def get_locale_or_did(string_value: str) -> str:
+        """Get the locale or DID from the formatted string (Coordinate 'c')."""
+        return string_value.split("|")[2]
+
+    @staticmethod
+    def get_region_code(string_value: str) -> str:
+        """Alias for backward compatibility."""
+        return GTime.get_locale_or_did(string_value)
+
+    @staticmethod
+    def is_valid_hash_function(hash_function: str | HashAlgorithm) -> bool:
+        """Check if the provided hash function is valid."""
+        if isinstance(hash_function, HashAlgorithm):
+            return True
+
+        if isinstance(hash_function, str):
+            try:
+                HashAlgorithm(hash_function.lower())
+                return True
+            except ValueError:
+                return False
+
+        return False
+
+    @staticmethod
+    def is_valid_region_code(region_code: str) -> bool:
+        """Check if the provided locale or region code is valid."""
+        return bool(region_code and isinstance(region_code, str))
+
+    @staticmethod
+    def is_iso_format(timestamp: str) -> bool:
+        """Check if the provided timestamp is in ISO format."""
+        try:
+            # Handle Z suffix for UTC (common in JS/ISO8601 but not supported by older python fromisoformat)
+            if timestamp.endswith("Z"):
+                timestamp = timestamp[:-1] + "+00:00"
+            datetime.fromisoformat(timestamp)
+            return True
+        except ValueError:
+            return False