capacium-models 0.5.0__py3-none-any.whl

capacium_models/__init__.py

@@ -0,0 +1,66 @@
+"""Shared domain models for the Capacium ecosystem.
+
+Usage:
+    from capacium_models import Listing, TrustState, TrustMachine
+"""
+
+from .models import (
+    MCPClient,
+    MCPMetadata,
+    TrustTransition,
+    Listing,
+    Publisher,
+    Category,
+    Subcategory,
+    TagCount,
+    Collection,
+    ClaimRequest,
+    VerificationRecord,
+    SearchQuery,
+)
+from .trust import TrustState, TrustMachine, TRUST_BADGES, get_trust_badge
+from .keys import (
+    LICENSE_PUBLIC_KEYS,
+    UnknownLicenseKid,
+    get_license_public_key,
+    known_kids,
+)
+from .labels import (
+    RESOURCE_KIND_LABELS,
+    OPERATOR_TYPE_LABELS,
+    INSTALL_STATUS_LABELS,
+    get_kind_label,
+    get_operator_type_label,
+    get_install_status_label,
+)
+from .search import ExchangeSearch
+
+__all__ = [
+    "MCPClient",
+    "MCPMetadata",
+    "TrustState",
+    "TrustTransition",
+    "TrustMachine",
+    "Listing",
+    "Publisher",
+    "Category",
+    "Subcategory",
+    "TagCount",
+    "Collection",
+    "ClaimRequest",
+    "VerificationRecord",
+    "SearchQuery",
+    "ExchangeSearch",
+    "TRUST_BADGES",
+    "get_trust_badge",
+    "RESOURCE_KIND_LABELS",
+    "OPERATOR_TYPE_LABELS",
+    "INSTALL_STATUS_LABELS",
+    "get_kind_label",
+    "get_operator_type_label",
+    "get_install_status_label",
+    "LICENSE_PUBLIC_KEYS",
+    "UnknownLicenseKid",
+    "get_license_public_key",
+    "known_kids",
+]

capacium_models/keys.py

