clm-kernel 0.0.0__py3-none-any.whl

clm/layer0/model/vcard_ext/__init__.py

@@ -0,0 +1,39 @@
+"""VCard Extension Types - Resource type definitions as pure data.
+
+This package provides modular resource type definitions that are loaded
+automatically into the VCard vocabulary. Each file exports resource type
+definitions as dictionaries or ResourceType dataclasses.
+
+Adding new resource types:
+1. Create a new .py file in this directory
+2. Define RESOURCE_TYPES dict with your type definitions
+3. The types are auto-registered on import
+
+Example:
+    # my_custom_types.py
+    RESOURCE_TYPES = {
+        "mytype": {
+            "name": "mytype",
+            "category": "custom",
+            "uri_template": "mytype://{identifier}",
+            "hash_template": "mytype:{identifier}",
+            "default_options": {"required": True}
+        }
+    }
+"""
+
+from .core import RESOURCE_REGISTRY, ResourceCategory, ResourceType
+from .network import RESOURCE_TYPES as NETWORK_TYPES
+from .observability import RESOURCE_TYPES as OBSERVABILITY_TYPES
+from .storage import RESOURCE_TYPES as STORAGE_TYPES
+from .vendors import RESOURCE_TYPES as VENDOR_TYPES
+
+# Auto-register all extension types
+for types_dict in [STORAGE_TYPES, NETWORK_TYPES, OBSERVABILITY_TYPES, VENDOR_TYPES]:
+    for name, type_def in types_dict.items():
+        if isinstance(type_def, dict):
+            RESOURCE_REGISTRY[name] = ResourceType(**type_def)
+        else:
+            RESOURCE_REGISTRY[name] = type_def
+
+__all__ = ["RESOURCE_REGISTRY", "ResourceType", "ResourceCategory"]

clm/layer0/model/vcard_ext/core.py

