clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/identity_guard.py

@@ -0,0 +1,348 @@
+"""
+Layer 1: Identity-First Zeroth Guard (DV-373-02).
+
+Enforces the Agentic Closure Theorem and Type Lattice root constraint:
+No action can occur in the CLM without verified cryptographic authorship.
+Every transition enforces a zeroth guard: V_identity = verifyIdentity(AgentDid).
+
+Supports:
+- EOA: Externally Owned Agent (Ed25519 DID key, e.g. did:key:z6M...)
+- CA: Contract Account / Multi-Sig (e.g. did:pkc:ca:..., did:clm:...)
+- Genesis Agent DID: did:key:z6MkhaXgBZDvotDkL5257faiz48Z8x28xhr554x4tp4MaEBx
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import yaml
+
+from clm.layer1.arrow_compiler import VCardGuard
+
+GENESIS_AGENT_DID = "did:key:z6MkhaXgBZDvotDkL5257faiz48Z8x28xhr554x4tp4MaEBx"
+
+# Regular expressions for valid DIDs
+# W3C did:key with base58btc Multicodec ed25519-pub (starts with z6M)
+_EOA_DID_REGEX = re.compile(r"^did:key:z6M[1-9A-HJ-NP-Za-km-z]{40,60}$")
+_CA_DID_REGEX = re.compile(r"^did:(pkc:ca|clm):[a-zA-Z0-9_\-\.:]+$")
+
+AgentClass = Literal["EOA", "CA", "UNKNOWN"]
+AgentType = Literal["eoa", "ca"]
+
+
+def classify_agent_did(did: str) -> AgentClass:
+    """Classifies a DID as an Externally Owned Agent (EOA) or Contract Account (CA)."""
+    if not did or not isinstance(did, str):
+        return "UNKNOWN"
+    if did == GENESIS_AGENT_DID or _EOA_DID_REGEX.match(did):
+        return "EOA"
+    if _CA_DID_REGEX.match(did) or did.startswith("did:pkc:ca:") or did.startswith("did:clm:"):
+        return "CA"
+    return "UNKNOWN"
+
+
+def verify_identity(did: str | None) -> bool:
+    """Verifies that a DID is cryptographically valid and authorizable."""
+    if not did:
+        return False
+    agent_class = classify_agent_did(did)
+    return agent_class in ("EOA", "CA")
+
+
+class IdentityVerificationError(Exception):
+    """Raised when an identity zeroth guard fails (T ∧ V_identity = ⊥)."""
+    pass
+
+
+def assert_identity_gate(did: str | None) -> None:
+    """Enforces the zeroth guard.
+
+    Raises IdentityVerificationError if did is missing or invalid.
+    """
+    if not verify_identity(did):
+        raise IdentityVerificationError(
+            f"V_identity check failed: DID '{did}' is not a valid EOA or CA authorization (T ∧ V_identity = ⊥)"
+        )
+
+
+def create_identity_zeroth_guard(agent_did: str | None = None) -> VCardGuard:
+    """Returns a VCardGuard checking the Zeroth Identity condition."""
+    target_did = agent_did or GENESIS_AGENT_DID
+    return VCardGuard(
+        name="V_identity_zeroth_guard",
+        predicate=lambda _: verify_identity(target_did),
+        error_message=f"Zeroth guard failed for DID '{target_did}'",
+    )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# W3C Agent Identity Schemas (EOA & CA Duality)
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class VerificationMethod:
+    """W3C standard verification method for declaring public keys."""
+
+    id: str
+    type: str
+    controller: str
+    publicKeyBase58: str
+
+
+@dataclass
+class AgentIdentity:
+    """Base class for all Agents in the system."""
+
+    did: str
+    agent_type: AgentType
+
+    def to_dict(self) -> dict[str, Any]:
+        raise NotImplementedError("Subclasses must implement to_dict")
+
+    def to_yaml(self) -> str:
+        return yaml.safe_dump(self.to_dict(), default_flow_style=False)
+
+
+@dataclass
+class EOAAgent(AgentIdentity):
+    """Externally Owned Agent (EOA)."""
+
+    agent_type: Literal["eoa"] = "eoa"
+    verification_methods: list[VerificationMethod] = field(default_factory=list)
+
+    def validate(self) -> None:
+        if not self.did.startswith("did:pkc:eoa:") and not self.did.startswith("did:key:"):
+            raise ValueError(f"EOA Data Schema Violation: Invalid EOA DID structure: {self.did}")
+        if len(self.verification_methods) == 0:
+            raise ValueError("EOA Data Schema Violation: At least one VerificationMethod is required for an EOA.")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "did": self.did,
+            "agent_type": self.agent_type,
+            "verification_methods": [
+                {
+                    "id": p.id,
+                    "type": p.type,
+                    "controller": p.controller,
+                    "publicKeyBase58": p.publicKeyBase58,
+                }
+                for p in self.verification_methods
+            ],
+        }
+
+
+@dataclass
+class ContractAgent(AgentIdentity):
+    """Contract Agent (CA)."""
+
+    agent_type: Literal["ca"] = "ca"
+    bound_clm_hash: str | None = None
+    controller_did: str | None = None
+
+    def validate(self) -> None:
+        if not self.did.startswith("did:pkc:ca:") and not self.did.startswith("did:clm:"):
+            raise ValueError(f"CA Data Schema Violation: Invalid CA DID structure: {self.did}")
+        if not self.bound_clm_hash:
+            raise ValueError("CA Data Schema Violation: ContractAgent MUST have a bound_clm_hash")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "did": self.did,
+            "agent_type": self.agent_type,
+            "bound_clm_hash": self.bound_clm_hash,
+            "controller_did": self.controller_did,
+        }
+
+
+def parse_identity(data_dict: dict[str, Any]) -> AgentIdentity:
+    """Parses a dictionary into typed EOA or CA schemas."""
+    agent_type = data_dict.get("agent_type")
+    if agent_type == "eoa":
+        methods = data_dict.get("verification_methods", [])
+        v_methods = [
+            VerificationMethod(
+                id=m["id"],
+                type=m["type"],
+                controller=m["controller"],
+                publicKeyBase58=m["publicKeyBase58"],
+            )
+            for m in methods
+        ]
+        agent = EOAAgent(did=data_dict["did"], verification_methods=v_methods)
+        agent.validate()
+        return agent
+    elif agent_type == "ca":
+        agent = ContractAgent(
+            did=data_dict["did"],
+            bound_clm_hash=data_dict.get("bound_clm_hash"),
+            controller_did=data_dict.get("controller_did"),
+        )
+        agent.validate()
+        return agent
+    raise ValueError(f"Unknown agent type mapping: {agent_type}")
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PCard Identity State Machine & Lineage
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class PCardState:
+    """State of a PCard Identity at a specific point in time."""
+
+    version: int
+    head: str
+    previous: str | None = None
+    timestamp: float = field(default_factory=time.time)
+
+
+@dataclass
+class PCardContract:
+    """Contract rules governing the PCard's evolution."""
+
+    upgradability: str = "uups"
+    rules: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PCardMetadata:
+    """Metadata for the PCard Identity."""
+
+    id: str
+    owner: str
+    created_at: float = field(default_factory=time.time)
+    description: str | None = None
+
+
+class PCardIdentity:
+    """Represents the persistent evolutionary identity of a Cubical Logic Model."""
+
+    def __init__(
+        self, metadata: PCardMetadata, state: PCardState, contract: PCardContract
+    ) -> None:
+        self.metadata = metadata
+        self.state = state
+        self.contract = contract
+        self.logger = logging.getLogger(__name__)
+
+    @classmethod
+    def create_genesis(
+        cls,
+        snapshot_hash: str,
+        owner: str,
+        pcard_id: str | None = None,
+        description: str | None = None,
+    ) -> "PCardIdentity":
+        pcard_id = pcard_id or str(uuid.uuid4())
+        metadata = PCardMetadata(id=pcard_id, owner=owner, description=description)
+        state = PCardState(version=1, head=snapshot_hash, previous=None)
+        contract = PCardContract()
+        return cls(metadata, state, contract)
+
+    def upgrade(self, new_snapshot_hash: str) -> None:
+        new_state = PCardState(
+            version=self.state.version + 1,
+            head=new_snapshot_hash,
+            previous=self.state.head,
+        )
+        self.state = new_state
+        self.logger.info(
+            f"PCard {self.metadata.id} upgraded to version {self.state.version}"
+        )
+
+    def fork(self, owner: str, description: str | None = None) -> "PCardIdentity":
+        new_id = str(uuid.uuid4())
+        metadata = PCardMetadata(
+            id=new_id,
+            owner=owner,
+            description=description or f"Fork of {self.metadata.id}",
+        )
+        state = PCardState(
+            version=1,
+            head=self.state.head,
+            previous=None,
+        )
+        contract = PCardContract()
+        self.logger.info(f"PCard {self.metadata.id} forked to {new_id}")
+        return PCardIdentity(metadata, state, contract)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": "PCard",
+            "metadata": {
+                "id": self.metadata.id,
+                "owner": self.metadata.owner,
+                "created_at": self.metadata.created_at,
+                "description": self.metadata.description,
+            },
+            "state": {
+                "version": self.state.version,
+                "head": self.state.head,
+                "previous": self.state.previous,
+                "timestamp": self.state.timestamp,
+            },
+            "contract": {
+                "upgradability": self.contract.upgradability,
+                "rules": self.contract.rules,
+            },
+        }
+
+    def to_yaml(self) -> str:
+        return yaml.safe_dump(self.to_dict(), default_flow_style=False)
+
+    @classmethod
+    def from_yaml(cls, yaml_content: str) -> "PCardIdentity":
+        data = yaml.safe_load(yaml_content)
+        if data.get("type") != "PCard":
+            raise ValueError("Invalid YAML: type must be 'PCard'")
+
+        metadata_data = data.get("metadata", {})
+        metadata = PCardMetadata(
+            id=metadata_data.get("id"),
+            owner=metadata_data.get("owner"),
+            created_at=metadata_data.get("created_at", time.time()),
+            description=metadata_data.get("description"),
+        )
+        state_data = data.get("state", {})
+        state = PCardState(
+            version=state_data.get("version"),
+            head=state_data.get("head"),
+            previous=state_data.get("previous"),
+            timestamp=state_data.get("timestamp", time.time()),
+        )
+        contract_data = data.get("contract", {})
+        contract = PCardContract(
+            upgradability=contract_data.get("upgradability", "uups"),
+            rules=contract_data.get("rules", []),
+        )
+        return cls(metadata, state, contract)
+
+
+__all__ = [
+    "GENESIS_AGENT_DID",
+    "AgentClass",
+    "AgentType",
+    "classify_agent_did",
+    "verify_identity",
+    "IdentityVerificationError",
+    "assert_identity_gate",
+    "create_identity_zeroth_guard",
+    "VerificationMethod",
+    "AgentIdentity",
+    "EOAAgent",
+    "ContractAgent",
+    "parse_identity",
+    "PCardState",
+    "PCardContract",
+    "PCardMetadata",
+    "PCardIdentity",
+]
+