@@ -0,0 +1,123 @@
+"""License public-key registry for capacium-models consumers.
+
+Consumers verify license tokens (issued by capacium-exchange `LicenseService`)
+using Ed25519. The matching PRIVATE key lives ONLY in envctl on prod, under:
+
+    envctl get capacium-exchange CAPACIUM_LICENSE_SIGNING_KEY    # 64-hex private
+    envctl get capacium-exchange CAPACIUM_LICENSE_SIGNING_KID    # current kid
+
+This module holds the corresponding PUBLIC keys, indexed by `kid` (key
+identifier as embedded in license token payloads). Consumers use these to
+verify signatures locally without round-tripping to the Exchange.
+
+Key rotation lifecycle for a given kid:
+  - Active:     issues new tokens; PRIVATE held in envctl
+  - Retired:    no longer issues NEW tokens; OLD tokens still validate
+                (entry stays in this registry until last token expires)
+  - Removed:    entry deleted from registry; OLD tokens fail validation
+
+To add a new kid: append to LICENSE_PUBLIC_KEYS, bump the package version
+(minor bump — additive); ship as a new capacium-models release. NEVER
+remove an entry whose tokens may still be in circulation.
+
+DECISION-001 reference: license-signing keypair is DISTINCT from
+capability-signing keypair. kid namespace MUST start with `lic-`.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+# ── License public-key registry ───────────────────────────────────────────
+#
+# Format: dict[kid -> 64-char lowercase hex] (32 bytes Ed25519 public key)
+#
+# Each entry MUST match the private key currently set as
+# CAPACIUM_LICENSE_SIGNING_KEY in envctl on capacium-prod, under the
+# matching kid CAPACIUM_LICENSE_SIGNING_KID.
+
+LICENSE_PUBLIC_KEYS: Dict[str, str] = {
+    # ──────────────────────────────────────────────────────────────────────
+    # kid: lic-2026-q2-01
+    # Added: 2026-06-03 (initial v2 launch — corresponds to the FIRST
+    # Ed25519 keypair generated on maintainer workstation, private uploaded
+    # to envctl on capacium-prod)
+    # ──────────────────────────────────────────────────────────────────────
+    "lic-2026-q2-01": "8e5e33e1ab3676d239a1f89cded6afca9aca0e8ba24c3b4b50ad4b71ef84e978",
+}
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+
+class UnknownLicenseKid(KeyError):
+    """Raised when a license token's `kid` is not in the public-key registry.
+
+    Consumers MUST reject the token in this case (treat as invalid signature).
+    Receiving this exception is the signal to upgrade `capacium-models` to a
+    newer version that includes the missing kid.
+    """
+
+
+def get_license_public_key(kid: str) -> str:
+    """Return the 64-char hex public key for a license kid.
+
+    Args:
+        kid: Key identifier as embedded in license token payload.
+
+    Returns:
+        64-char lowercase hex string representing the Ed25519 public key.
+
+    Raises:
+        UnknownLicenseKid: when `kid` is not in `LICENSE_PUBLIC_KEYS`, OR
+            when its registered value is not a valid 64-char hex string
+            (e.g., still a placeholder, malformed registry entry).
+            Consumer code MUST reject the token in this case.
+    """
+    try:
+        pubkey = LICENSE_PUBLIC_KEYS[kid]
+    except KeyError as e:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} not in LICENSE_PUBLIC_KEYS. "
+            f"Known kids: {known_kids()}. "
+            f"Upgrade capacium-models to support newer kids."
+        ) from e
+    _validate_hex(kid, pubkey)
+    return pubkey
+
+
+def known_kids() -> List[str]:
+    """Return all registered kids, sorted newest-first (lexicographic reverse).
+
+    Naming convention `lic-YYYY-qN-NN` makes lex reverse equal to
+    chronological reverse.
+    """
+    return sorted(LICENSE_PUBLIC_KEYS.keys(), reverse=True)
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────
+
+
+def _validate_hex(kid: str, pubkey: str) -> None:
+    """Validate that `pubkey` is a 64-char lowercase hex string.
+
+    Raises UnknownLicenseKid (not ValueError) so consumers handling kid
+    lookup errors have a single exception type to catch.
+    """
+    if not isinstance(pubkey, str):
+        raise UnknownLicenseKid(
+            f"kid={kid!r} has non-string pubkey of type {type(pubkey).__name__}"
+        )
+    if len(pubkey) != 64:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} pubkey length is {len(pubkey)}, expected 64 hex chars. "
+            f"Likely placeholder — registry entry must be filled in before release."
+        )
+    try:
+        int(pubkey, 16)
+    except ValueError as e:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} pubkey is not valid hex: {e}. "
+            f"Registry entry may still contain a placeholder."
+        ) from e

capacium_models/labels.py

@@ -0,0 +1,75 @@
+"""Canonical label registries for all Capacium surfaces.
+
+These dicts serve as single sources of truth — all UIs, badges, APIs, and CLI
+surfaces derive their display labels from these exactly maps.
+"""
+
+RESOURCE_KIND_LABELS = {
+    "skill": "Skill",
+    "mcp-server": "MCP Server",
+    "bundle": "Bundle",
+    "tool": "Tool",
+    "prompt": "Prompt",
+    "template": "Template",
+    "workflow": "Workflow",
+    "connector-pack": "Connector Pack",
+    "operator": "Operator",
+    "checkpoint": "Checkpoint",
+    "policy": "Policy",
+    "resource": "Resource",
+}
+
+OPERATOR_TYPE_LABELS = {
+    "ai": "AI",
+    "human": "Human",
+    "hybrid": "Hybrid",
+}
+
+INSTALL_STATUS_LABELS = {
+    "not_installed": "Not Installed",
+    "installing": "Installing",
+    "installed": "Installed",
+    "failed": "Failed",
+    "update_available": "Update Available",
+    "removed": "Removed",
+}
+
+TRUST_BADGES = {
+    "discovered": "Discovered",
+    "pending_review": "Pending Review",
+    "verified": "Verified",
+    "signed": "Signed",
+    "deprecated": "Deprecated",
+}
+
+
+def get_kind_label(kind: str) -> str:
+    """Return the human-readable label for a capability kind.
+
+    Falls back to the raw string if the kind is unknown.
+    """
+    return RESOURCE_KIND_LABELS.get(kind, kind)
+
+
+def get_operator_type_label(op_type: str) -> str:
+    """Return the human-readable label for an operator type.
+
+    Falls back to the raw string if the type is unknown.
+    """
+    return OPERATOR_TYPE_LABELS.get(op_type, op_type)
+
+
+def get_install_status_label(status: str) -> str:
+    """Return the human-readable label for an install status.
+
+    Falls back to the raw string if the status is unknown.
+    """
+    return INSTALL_STATUS_LABELS.get(status, status)
+
+
+def get_trust_badge(state: str) -> str:
+    """Return the human-readable trust badge label for a trust state.
+
+    Falls back to the raw string if the state is unknown.
+    """
+    return TRUST_BADGES.get(state, state)

capacium_models/models.py

@@ -0,0 +1,389 @@
+"""Exchange Core domain models.
+
+Defines the central data structures for the Capacium Exchange:
+Listing, MCPMetadata, Publisher, Category, Subcategory, TagCount,
+Collection, ClaimRequest, VerificationRecord, TrustTransition, SearchQuery.
+"""
+
+import json
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class MCPClient(Enum):
+    CLAUDE_DESKTOP = "claude-desktop"
+    CLAUDE_CODE = "claude-code"
+    CURSOR = "cursor"
+    OPENCODE = "opencode"
+    CODEX = "codex"
+    CONTINUE = "continue"
+    WINDSURF = "windsurf"
+    GENERIC = "generic-mcp-client"
+
+
+@dataclass
+class MCPMetadata:
+    supported_clients: List[str] = field(default_factory=list)
+    transport: str = "stdio"
+    runtime: Optional[str] = None
+    hosted: bool = False
+    auth_model: Optional[str] = None
+    required_env_vars: List[str] = field(default_factory=list)
+    permission_scopes: List[str] = field(default_factory=list)
+    health_endpoint: Optional[str] = None
+    health_status: Optional[str] = None
+    last_health_check: Optional[str] = None
+    setup_command: Optional[str] = None
+    documentation_url: Optional[str] = None
+    command_examples: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MCPMetadata":
+        if data is None:
+            return cls()
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in known}
+        return cls(**filtered)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, text: str) -> "MCPMetadata":
+        if not text:
+            return cls()
+        return cls.from_dict(json.loads(text))
+
+
+@dataclass
+class TrustTransition:
+    from_state: str
+    to_state: str
+    reason: str = ""
+    triggered_by: str = "system"
+    timestamp: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TrustTransition":
+        return cls(**{k: v for k, v in data.items() if k in {
+            "from_state", "to_state", "reason", "triggered_by", "timestamp"
+        }})
+
+
+@dataclass
+class Listing:
+    id: str = ""
+    canonical_name: str = ""
+    package_type: str = "skill"
+
+    canonical_source_url: str = ""
+    source_urls: List[str] = field(default_factory=list)
+
+    short_description: str = ""
+    long_description: str = ""
+
+    trust_state: str = "discovered"
+    trust_history: List[Dict[str, Any]] = field(default_factory=list)
+
+    primary_category: str = "developer-tools"
+    subcategory: Optional[str] = None
+    tags: List[str] = field(default_factory=list)
+
+    publisher_id: Optional[str] = None
+
+    target_frameworks: List[str] = field(default_factory=list)
+
+    installability: str = "local-install"
+    install_reference: Optional[str] = None
+
+    license: Optional[str] = None
+
+    maturity: str = "experimental"
+
+    discovered_at: str = ""
+    indexed_at: Optional[str] = None
+    updated_at: str = ""
+
+    mcp_metadata: Optional[Dict[str, Any]] = None
+
+    installed_capability_id: Optional[int] = None
+
+    # -- GitHub Enrichment --
+    github_owner: Optional[str] = None
+    github_repo: Optional[str] = None
+    github_stars: int = 0
+    github_forks: int = 0
+    github_watchers: int = 0
+    github_license: Optional[str] = None
+    github_topics: List[str] = field(default_factory=list)
+    github_language: Optional[str] = None
+    github_description: Optional[str] = None
+    github_homepage: Optional[str] = None
+    github_default_branch: Optional[str] = None
+    github_created_at: Optional[str] = None
+    github_pushed_at: Optional[str] = None
+    github_updated_at: Optional[str] = None
+
+    # -- Document Model v2 --
+    source_repo: Optional[str] = None      # e.g. "anthropics/skills"
+    source_path: str = "/"                  # e.g. "skills/ai-ml/3d-cv-labeling"
+    repo_type: str = "unknown"             # single_skill | multi_skill | collection | mcp_server | unknown
+    skill_path: Optional[str] = None       # path to SKILL.md within repo
+    skill_name: Optional[str] = None       # parsed from SKILL.md frontmatter
+    skill_compatibility: Optional[Dict[str, Any]] = None  # from SKILL.md
+    skill_metadata: Optional[Dict[str, Any]] = None       # from SKILL.md
+
+    # -- Manifest --
+    manifest_raw: Optional[str] = None     # raw capability.yaml content
+    manifest_version: Optional[str] = None
+
+    # -- Capability IR --
+    capability_ir: Optional[Dict[str, Any]] = None   # framework-agnostic IR (JSONB)
+    adaptation_targets: List[str] = field(default_factory=list)  # ["mcp-server", "a2a-agent"]
+
+    # -- Capacium Trust --
+    fingerprint: Optional[str] = None
+    signature_value: Optional[str] = None
+    signature_public_key: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        now = datetime.now(timezone.utc).isoformat()
+        if not self.discovered_at:
+            self.discovered_at = now
+        if not self.updated_at:
+            self.updated_at = now
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Listing":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in known}
+        for list_field in ("source_urls", "tags", "target_frameworks", "trust_history", "github_topics", "adaptation_targets"):
+            if list_field in filtered and isinstance(filtered[list_field], str):
+                try:
+                    filtered[list_field] = json.loads(filtered[list_field])
+                except (json.JSONDecodeError, TypeError):
+                    filtered[list_field] = []
+        for dict_field in ("mcp_metadata", "skill_compatibility", "skill_metadata", "capability_ir"):
+            if dict_field in filtered and isinstance(filtered[dict_field], str):
+                try:
+                    filtered[dict_field] = json.loads(filtered[dict_field])
+                except (json.JSONDecodeError, TypeError):
+                    filtered[dict_field] = None
+        return cls(**filtered)
+
+    def get_mcp_metadata_obj(self) -> Optional[MCPMetadata]:
+        if self.mcp_metadata:
+            return MCPMetadata.from_dict(self.mcp_metadata)
+        return None
+
+
+@dataclass
+class Publisher:
+    id: str = ""
+    display_name: str = ""
+    slug: str = ""
+    primary_proof_type: str = "account"
+    primary_proof_value: str = ""
+    verified: bool = False
+    verified_at: Optional[str] = None
+    verification_method: Optional[str] = None
+    contact_url: Optional[str] = None
+    created_at: str = ""
+    updated_at: str = ""
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        now = datetime.now(timezone.utc).isoformat()
+        if not self.created_at:
+            self.created_at = now
+        if not self.updated_at:
+            self.updated_at = now
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Publisher":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class Category:
+    slug: str = ""
+    display_name: str = ""
+    description: str = ""
+    sort_order: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Category":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class Subcategory:
+    slug: str = ""
+    category_slug: str = ""
+    display_name: str = ""
+    sort_order: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Subcategory":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class TagCount:
+    tag: str = ""
+    count: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TagCount":
+        return cls(tag=data.get("tag", ""), count=data.get("count", 0))
+
+
+@dataclass
+class Collection:
+    id: str = ""
+    slug: str = ""
+    display_name: str = ""
+    description: str = ""
+    listing_ids: List[str] = field(default_factory=list)
+    curated_by: Optional[str] = None
+    created_at: str = ""
+    updated_at: str = ""
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        now = datetime.now(timezone.utc).isoformat()
+        if not self.created_at:
+            self.created_at = now
+        if not self.updated_at:
+            self.updated_at = now
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Collection":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        filtered = {k: v for k, v in data.items() if k in known}
+        if "listing_ids" in filtered and isinstance(filtered["listing_ids"], str):
+            try:
+                filtered["listing_ids"] = json.loads(filtered["listing_ids"])
+            except (json.JSONDecodeError, TypeError):
+                filtered["listing_ids"] = []
+        return cls(**filtered)
+
+
+@dataclass
+class ClaimRequest:
+    id: str = ""
+    listing_id: str = ""
+    publisher_id: str = ""
+    proof_type: str = "repo-file"
+    proof_value: str = ""
+    status: str = "pending"
+    submitted_at: str = ""
+    reviewed_at: Optional[str] = None
+    reviewed_by: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.submitted_at:
+            self.submitted_at = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ClaimRequest":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class VerificationRecord:
+    id: str = ""
+    listing_id: str = ""
+    method: str = "repo-token-file"
+    result: str = "pass"
+    details: str = ""
+    verified_at: str = ""
+    expires_at: Optional[str] = None
+    verifier: str = "system"
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.verified_at:
+            self.verified_at = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "VerificationRecord":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class SearchQuery:
+    text: Optional[str] = None
+    package_type: Optional[str] = None
+    category: Optional[str] = None
+    subcategory: Optional[str] = None
+    tags: Optional[List[str]] = None
+    trust_state: Optional[str] = None
+    min_trust_state: Optional[str] = None
+    publisher_id: Optional[str] = None
+    installability: Optional[str] = None
+    license: Optional[str] = None
+    maturity: Optional[str] = None
+    mcp_client: Optional[str] = None
+    mcp_transport: Optional[str] = None
+    mcp_hosted: Optional[bool] = None
+    limit: int = 50
+    offset: int = 0
+    sort_by: str = "relevance"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {k: v for k, v in asdict(self).items() if v is not None}
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SearchQuery":
+        known = {f.name for f in cls.__dataclass_fields__.values()}
+        return cls(**{k: v for k, v in data.items() if k in known})

capacium_models/search.py

@@ -0,0 +1,141 @@
+"""Faceted search engine for Exchange listings.
+
+Builds dynamic SQL WHERE clauses from SearchQuery facets.
+Supports text search, type/category/trust/tag/publisher/mcp-client filtering,
+sorting, and pagination.
+"""
+
+import sqlite3
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .models import Listing, SearchQuery
+from .trust import TrustState
+
+
+class ExchangeSearch:
+
+    def __init__(self, db_path: Optional[Path] = None):
+        if db_path is None:
+            db_path = Path.home() / ".capacium" / "registry.db"
+        self.db_path = db_path
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def search(self, query: SearchQuery) -> Tuple[List[Listing], int]:
+        conditions = []
+        params = []
+
+        if query.text:
+            conditions.append(
+                "(canonical_name LIKE ? OR short_description LIKE ? OR long_description LIKE ?)"
+            )
+            like = f"%{query.text}%"
+            params.extend([like, like, like])
+
+        if query.package_type:
+            conditions.append("package_type = ?")
+            params.append(query.package_type)
+
+        if query.category:
+            conditions.append("primary_category = ?")
+            params.append(query.category)
+
+        if query.subcategory:
+            conditions.append("subcategory = ?")
+            params.append(query.subcategory)
+
+        if query.trust_state:
+            conditions.append("trust_state = ?")
+            params.append(query.trust_state)
+
+        if query.min_trust_state:
+            try:
+                from .trust import normalize_legacy_state, LEGACY_STATE_MAP
+                normalized = normalize_legacy_state(query.min_trust_state)
+                min_state = TrustState(normalized)
+                valid_states = [
+                    s.value for s in TrustState.ordering()
+                    if s >= min_state
+                ]
+                # Include legacy aliases that map to valid states
+                for legacy, modern in LEGACY_STATE_MAP.items():
+                    if modern in valid_states and legacy not in valid_states:
+                        valid_states.append(legacy)
+                if valid_states:
+                    placeholders = ", ".join("?" for _ in valid_states)
+                    conditions.append(f"trust_state IN ({placeholders})")
+                    params.extend(valid_states)
+            except ValueError:
+                pass
+
+        if query.publisher_id:
+            conditions.append("publisher_id = ?")
+            params.append(query.publisher_id)
+
+        if query.installability:
+            conditions.append("installability = ?")
+            params.append(query.installability)
+
+        if query.license:
+            conditions.append("license = ?")
+            params.append(query.license)
+
+        if query.maturity:
+            conditions.append("maturity = ?")
+            params.append(query.maturity)
+
+        if query.tags:
+            for tag in query.tags:
+                conditions.append("tags LIKE ?")
+                params.append(f'%"{tag}"%')
+
+        if query.mcp_client:
+            conditions.append("mcp_metadata LIKE ?")
+            params.append(f'%"{query.mcp_client}"%')
+
+        if query.mcp_transport:
+            conditions.append("mcp_metadata LIKE ?")
+            params.append(f'%"transport": "{query.mcp_transport}"%')
+
+        if query.mcp_hosted is not None:
+            hosted_str = "true" if query.mcp_hosted else "false"
+            conditions.append("mcp_metadata LIKE ?")
+            params.append(f'%"hosted": {hosted_str}%')
+
+        where = ""
+        if conditions:
+            where = " WHERE " + " AND ".join(conditions)
+
+        conn = self._connect()
+        try:
+            count_row = conn.execute(
+                f"SELECT count(*) FROM listings{where}", params
+            ).fetchone()
+            total_count = count_row[0] if count_row else 0
+
+            sort_map = {
+                "name": "canonical_name ASC",
+                "trust": "trust_state ASC",
+                "updated": "updated_at DESC",
+                "relevance": "updated_at DESC",
+            }
+            order_by = sort_map.get(query.sort_by, "updated_at DESC")
+
+            full_query = f"SELECT * FROM listings{where} ORDER BY {order_by} LIMIT ? OFFSET ?"
+            params.extend([query.limit, query.offset])
+
+            rows = conn.execute(full_query, params).fetchall()
+            listings = [Listing.from_dict(dict(row)) for row in rows]
+
+            return listings, total_count
+        finally:
+            conn.close()
+
+    def search_simple(self, text: str, limit: int = 50) -> List[Listing]:
+        q = SearchQuery(text=text, limit=limit)
+        listings, _ = self.search(q)
+        return listings

capacium_models/trust.py

@@ -0,0 +1,211 @@
+"""TrustState machine for Exchange listings.
+ 
+Enforces valid state transitions, records history, and validates entry criteria.
+ 
+v2.1: Unified 5-state model (discovered → pending_review → verified → signed → deprecated).
+Legacy states (indexed, claimed, audited) are mapped via normalize_legacy_state().
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Dict, List
+
+from .models import Listing, TrustTransition
+
+
+class TrustState(str, Enum):
+    DISCOVERED = "discovered"          # Found by crawler, minimal validation
+    PENDING_REVIEW = "pending_review"  # Schema validated, composite score computed (formerly "audited")
+    VERIFIED = "verified"              # Publisher claimed and ownership verified
+    SIGNED = "signed"                  # Cryptographic signature present and valid
+    DEPRECATED = "deprecated"          # End-of-life, superseded, or abandoned
+
+    @classmethod
+    def ordering(cls) -> List["TrustState"]:
+        return [
+            cls.DISCOVERED,
+            cls.PENDING_REVIEW,
+            cls.VERIFIED,
+            cls.SIGNED,
+            cls.DEPRECATED,
+        ]
+
+    def __lt__(self, other):
+        if self.__class__ is other.__class__:
+            ordering = self.ordering()
+            return ordering.index(self) < ordering.index(other)
+        return NotImplemented
+
+    def __gt__(self, other):
+        if self.__class__ is other.__class__:
+            ordering = self.ordering()
+            return ordering.index(self) > ordering.index(other)
+        return NotImplemented
+
+    def __ge__(self, other):
+        if self.__class__ is other.__class__:
+            ordering = self.ordering()
+            return ordering.index(self) >= ordering.index(other)
+        return NotImplemented
+
+    def __le__(self, other):
+        if self.__class__ is other.__class__:
+            ordering = self.ordering()
+            return ordering.index(self) <= ordering.index(other)
+        return NotImplemented
+
+
+# Legacy state mapping for backward compatibility
+LEGACY_STATE_MAP: Dict[str, str] = {
+    "indexed": "pending_review",
+    "claimed": "verified",
+    "audited": "pending_review",  # v1.0 → v2.1 migration
+}
+
+
+def normalize_legacy_state(state: str) -> str:
+    """Map old trust states to current model.
+
+    indexed/audited → pending_review, claimed → verified.
+    All other states pass through unchanged.
+    """
+    return LEGACY_STATE_MAP.get(state, state)
+
+
+class TrustTransitionError(Exception):
+    pass
+
+
+VALID_TRANSITIONS = {
+    TrustState.DISCOVERED: {TrustState.PENDING_REVIEW},
+    TrustState.PENDING_REVIEW: {TrustState.VERIFIED, TrustState.DISCOVERED},
+    TrustState.VERIFIED: {TrustState.SIGNED, TrustState.PENDING_REVIEW},
+    TrustState.SIGNED: {TrustState.VERIFIED, TrustState.DEPRECATED},
+    TrustState.DEPRECATED: {TrustState.PENDING_REVIEW},
+}
+
+
+class TrustMachine:
+
+    @staticmethod
+    def normalize_legacy_state(state: str) -> str:
+        """Map old trust states to new ones (convenience wrapper)."""
+        return normalize_legacy_state(state)
+
+    @staticmethod
+    def can_transition(from_state: TrustState, to_state: TrustState) -> bool:
+        allowed = VALID_TRANSITIONS.get(from_state, set())
+        return to_state in allowed
+
+    @staticmethod
+    def validate_entry_criteria(listing: Listing, target_state: TrustState) -> list:
+        errors = []
+
+        if target_state == TrustState.PENDING_REVIEW:
+            if not listing.canonical_name:
+                errors.append("Pending review state requires canonical_name")
+            if not listing.short_description:
+                errors.append("Pending review state requires short_description")
+            if not listing.canonical_source_url:
+                errors.append("Pending review state requires canonical_source_url")
+
+        elif target_state == TrustState.VERIFIED:
+            if not listing.publisher_id:
+                errors.append("Verified state requires publisher_id")
+
+        elif target_state == TrustState.SIGNED:
+            if not listing.fingerprint:
+                errors.append("Signed state requires fingerprint")
+            if not listing.signature_value:
+                errors.append("Signed state requires signature_value")
+
+        return errors
+
+    @classmethod
+    def transition(
+        cls,
+        listing: Listing,
+        to_state: TrustState,
+        reason: str = "",
+        triggered_by: str = "system",
+    ) -> Listing:
+        # Normalize legacy states before processing
+        current_state_str = normalize_legacy_state(listing.trust_state)
+        from_state = TrustState(current_state_str)
+
+        if from_state == to_state:
+            raise TrustTransitionError(
+                f"Listing is already in state '{to_state.value}'"
+            )
+
+        if not cls.can_transition(from_state, to_state):
+            raise TrustTransitionError(
+                f"Cannot transition from '{from_state.value}' to '{to_state.value}'. "
+                f"Valid targets: {[s.value for s in VALID_TRANSITIONS.get(from_state, set())]}"
+            )
+
+        criteria_errors = cls.validate_entry_criteria(listing, to_state)
+        if criteria_errors:
+            raise TrustTransitionError(
+                f"Entry criteria not met for '{to_state.value}': {'; '.join(criteria_errors)}"
+            )
+
+        transition = TrustTransition(
+            from_state=from_state.value,
+            to_state=to_state.value,
+            reason=reason,
+            triggered_by=triggered_by,
+        )
+
+        listing.trust_state = to_state.value
+        listing.trust_history.append(transition.to_dict())
+        listing.updated_at = datetime.now(timezone.utc).isoformat()
+
+        return listing
+
+
+# ── V2 Trust Badge Dictionary (single source of truth for all surfaces) ──
+
+TRUST_BADGES: Dict[str, Dict[str, str]] = {
+    "discovered": {
+        "label": "Discovered",
+        "symbol": "○",
+        "color": "grey",
+        "description": "Found by crawler, minimal validation",
+        "order": 0,
+    },
+    "pending_review": {
+        "label": "Pending Review",
+        "symbol": "◉",
+        "color": "yellow",
+        "description": "Schema validated, composite score computed",
+        "order": 1,
+    },
+    "verified": {
+        "label": "Verified",
+        "symbol": "✓",
+        "color": "green",
+        "description": "Publisher claimed and ownership verified",
+        "order": 2,
+    },
+    "signed": {
+        "label": "Signed",
+        "symbol": "✦",
+        "color": "blue",
+        "description": "Cryptographic signature present and valid",
+        "order": 3,
+    },
+    "deprecated": {
+        "label": "Deprecated",
+        "symbol": "✗",
+        "color": "red",
+        "description": "End-of-life, superseded, or abandoned",
+        "order": 4,
+    },
+}
+
+
+def get_trust_badge(trust_state: str) -> Dict[str, str]:
+    """Return the badge definition for a trust state. Falls back to 'discovered' for unknown states."""
+    normalized = normalize_legacy_state(trust_state)
+    return TRUST_BADGES.get(normalized, TRUST_BADGES["discovered"])