@@ -0,0 +1,60 @@
+"""Core resource types and base registry."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ResourceCategory(Enum):
+    """Categories of external resources (side effects)."""
+
+    ENVIRONMENT = "env"
+    FILESYSTEM = "file"
+    STORAGE = "storage"
+    NETWORK = "network"
+    OBSERVABILITY = "observability"
+    COMPUTE = "compute"
+    RANDOM = "random"
+
+
+@dataclass
+class ResourceType:
+    """Definition of a resource type in the registry."""
+
+    name: str  # Type identifier (e.g., "env", "sqlite", "grafana")
+    category: str  # Category string or ResourceCategory value
+    uri_template: str  # URI template with {placeholders}
+    hash_template: str  # Hash content template
+    default_options: dict[str, Any] = field(default_factory=dict)
+    arg_names: list = field(default_factory=list)  # Positional argument names
+
+
+# Core resource types that are always available
+RESOURCE_REGISTRY: dict[str, ResourceType] = {
+    # Environment
+    "env": ResourceType(
+        name="env",
+        category=ResourceCategory.ENVIRONMENT.value,
+        uri_template="env://{name}",
+        hash_template="env:{name}:{required}:{secret}",
+        default_options={"required": True, "secret": False},
+        arg_names=["name"],
+    ),
+    # Filesystem
+    "file": ResourceType(
+        name="file",
+        category=ResourceCategory.FILESYSTEM.value,
+        uri_template="file://{path}",
+        hash_template="file:{path}",
+        default_options={"mode": "read", "required": True},
+        arg_names=["path"],
+    ),
+    "directory": ResourceType(
+        name="directory",
+        category=ResourceCategory.FILESYSTEM.value,
+        uri_template="file://{path}/",
+        hash_template="dir:{path}",
+        default_options={"recursive": True},
+        arg_names=["path"],
+    ),
+}

clm/layer0/model/vcard_ext/network.py

@@ -0,0 +1,23 @@
+"""Network resource types - APIs and webhooks."""
+
+from .core import ResourceCategory, ResourceType
+
+# Network resource type definitions as pure data
+RESOURCE_TYPES = {
+    "api": ResourceType(
+        name="api",
+        category=ResourceCategory.NETWORK.value,
+        uri_template="{endpoint}",
+        hash_template="api:{method}:{endpoint}",
+        default_options={"type": "api", "method": "GET", "_preserve_uri": True},
+        arg_names=["endpoint"],
+    ),
+    "webhook": ResourceType(
+        name="webhook",
+        category=ResourceCategory.NETWORK.value,
+        uri_template="{endpoint}",
+        hash_template="webhook:{endpoint}",
+        default_options={"type": "webhook", "_preserve_uri": True},
+        arg_names=["endpoint"],
+    ),
+}

clm/layer0/model/vcard_ext/observability.py

@@ -0,0 +1,63 @@
+"""Observability resource types - Grafana LGTM Stack."""
+
+from .core import ResourceType
+
+# Observability resource type definitions as pure data
+RESOURCE_TYPES = {
+    "grafana": ResourceType(
+        name="grafana",
+        category="observability",
+        uri_template="grafana://{endpoint}",
+        hash_template="grafana:{endpoint}:{org_id}:{dashboard_uid}",
+        default_options={"type": "grafana", "org_id": None, "dashboard_uid": None},
+        arg_names=["endpoint"],
+    ),
+    "prometheus": ResourceType(
+        name="prometheus",
+        category="observability",
+        uri_template="prometheus://{endpoint}",
+        hash_template="prometheus:{endpoint}:{job_name}",
+        default_options={"type": "prometheus", "scrape_interval": 15},
+        arg_names=["endpoint"],
+    ),
+    "loki": ResourceType(
+        name="loki",
+        category="observability",
+        uri_template="loki://{endpoint}",
+        hash_template="loki:{endpoint}:{tenant_id}",
+        default_options={"type": "loki", "labels": {}},
+        arg_names=["endpoint"],
+    ),
+    "tempo": ResourceType(
+        name="tempo",
+        category="observability",
+        uri_template="tempo://{endpoint}",
+        hash_template="tempo:{endpoint}:{service_name}",
+        default_options={"type": "tempo", "sampling_rate": 1.0},
+        arg_names=["endpoint"],
+    ),
+    "faro": ResourceType(
+        name="faro",
+        category="observability",
+        uri_template="faro://{collector_url}",
+        hash_template="faro:{collector_url}:{app_name}:{environment}",
+        default_options={
+            "type": "faro",
+            "environment": "production",
+            "features": ["console", "errors", "web_vitals", "sessions"],
+        },
+        arg_names=["collector_url", "app_name"],
+    ),
+    "otlp": ResourceType(
+        name="otlp",
+        category="observability",
+        uri_template="otlp://{endpoint}",
+        hash_template="otlp:{endpoint}:{protocol}:{service_name}",
+        default_options={
+            "type": "otlp",
+            "protocol": "grpc",
+            "signals": ["traces", "metrics", "logs"],
+        },
+        arg_names=["endpoint"],
+    ),
+}

clm/layer0/model/vcard_ext/storage.py

@@ -0,0 +1,60 @@
+"""Storage resource types - databases and object storage."""
+
+from .core import ResourceCategory, ResourceType
+
+# Storage resource type definitions as pure data
+RESOURCE_TYPES = {
+    "sqlite": ResourceType(
+        name="sqlite",
+        category=ResourceCategory.STORAGE.value,
+        uri_template="sqlite://{path}",
+        hash_template="sqlite:{path}",
+        default_options={"engine": "sqlite", "required": True},
+        arg_names=["path"],
+    ),
+    "postgres": ResourceType(
+        name="postgres",
+        category=ResourceCategory.STORAGE.value,
+        uri_template="postgres://{connection}",
+        hash_template="postgres:{connection}",
+        default_options={"engine": "postgresql", "required": True},
+        arg_names=["connection"],
+    ),
+    "s3": ResourceType(
+        name="s3",
+        category=ResourceCategory.STORAGE.value,
+        uri_template="s3://{bucket}/{key}",
+        hash_template="s3:{bucket}/{key}",
+        default_options={"engine": "s3", "region": "us-east-1"},
+        arg_names=["bucket", "key"],
+    ),
+    # LiteFS: Distributed SQLite replication (Fly.io)
+    "litefs": ResourceType(
+        name="litefs",
+        category=ResourceCategory.STORAGE.value,
+        uri_template="litefs://{path}",
+        hash_template="litefs:{path}:{primary}",
+        default_options={
+            "engine": "litefs",
+            "primary": None,
+            "lease_key": None,
+            "required": True,
+        },
+        arg_names=["path"],
+    ),
+    # Turso: Edge SQLite (libSQL)
+    "turso": ResourceType(
+        name="turso",
+        category=ResourceCategory.STORAGE.value,
+        uri_template="libsql://{database}.turso.io",
+        hash_template="turso:{database}:{group}",
+        default_options={
+            "engine": "turso",
+            "group": "default",
+            "auth_token_env_var": "TURSO_AUTH_TOKEN",
+            "sync_url": None,
+            "required": True,
+        },
+        arg_names=["database"],
+    ),
+}

clm/layer0/model/vcard_ext/vendors.py

@@ -0,0 +1,211 @@
+"""Vendor-provisioned SaaS resource types.
+
+Third-party services organized by category:
+- Identity/Auth: Google, GitHub, Meta/Facebook
+- Messaging: WhatsApp, Line, WeChat, Telegram, Slack
+- Collaboration: Trello, Miro, Figma, LinkedIn
+"""
+
+from .core import ResourceType
+
+# Vendor/SaaS resource type definitions
+RESOURCE_TYPES = {
+    # =========================================================================
+    # Identity & Authentication Providers
+    # =========================================================================
+    "google": ResourceType(
+        name="google",
+        category="vendor",
+        uri_template="google://{service}/{resource}",
+        hash_template="google:{service}:{resource}:{project_id}",
+        default_options={
+            "type": "google",
+            "service": "oauth",  # oauth, drive, sheets, calendar, etc.
+            "auth_env_var": "GOOGLE_CLIENT_ID",
+            "required": True,
+        },
+        arg_names=["service", "resource"],
+    ),
+    "github": ResourceType(
+        name="github",
+        category="vendor",
+        uri_template="github://{owner}/{repo}",
+        hash_template="github:{owner}:{repo}:{ref}",
+        default_options={
+            "type": "github",
+            "ref": "main",
+            "auth_env_var": "GITHUB_TOKEN",
+            "required": True,
+        },
+        arg_names=["owner", "repo"],
+    ),
+    "meta": ResourceType(
+        name="meta",
+        category="vendor",
+        uri_template="meta://{app_id}/{service}",
+        hash_template="meta:{app_id}:{service}",
+        default_options={
+            "type": "meta",
+            "service": "graph",  # graph, login, messenger, instagram
+            "auth_env_var": "META_APP_SECRET",
+            "required": True,
+        },
+        arg_names=["app_id", "service"],
+    ),
+    # =========================================================================
+    # Messaging Platforms
+    # =========================================================================
+    "whatsapp": ResourceType(
+        name="whatsapp",
+        category="vendor",
+        uri_template="whatsapp://{phone_number_id}",
+        hash_template="whatsapp:{phone_number_id}:{business_id}",
+        default_options={
+            "type": "whatsapp",
+            "api_version": "v18.0",
+            "auth_env_var": "WHATSAPP_TOKEN",
+            "required": True,
+        },
+        arg_names=["phone_number_id"],
+    ),
+    "telegram": ResourceType(
+        name="telegram",
+        category="vendor",
+        uri_template="telegram://{bot_id}",
+        hash_template="telegram:{bot_id}",
+        default_options={
+            "type": "telegram",
+            "auth_env_var": "TELEGRAM_BOT_TOKEN",
+            "required": True,
+        },
+        arg_names=["bot_id"],
+    ),
+    "line": ResourceType(
+        name="line",
+        category="vendor",
+        uri_template="line://{channel_id}",
+        hash_template="line:{channel_id}",
+        default_options={
+            "type": "line",
+            "auth_env_var": "LINE_CHANNEL_ACCESS_TOKEN",
+            "required": True,
+        },
+        arg_names=["channel_id"],
+    ),
+    "wechat": ResourceType(
+        name="wechat",
+        category="vendor",
+        uri_template="wechat://{app_id}",
+        hash_template="wechat:{app_id}",
+        default_options={
+            "type": "wechat",
+            "auth_env_var": "WECHAT_APP_SECRET",
+            "required": True,
+        },
+        arg_names=["app_id"],
+    ),
+    "slack": ResourceType(
+        name="slack",
+        category="vendor",
+        uri_template="slack://{workspace}/{channel}",
+        hash_template="slack:{workspace}:{channel}",
+        default_options={
+            "type": "slack",
+            "auth_env_var": "SLACK_BOT_TOKEN",
+            "required": True,
+        },
+        arg_names=["workspace", "channel"],
+    ),
+    # =========================================================================
+    # Collaboration & Productivity
+    # =========================================================================
+    "trello": ResourceType(
+        name="trello",
+        category="vendor",
+        uri_template="trello://{board_id}",
+        hash_template="trello:{board_id}",
+        default_options={
+            "type": "trello",
+            "auth_env_var": "TRELLO_API_KEY",
+            "required": True,
+        },
+        arg_names=["board_id"],
+    ),
+    "miro": ResourceType(
+        name="miro",
+        category="vendor",
+        uri_template="miro://{board_id}",
+        hash_template="miro:{board_id}:{team_id}",
+        default_options={
+            "type": "miro",
+            "auth_env_var": "MIRO_ACCESS_TOKEN",
+            "required": True,
+        },
+        arg_names=["board_id"],
+    ),
+    "figma": ResourceType(
+        name="figma",
+        category="vendor",
+        uri_template="figma://{file_key}",
+        hash_template="figma:{file_key}:{node_id}",
+        default_options={
+            "type": "figma",
+            "node_id": None,
+            "auth_env_var": "FIGMA_ACCESS_TOKEN",
+            "required": True,
+        },
+        arg_names=["file_key"],
+    ),
+    "linkedin": ResourceType(
+        name="linkedin",
+        category="vendor",
+        uri_template="linkedin://{organization_id}",
+        hash_template="linkedin:{organization_id}",
+        default_options={
+            "type": "linkedin",
+            "auth_env_var": "LINKEDIN_ACCESS_TOKEN",
+            "required": True,
+        },
+        arg_names=["organization_id"],
+    ),
+    # =========================================================================
+    # Cloud Providers (Infrastructure)
+    # =========================================================================
+    "aws": ResourceType(
+        name="aws",
+        category="vendor",
+        uri_template="aws://{service}/{resource}",
+        hash_template="aws:{service}:{resource}:{region}",
+        default_options={
+            "type": "aws",
+            "region": "us-east-1",
+            "auth_env_var": "AWS_ACCESS_KEY_ID",
+            "required": True,
+        },
+        arg_names=["service", "resource"],
+    ),
+    "azure": ResourceType(
+        name="azure",
+        category="vendor",
+        uri_template="azure://{subscription}/{resource_group}/{resource}",
+        hash_template="azure:{subscription}:{resource_group}:{resource}",
+        default_options={
+            "type": "azure",
+            "auth_env_var": "AZURE_CLIENT_ID",
+            "required": True,
+        },
+        arg_names=["subscription", "resource_group", "resource"],
+    ),
+    "gcp": ResourceType(
+        name="gcp",
+        category="vendor",
+        uri_template="gcp://{project}/{service}/{resource}",
+        hash_template="gcp:{project}:{service}:{resource}",
+        default_options={
+            "type": "gcp",
+            "auth_env_var": "GOOGLE_APPLICATION_CREDENTIALS",
+            "required": True,
+        },
+        arg_names=["project", "service", "resource"],
+    ),
+}

clm/layer0/model/vcard_sandwich.py

@@ -0,0 +1,119 @@
+"""VCardSandwich builder for creating Verification VCard proofs."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from clm.layer0.model.card import MCard
+from clm.layer0.model.vcard import VCard
+
+
+class VCardSandwich:
+    """Builder methods for creating Verification VCard proofs (VCard Sandwich)."""
+
+    @staticmethod
+    def witness_precondition(
+        input_mcard: MCard,
+        hash_function: str = "sha256",
+        pcard_hash: str = "",
+        verification_evidence: dict[str, Any] | None = None,
+        chl_temporal: dict[str, Any] | None = None,
+    ) -> VCard:
+        verification: dict[str, Any] = {
+            "phase": "prep",
+            "input_hash": input_mcard.hash,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "status": "accepted",
+        }
+        if pcard_hash:
+            verification["pcard_hash"] = pcard_hash
+        if verification_evidence:
+            verification["clm_verification"] = verification_evidence
+
+        content: dict[str, Any] = {
+            "vcard": {
+                "version": "1.0",
+                "type": "precondition-witness",
+                "identity": {"subject_did": "did:ptr:system", "controller_pubkeys": []},
+                "verification": verification,
+                "gatekeeper": {"capabilities": []},
+                "external_refs": [],
+            }
+        }
+        if chl_temporal:
+            content["vcard"]["chl_temporal"] = chl_temporal
+        return VCard(json.dumps(content, sort_keys=True), hash_function=hash_function)
+
+    @staticmethod
+    def witness_postcondition(
+        output: Any,
+        pcard_hash: str = "",
+        hash_function: str = "sha256",
+        alignment_score: float | None = None,
+        invariants_preserved: bool = True,
+        execution_telemetry: dict[str, Any] | None = None,
+        chl_temporal: dict[str, Any] | None = None,
+    ) -> VCard:
+        if isinstance(output, MCard):
+            output_repr = output.hash
+        elif isinstance(output, dict):
+            output_repr = json.dumps(output, sort_keys=True, default=str)
+        else:
+            output_repr = str(output)
+
+        verification: dict[str, Any] = {
+            "phase": "post",
+            "pcard_hash": pcard_hash,
+            "output_repr": output_repr[:512],
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "status": "accepted",
+        }
+        if alignment_score is not None:
+            verification["correctness_measures"] = {
+                "alignment_score": alignment_score,
+                "invariants_preserved": invariants_preserved,
+                "alignment_threshold": 0.85,
+            }
+
+        content: dict[str, Any] = {
+            "vcard": {
+                "version": "1.0",
+                "type": "postcondition-witness",
+                "identity": {"subject_did": "did:ptr:system", "controller_pubkeys": []},
+                "verification": verification,
+                "gatekeeper": {"capabilities": []},
+                "external_refs": [],
+            }
+        }
+        if execution_telemetry:
+            content["vcard"]["execution_telemetry"] = execution_telemetry
+        if chl_temporal:
+            content["vcard"]["chl_temporal"] = chl_temporal
+        return VCard(json.dumps(content, sort_keys=True), hash_function=hash_function)
+
+    @staticmethod
+    def sandwich(
+        v_pre: VCard,
+        v_post: VCard,
+        pcard_hash: str = "",
+        hash_function: str = "sha256",
+    ) -> VCard:
+        content: dict[str, Any] = {
+            "vcard": {
+                "version": "1.0",
+                "type": "verification-sandwich",
+                "identity": {"subject_did": "did:ptr:system", "controller_pubkeys": []},
+                "verification": {
+                    "pcard_hash": pcard_hash,
+                    "v_pre_hash": v_pre.hash,
+                    "v_post_hash": v_post.hash,
+                    "timestamp": datetime.now(timezone.utc).isoformat(),
+                    "success": True,
+                },
+                "gatekeeper": {"capabilities": []},
+                "external_refs": [],
+            }
+        }
+        return VCard(json.dumps(content, sort_keys=True), hash_function=hash_function)