clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/model/card.py

@@ -0,0 +1,280 @@
+import logging
+
+from clm.layer0.model.g_time import GTime
+from clm.layer0.model.hash.validator import HashAlgorithm, HashValidator
+
+
+class MCard:
+    """MCard - Content-addressable data container (Data Plane).
+
+    DOTS Vocabulary Role: CARRIER
+    =============================
+
+    MCard is the **Carrier** in the Double Operadic Theory of Systems (DOTS).
+    - Each MCard is an **Object** in the Carrier category Car(S)
+    - Hash-links between MCards are **Morphisms** in Car(S)
+    - The Carrier is the category of all actual data/systems
+
+    EOS Role: Invariant Content (Galois Root)
+    =========================================
+
+    MCard provides the **Invariant Substrate** in Experimental-Operational Symmetry:
+    - `Hash(Content)` is a **pure function** with no side effects
+    - Same content in Dev = Same hash in Prod (environment-invariant)
+    - This is the "Joint Reality" P(H,E) = P(E,H) in Bayesian terms
+
+    MVP Cards Architecture: Data Plane
+    ===================================
+
+    ::
+
+        ┌───────────────────────────────────────────────────────┐
+        │               APPLICATION PLANE (VCard)               │
+        │     Value Exchange / AuthN/AuthZ / Sovereign Memory   │
+        └─────────────────────────┬─────────────────────────────┘
+                                  │ (Policy Triggers)
+        ┌─────────────────────────▼─────────────────────────────┐
+        │                CONTROL PLANE (PCard)                  │
+        │   Polynomial Functor Composition / Monadic Execution  │
+        └─────────────────────────┬─────────────────────────────┘
+                                  │ (Hash References)
+        ┌─────────────────────────▼─────────────────────────────┐
+        │                 DATA PLANE (MCard) ◀── YOU ARE HERE   │
+        │   Immutable, Content-Addressable Storage / Monad      │
+        └───────────────────────────────────────────────────────┘
+
+    The Empty Schema Principle
+    ==========================
+
+    MCard embodies the Empty Schema Principle from the Wordless Book:
+    - Schema contains NO domain-specific terms (only hash, content, g_time)
+    - Domain customization happens via data (INSERT), not schema changes
+    - Universal applicability: same structure for ANY domain
+
+    Functional Requirements (from design docs)
+    ==========================================
+
+    +--------+--------------------------------+----------------------------------+
+    | ID     | Requirement                    | Implementation                   |
+    +--------+--------------------------------+----------------------------------+
+    | M-1    | Content-addressable via hash   | self.hash = SHA-256(content)     |
+    | M-2    | CRD-only (no UPDATE)           | Immutable, no __setattr__        |
+    | M-3    | Include g_time for ordering    | self.g_time field                |
+    | M-4    | Human-readable content         | get_content(as_text=True)        |
+    | EOS-M1 | Hash is pure function          | No side effects in hash compute  |
+    | EOS-M2 | Content is immutable           | Content set once in __init__     |
+    +--------+--------------------------------+----------------------------------+
+
+    Attributes:
+        content (bytes): Raw bytes of the content (Carrier Object data)
+        hash (str): SHA-256 cryptographic hash (Carrier Object identity)
+        g_time (str): Global timestamp with algorithm identifier
+        hash_function (HashAlgorithm): The hash algorithm used
+
+    See Also:
+        - docs/WorkingNotes/Permanent/Projects/PKC Kernel/MCard.md
+        - docs/WorkingNotes/Hub/Theory/Integration/DOTS Vocabulary as Efficient Representation for ABC Curriculum.md
+    """
+
+    def __init__(
+        self,
+        content: str | bytes,
+        hash_function: str | HashAlgorithm = HashAlgorithm.get_default(),
+    ):
+        """Initialize an MCard with content.
+
+        Args:
+            content: The content to store. Can be string or bytes.
+
+        Raises:
+            ValueError: If content is None or empty
+        """
+        if content is None:
+            raise ValueError("Content cannot be None")
+
+        if hash_function is None:
+            raise ValueError("hash_function cannot be None")
+
+        if isinstance(content, str | bytes) and len(content) == 0:
+            raise ValueError("Content cannot be empty")
+
+        self.content = (
+            content if isinstance(content, bytes) else content.encode("utf-8")
+        )
+
+        self.hash_function = HashAlgorithm(hash_function)
+
+        # Compute and log the hash
+        self.hash = HashValidator.compute_hash(content, self.hash_function)
+        logging.debug(f"Computed hash for content: {self.hash}")
+
+        self.g_time = GTime.stamp_now(self.hash_function)
+
+        # Cache the content type
+        from clm.layer0.model.interpreter import get_interpreter
+
+        try:
+            self._content_type, _ = get_interpreter().detect_content_type(self.content)
+        except Exception as e:
+            logging.warning(f"Failed to detect content type: {e}")
+            self._content_type = "unknown"
+
+    def get_content(self, as_text: bool = False) -> bytes | str:
+        """Get the content.
+
+        Args:
+            as_text: If True, returns the content as a string (decoded from UTF-8).
+                    If False (default), returns raw bytes.
+
+        Returns:
+            The content as either bytes (default) or string, depending on the as_text parameter.
+        """
+        if as_text:
+            try:
+                return self.content.decode("utf-8")
+            except UnicodeDecodeError:
+                # Return a string representation of the bytes if UTF-8 decoding fails
+                return f"<binary data, length={len(self.content)}>"
+        return self.content
+
+    def __repr__(self) -> str:
+        hash_short = self.hash[:12] if self.hash else "None"
+        return f"MCard(hash={hash_short!r}…, content_type={self._content_type!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, MCard):
+            return NotImplemented
+        return self.hash == other.hash
+
+    def __hash__(self) -> int:
+        return hash(self.hash)
+
+    def get_hash(self) -> str:
+        """Compute and return the hash of the content."""
+        return self.hash
+
+    def get_g_time(self) -> str:
+        """Get the current GTime string computed from the current time."""
+        return self.g_time
+
+    def get_content_type(self):
+        """Get the content type of the MCard content."""
+        return self._content_type
+
+    def to_dict(self):
+        """Convert the MCard to a dictionary.
+
+        Returns:
+            dict: A dictionary representation of the MCard with content as string.
+        """
+        content = self.get_content()
+        if isinstance(content, str):
+            # Content is already decoded string
+            content_str = content
+        elif isinstance(content, bytes):
+            try:
+                # Attempt decoding, but keep original bytes if fails
+                content_str = content.decode("utf-8")
+            except UnicodeDecodeError:
+                content_str = f"<binary data, length={len(content)}>"
+        else:
+            content_str = str(content)
+
+        return {
+            "content": content_str,
+            "hash": self.get_hash(),
+            "g_time": self.get_g_time(),
+            "content_type": self.get_content_type(),
+        }
+
+    def to_display_dict(self) -> dict[str, str]:
+        """Convert the MCard to a display-friendly dictionary.
+
+        Returns:
+            dict: A dictionary with formatted fields for display:
+                - hash: The card's unique hash
+                - content_type: The type of content in the card
+                - created_at: Formatted creation timestamp
+                - content_preview: A preview of the card's content (first 50 chars)
+                - card_class: The class name of the card (for debugging)
+        """
+        try:
+            # Get content safely
+            content = self.get_content()
+            # Ensure we have a string for preview
+            if isinstance(content, str):
+                content_str = content
+            else:
+                content_str = str(content)
+
+            # Create preview
+            content_preview = content_str[:50] + (
+                "..." if len(content_str) > 50 else ""
+            )
+
+            # Format timestamp
+            created_at = self.get_g_time()
+            created_at_str = str(created_at)[:19] if created_at else "N/A"
+
+            return {
+                "hash": self.get_hash(),
+                "content_type": self.get_content_type() or "unknown",
+                "created_at": created_at_str,
+                "content_preview": content_preview,
+                "card_class": self.__class__.__name__,
+            }
+        except (AttributeError, TypeError, ValueError) as e:
+            logging.error(f"Error processing card for display: {e}")
+            return {}
+
+    def get_dots_metadata(
+        self, tight_refs: list[str] = None, loose_refs: list[str] = None
+    ):
+        """Get DOTS vocabulary metadata for this MCard.
+
+        Returns the DOTS role information that positions this MCard
+        in the Double Operadic Theory of Systems framework.
+
+        MCard is always a CARRIER object in the Data Plane.
+
+        Args:
+            tight_refs: Optional list of prerequisite MCard hashes (vertical composition)
+            loose_refs: Optional list of alternative MCard hashes (horizontal composition)
+
+        Returns:
+            DOTSMetadata describing this card's role.
+        """
+        from clm.layer0.model.dots import create_mcard_dots_metadata
+
+        return create_mcard_dots_metadata(tight_refs, loose_refs)
+
+
+class MCardFromData(MCard):
+    """An MCard subclass that initializes from existing hash and g_time."""
+
+    def __init__(self, content: bytes, hash_value: str, g_time_str: str):
+        """Initialize an MCard from pre-existing hash and g_time."""
+        if not isinstance(content, bytes):
+            raise TypeError(
+                "Content must be bytes when initializing from existing data."
+            )
+
+        if not hash_value:
+            raise ValueError("Hash value cannot be None or empty")
+
+        if not g_time_str:
+            raise ValueError("g_time string cannot be None or empty")
+
+        self.content = content
+        self.hash = hash_value
+        self.g_time = g_time_str  # Directly assign the provided g_time string
+        self.hash_function = GTime.get_hash_function(self.g_time)
+
+        # Cache the content type
+        from clm.layer0.model.interpreter import get_interpreter
+
+        try:
+            self._content_type, _ = get_interpreter().detect_content_type(self.content)
+        except Exception as e:
+            logging.warning(f"Failed to detect content type for MCardFromData: {e}")
+            self._content_type = "unknown"