capacium_models-0.5.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: capacium-models
+Version: 0.5.0
+Summary: Shared domain models for the Capacium ecosystem — Listing, TrustState, TrustMachine, and more
+Author: Capacium
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Capacium/capacium-models
+Project-URL: Repository, https://github.com/Capacium/capacium-models
+Project-URL: Issues, https://github.com/Capacium/capacium-models/issues
+Keywords: capacium,models,listing,trust,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# capacium-models
+
+> [!NOTE]
+> **Public mirror.** The canonical repository is hosted on our self-hosted git.
+> This GitHub copy is a read-only mirror kept in sync for visibility and
+> installation. Bug reports are welcome via Issues; pull requests are applied
+> upstream and synced back here.
+
+Shared domain models for the Capacium ecosystem. Used by `capacium-exchange` and `capacium-crawler`.
+
+## Installation
+
+```bash
+pip install capacium-models
+```
+
+## Models
+
+| Model | Description |
+|-------|-------------|
+| `TrustState` | Enum: DISCOVERED → PENDING_REVIEW → VERIFIED → SIGNED → DEPRECATED |
+| `TrustMachine` | State machine with VALID_TRANSITIONS, can_transition(), transition() |
+| `Listing` | Full listing model (24 fields, auto-UUID, auto-timestamps) |
+| `Publisher` | Publisher profile with verification support |
+| `MCPClient` | Enum of supported MCP clients |
+| `MCPMetadata` | MCP-specific metadata (transport, runtime, auth_model, etc.) |
+| `Category` / `Subcategory` / `TagCount` | Taxonomy models |
+| `Collection` | Curated collection of listing IDs |
+| `ClaimRequest` / `VerificationRecord` | Trust workflow models |
+| `SearchQuery` | Faceted search query model (16 fields) |
+| `ExchangeSearch` | Faceted search SQL engine |
+
+The package-level `TRUST_BADGES` and `get_trust_badge()` exports retain the
+rich badge metadata introduced in v0.4.0. UI-facing canonical text labels,
+including the string-only trust labels, live in `capacium_models.labels`.
+
+## Usage
+
+```python
+from capacium_models import Listing, TrustState, TrustMachine
+
+# Create a discovered listing
+listing = Listing(
+    canonical_name="org/my-mcp-server",
+    package_type="mcp-server",
+    canonical_source_url="https://github.com/org/my-mcp-server",
+    short_description="A cool MCP server",
+    trust_state=TrustState.DISCOVERED,
+)
+
+# Transition through trust states
+machine = TrustMachine()
+if machine.can_transition(listing.trust_state, TrustState.PENDING_REVIEW):
+    listing = machine.transition(
+        listing,
+        TrustState.PENDING_REVIEW,
+        "Validated metadata",
+    )
+```
+
+## Dependencies
+
+Zero runtime dependencies — stdlib only (`dataclasses`, `enum`, `uuid`, `datetime`, `json`, `typing`).
+
+## License
+
+MIT
+
+## Development
+
+Canonical repository: **self-hosted Forgejo** — `git.langevc.com/capacium/capacium-models`
+(`git clone git@git.langevc.com:capacium/capacium-models.git`). Develop against the Forgejo
+clone and open pull requests there. The GitHub copy is a read-only mirror.