clm/layer1/matrix.py

@@ -0,0 +1,138 @@
+"""Layer 1: Integer Incidence Matrix & P-Invariant Nullspace Analysis.
+
+Canonical Path: kernel/scripts/clm/layer1/matrix.py
+Parity: Rust `src/layer1/matrix.rs`, TypeScript `src/layer1/matrix.ts`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from clm.layer0.math_utils import math_gcd, math_lcm, solve_nullspace
+from clm.layer0.types import PolynomialTerm, PrimeHash
+from clm.layer1.sparse_net import PrecomputedInvariants, SparseIncidenceMatrix
+
+__all__ = [
+    "math_gcd",
+    "math_lcm",
+    "solve_nullspace",
+    "IncidenceMatrix",
+    "PolynomialStructure",
+    "SparseIncidenceMatrix",
+    "PrecomputedInvariants",
+]
+
+
+
+class IncidenceMatrix:
+    """Integer Incidence Matrix D = D^+ - D^- for a Petri Net topology."""
+
+    def __init__(
+        self,
+        places: list[str],
+        transitions: list[str],
+        d_minus: list[list[int]],
+        d_plus: list[list[int]],
+        d: list[list[int]],
+    ) -> None:
+        self.places = places
+        self.transitions = transitions
+        self.d_minus = d_minus
+        self.d_plus = d_plus
+        self.d = d
+
+    @classmethod
+    def from_topology(cls, topo: dict[str, Any]) -> IncidenceMatrix:
+        """Constructs an IncidenceMatrix from a Petri net topology definition."""
+        places = [p["id"] for p in topo.get("places", [])]
+        transitions = [t["id"] for t in topo.get("transitions", [])]
+
+        place_to_idx = {pid: i for i, pid in enumerate(places)}
+
+        num_p = len(places)
+        num_t = len(transitions)
+
+        d_minus = [[0] * num_t for _ in range(num_p)]
+        d_plus = [[0] * num_t for _ in range(num_p)]
+
+        for j, t in enumerate(topo.get("transitions", [])):
+            for inp in t.get("inputs", []):
+                if inp in place_to_idx:
+                    d_minus[place_to_idx[inp]][j] += 1
+            for outp in t.get("outputs", []):
+                if outp in place_to_idx:
+                    d_plus[place_to_idx[outp]][j] += 1
+
+        d = [[0] * num_t for _ in range(num_p)]
+        for r in range(num_p):
+            for c in range(num_t):
+                d[r][c] = d_plus[r][c] - d_minus[r][c]
+
+        return cls(places, transitions, d_minus, d_plus, d)
+
+    def p_invariants(self) -> list[list[int]]:
+        """Solves x^T * D = 0^T for the rational/integer P-invariant basis."""
+        return solve_nullspace(self.d, len(self.places), len(self.transitions), transpose=True)
+
+    def verify_invariant(self, weights: list[int]) -> bool:
+        """Verifies if a weight vector x satisfies x^T * D = 0^T."""
+        if len(weights) != len(self.places):
+            return False
+        for t in range(len(self.transitions)):
+            s = sum(weights[p] * self.d[p][t] for p in range(len(self.places)))
+            if s != 0:
+                return False
+        return True
+
+
+@dataclass
+class PolynomialStructure:
+    """Represents the polynomial structure of a PCard (Layer 1).
+
+    F(X) = Sum(A_i * X^{B_i}) + C
+
+    Where:
+    - A_i: Abstract Specifications (Coefficients)
+    - B_i: Balanced Expectations (Exponents)
+    - C: Concrete Implementation (Constant/Base)
+    """
+
+    terms: list[PolynomialTerm] = field(default_factory=list)
+    constant: PrimeHash | None = None
+
+    def add_term(self, abstract_hash: str, balanced_hash: str) -> None:
+        """Add a term (A * X^B) to the polynomial."""
+        self.terms.append(
+            PolynomialTerm(
+                coefficient=PrimeHash(abstract_hash),
+                exponent=PrimeHash(balanced_hash),
+            )
+        )
+
+    def set_constant(self, concrete_hash: str) -> None:
+        """Set the constant term (C) - the Concrete Implementation."""
+        self.constant = PrimeHash(concrete_hash)
+
+    def compose(self, other: "PolynomialStructure") -> "PolynomialStructure":
+        """Compose this polynomial with another: (F * G)(X)."""
+        new_poly = PolynomialStructure()
+        new_poly.terms.extend(self.terms)
+        new_poly.terms.extend(other.terms)
+        new_poly.constant = other.constant or self.constant
+        return new_poly
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        return {
+            "terms": [
+                {
+                    "coefficient": str(t.coefficient),
+                    "exponent": str(t.exponent),
+                    "weight": t.weight,
+                }
+                for t in self.terms
+            ],
+            "constant": str(self.constant) if self.constant else None,
+        }
+