clm/layer0/model/card_triad.py

@@ -0,0 +1,427 @@
+"""Card Triad Grounding in Layer 0 (Sprint 384 / DEL-384-01).
+
+Implements the irreducible computational foundation of the CLM OS kernel:
+- MCard: Σ-type (Data, Content-Addressed Identity, Value constant 1 -> X)
+- PCard: Π-type (Process, Dynamic Operator A -> B)
+- VCard: Id-type (Witness, Gating Commits X -> 2 / Boolean PCard)
+
+Conforms to:
+- docs/spec/20-architecture/card-triad-architecture.md
+- Leibnizian Monadology & Function-Number Duality
+- Empty Schema Principle & Parameterized Content Hashing
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from clm.cross_cutting.domain_types import (
+    AgentDid,
+    ContentHash,
+    HandleName,
+    MarkingHash,
+    PlaceId,
+    TransitionId,
+    make_agent_did,
+    make_content_hash,
+    make_handle_name,
+)
+
+
+def compute_canonical_serialized(payload: Any) -> str:
+    """Serialize payload to deterministic canonical JSON (sorted keys, compact separators, UTF-8 preserved)."""
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def compute_canonical_hash(payload: Any) -> str:
+    """Compute deterministic BLAKE3 content hash over canonical JSON preimage."""
+    from clm.layer0.utils import clm_hash_string
+
+    serialized = compute_canonical_serialized(payload)
+    return clm_hash_string(serialized)
+
+
+# ---------------------------------------------------------------------------
+# Core Triad: MCard (Σ-type)
+# ---------------------------------------------------------------------------
+
+
+class MCard(BaseModel):
+    """Universal immutable data entity and file system primitive (Σ-type / Carrier).
+
+    Normative Reference:
+        docs/spec/20-architecture/card-triad-architecture.md § 1.1 (Universal MCard Ontology)
+        docs/spec/20-architecture/system-architecture.md § 1.1 (Everything is an MCard)
+
+    Invariants:
+        INV-01 (Stateless Kenotic Purity): Zero disk writes or network access.
+        INV-09 (Cryptographic Content Addressing): Hash uniquely determines identity.
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    uri: str = ""
+    hash: ContentHash = Field(default=ContentHash(""))
+    payload: Any = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    author: AgentDid = Field(default=AgentDid("did:clm:system"))
+    sequence: int = 1
+
+    def __init__(self, content: Any = None, **kwargs: Any) -> None:
+        """Allow positional content MCard(content) or keyword initialization."""
+        if content is not None and not kwargs:
+            if isinstance(content, (str, bytes)):
+                from clm.layer0.utils import clm_hash_string
+
+                text = content.decode("utf-8") if isinstance(content, bytes) else content
+                h = clm_hash_string(text)
+                super().__init__(
+                    uri=f"mcard:{h[:16]}",
+                    hash=ContentHash(h),
+                    payload=content,
+                    author=AgentDid("did:clm:system"),
+                    sequence=1,
+                )
+                return
+            elif isinstance(content, dict):
+                digest = compute_canonical_hash(content)
+                super().__init__(
+                    uri=f"mcard:{digest[:16]}",
+                    hash=ContentHash(digest),
+                    payload=content,
+                    author=AgentDid("did:clm:system"),
+                    sequence=1,
+                )
+                return
+        super().__init__(**kwargs)
+
+    @classmethod
+    def create(
+        cls,
+        uri: str,
+        payload: Any,
+        author: AgentDid | str,
+        sequence: int = 1,
+        metadata: dict[str, Any] | None = None,
+    ) -> MCard:
+        digest = compute_canonical_hash(payload)
+        return cls(
+            uri=uri,
+            hash=make_content_hash(digest),
+            payload=payload,
+            metadata=metadata or {},
+            author=make_agent_did(str(author)),
+            sequence=sequence,
+        )
+
+    @property
+    def content(self) -> bytes | None:
+        """Compatibility property for algebraic consumers."""
+        if isinstance(self.payload, bytes):
+            return self.payload
+        if isinstance(self.payload, str):
+            return self.payload.encode("utf-8")
+        if self.payload is not None:
+            return compute_canonical_serialized(self.payload).encode("utf-8")
+        return None
+
+    @property
+    def g_time(self) -> str:
+        """Temporal coordinate compatibility property."""
+        return self.metadata.get("g_time", "sha256|1970-01-01T00:00:00Z|UTC")
+
+
+# ---------------------------------------------------------------------------
+# Core Triad: PCard (Π-type)
+# ---------------------------------------------------------------------------
+
+
+class InvariantPhase(str, Enum):
+    Precondition = "precondition"
+    Postcondition = "postcondition"
+    LoopInvariant = "loop_invariant"
+
+
+class CordisCoeffects(BaseModel):
+    """Declared coeffects (@Inject dependencies) for PCards."""
+
+    model_config = ConfigDict(frozen=True)
+
+    required_services: list[str] = Field(default_factory=list)
+    input_schema_uri: str | None = None
+    output_schema_uri: str | None = None
+    required_capabilities: list[str] = Field(default_factory=list)
+
+
+class PrimitivePCard(BaseModel):
+    """Zero-coeffect constant function: 1 -> X."""
+
+    model_config = ConfigDict(frozen=True)
+
+    mcard: MCard
+
+    def evaluate(self) -> MCard:
+        return self.mcard
+
+
+class DynamicPCard(BaseModel):
+    """Dynamic effectful computation: A -> B."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    code_hash: ContentHash
+    source_uri: str
+    coeffects: CordisCoeffects = Field(default_factory=CordisCoeffects)
+    signature: str
+
+
+class BooleanPCard(BaseModel):
+    """Boolean guard specialization returning Bool (X -> 2)."""
+
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    phase: InvariantPhase
+    expression: str
+    guarded_uri_pattern: str
+    coeffects: CordisCoeffects = Field(default_factory=CordisCoeffects)
+
+    def is_precondition(self) -> bool:
+        return self.phase == InvariantPhase.Precondition
+
+    def is_postcondition(self) -> bool:
+        return self.phase == InvariantPhase.Postcondition
+
+
+class PCardDefinition(BaseModel):
+    """Tagged polymorphic PCard definition."""
+
+    model_config = ConfigDict(frozen=True)
+
+    pcard_type: str = Field(pattern=r"^(primitive|dynamic|boolean)$")
+    primitive: PrimitivePCard | None = None
+    dynamic: DynamicPCard | None = None
+    boolean: BooleanPCard | None = None
+
+
+class PCard(BaseModel):
+    """PCard: Process / Dynamic Operator / Control Plane (Π-type).
+
+    Normative Reference:
+        docs/spec/20-architecture/card-triad-architecture.md § 1.1 (PCard & Lambda Abstractions)
+        docs/spec/40-behavior/baldwin_monadic_pcard_algebra.md
+
+    Invariants:
+        INV-02 (Function-Number Duality): Function ≅ Number†.
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    uri: str = ""
+    hash: ContentHash = Field(default=ContentHash(""))
+    pcard_type: str = "primitive"
+    definition: PCardDefinition | None = None
+    primitive: PrimitivePCard | None = None
+    dynamic: DynamicPCard | None = None
+    boolean: BooleanPCard | None = None
+    coeffects: CordisCoeffects = Field(default_factory=CordisCoeffects)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    sequence: int = 1
+
+    def __init__(self, content: Any = None, **kwargs: Any) -> None:
+        if content is not None and not kwargs:
+            if isinstance(content, PrimitivePCard):
+                super().__init__(
+                    uri=content.mcard.uri,
+                    hash=content.mcard.hash,
+                    pcard_type="primitive",
+                    primitive=content,
+                )
+                return
+            if isinstance(content, (str, bytes, dict)):
+                m = MCard(content)
+                prim = PrimitivePCard(mcard=m)
+                super().__init__(
+                    uri=m.uri,
+                    hash=m.hash,
+                    pcard_type="primitive",
+                    primitive=prim,
+                )
+                return
+        super().__init__(**kwargs)
+
+    def evaluate(self) -> MCard:
+        """Evaluate the PCard polynomial morphism."""
+        if self.primitive is not None:
+            return self.primitive.evaluate()
+        if self.definition is not None and self.definition.primitive is not None:
+            return self.definition.primitive.evaluate()
+        return MCard(uri=self.uri, hash=self.hash, payload=self.metadata)
+
+
+# ---------------------------------------------------------------------------
+# Core Triad: VCard (Id-type)
+# ---------------------------------------------------------------------------
+
+
+class BailVerdict(BaseModel):
+    """Verdict returned by invariant evaluation or speculative execution."""
+
+    model_config = ConfigDict(frozen=True)
+
+    passed: bool
+    reason: str = ""
+    invariant_code: str = ""
+    context_dump: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def pass_verdict(cls) -> BailVerdict:
+        return cls(passed=True)
+
+    @classmethod
+    def bail(
+        cls, reason: str, invariant_code: str = "", context_dump: dict[str, Any] | None = None
+    ) -> BailVerdict:
+        return cls(
+            passed=False,
+            reason=reason,
+            invariant_code=invariant_code,
+            context_dump=context_dump or {},
+        )
+
+
+class VCard(BaseModel):
+    """VCard: Invariant Verification Witness & Gating Primitive (Id-type).
+
+    Normative Reference:
+        docs/spec/20-architecture/card-triad-architecture.md § 1.1 (VCard as Boolean PCard X -> 2)
+        docs/spec/40-behavior/hoare_triple_composition_protocol.md
+
+    Invariants:
+        INV-03 (Hoare Sandwich): {V_pre} Action {V_post} with <1ms atomic rollback.
+
+    All VCards are implemented as a special kind of PCard that returns Bool as its outcome
+    (X -> 2 = {true, false}), determining whether the runtime commits the state transition
+    or triggers an atomic rollback via Cordis Bail Dispatch.
+    """
+
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    uri: str = ""
+    hash: ContentHash = Field(default=ContentHash(""))
+    gate_type: str = "dispatch"
+    result: str = "pass"
+    verdict: BailVerdict = Field(default_factory=BailVerdict.pass_verdict)
+    boolean_pcard: BooleanPCard | None = None
+    witness_proof: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    sequence: int = 1
+
+    def is_passed(self) -> bool:
+        return self.result == "pass" and self.verdict.passed
+
+
+# ---------------------------------------------------------------------------
+# Auxiliary Domain Models (Petri Net & Token Models)
+# ---------------------------------------------------------------------------
+
+
+class TokenModel(BaseModel):
+    """Immutable Colored Petri Net token representation."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    color: ContentHash = Field(description="Content hash representing token data")
+    carrier: str | None = Field(default=None, description="Carrier identifier for token routing")
+    timestamp: str | None = Field(default=None, description="ISO-8601 creation timestamp")
+
+
+class PlaceModel(BaseModel):
+    """Immutable Petri Net place specification."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: PlaceId
+    name: str = Field(description="Human-readable place name")
+    tokens: int = Field(default=0, ge=0, description="Non-negative token count")
+    current_color: ContentHash | None = Field(default=None, description="Active color if token present")
+
+
+class TransitionModel(BaseModel):
+    """Immutable Petri Net transition specification."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: TransitionId
+    name: str
+    inputs: list[PlaceId] = Field(default_factory=list)
+    outputs: list[PlaceId] = Field(default_factory=list)
+    condition: str | None = None
+
+
+class MarkingModel(BaseModel):
+    """Immutable Colored Petri Net marking state with bitemporal provenance."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    topology_hash: ContentHash
+    places: dict[PlaceId, int] = Field(default_factory=dict)
+    place_colors: dict[PlaceId, ContentHash] = Field(default_factory=dict)
+    parent_hash: ContentHash | None = None
+    fired_transition: TransitionId | None = None
+    sponsor_did: AgentDid
+    firer_did: AgentDid
+
+    @field_validator("sponsor_did", "firer_did")
+    @classmethod
+    def validate_did_prefix(cls, v: AgentDid) -> AgentDid:
+        if not str(v).startswith("did:"):
+            raise ValueError(f"Agent DID must start with 'did:', got '{v}'")
+        return v
+
+
+class CardModel(BaseModel):
+    """Content-addressed MCard/PCard/VCard domain model."""
+
+    model_config = ConfigDict(frozen=True)
+
+    hash: ContentHash
+    token_type: str = Field(pattern=r"^(mcard|pcard|vcard|token)$")
+    payload: dict[str, Any] = Field(default_factory=dict)
+    timestamp: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+__all__ = [
+    "AgentDid",
+    "BailVerdict",
+    "BooleanPCard",
+    "CardModel",
+    "ContentHash",
+    "CordisCoeffects",
+    "DynamicPCard",
+    "HandleName",
+    "InvariantPhase",
+    "MarkingHash",
+    "MarkingModel",
+    "MCard",
+    "PCard",
+    "PCardDefinition",
+    "PlaceId",
+    "PlaceModel",
+    "PrimitivePCard",
+    "TokenModel",
+    "TransitionId",
+    "TransitionModel",
+    "VCard",
+    "compute_canonical_hash",
+    "compute_canonical_serialized",
+    "make_agent_did",
+    "make_content_hash",
+    "make_handle_name",
+]