capacium_models-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+capacium_models/__init__.py,sha256=WPuprI0Bx8EcYYFMLgvRxgygdXX3JLfV1-7PZpjWjF0,1375
+capacium_models/keys.py,sha256=u98gw9FFTSBBdv9JM0_o4xWUyFdUa8GuiZIDEbJs750,5299
+capacium_models/labels.py,sha256=sopRzLjyB7PyWnRLKO8caduu_RwPH1masmCpyMIDaCg,1956
+capacium_models/models.py,sha256=19Xtw7cAs4RIXLyhcq1BjKbqQwVdguLFxyZjtnmLbno,12350
+capacium_models/search.py,sha256=OPNM7RlZ8sx8ipT_XE6C9VA-JwGNWKLJM3yvxEz0c7w,4863
+capacium_models/trust.py,sha256=z8yom8kpcrV6KGRo6FWEai_56TibSOKEVtj3HIx4z7Q,7111
+capacium_models-0.5.0.dist-info/licenses/LICENSE,sha256=XU1ruW3qAVD_Kyt2yvyVNadjak_NPX6YE8oRdnkxn7g,1065
+capacium_models-0.5.0.dist-info/METADATA,sha256=Z7jDfVtXcMPxu1ZzrEkRjSPvJObc_aDe-J-p8bpfW6M,3608
+capacium_models-0.5.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+capacium_models-0.5.0.dist-info/top_level.txt,sha256=HlNIpG2DeFPM7x6qXh8d_0s6Bvjh8cmKmZn7XT1tDg0,16
+capacium_models-0.5.0.dist-info/RECORD,,

capacium_models-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

capacium_models-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capacium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capacium_models-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+capacium_models