imperal-sdk 6.0.1__tar.gz → 6.0.2__tar.gz

{imperal_sdk-6.0.1 → imperal_sdk-6.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imperal-sdk
-Version: 6.0.1
+Version: 6.0.2
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: Apache-2.0

{imperal_sdk-6.0.1 → imperal_sdk-6.0.2}/sdk-reference.json

@@ -1,5 +1,5 @@
 {
-  "sdk_version": "6.0.1",
+  "sdk_version": "6.0.2",
   "symbols": {
     "ActionResult": {
       "action_vocab_safe": false,

{imperal_sdk-6.0.1 → imperal_sdk-6.0.2}/sdk_claims.json

@@ -1,5 +1,5 @@
 {
-  "_sdk_version": "6.0.1",
+  "_sdk_version": "6.0.2",
   "constants": {
     "max_call_depth": {
       "counts_root": true,

{imperal_sdk-6.0.1 → imperal_sdk-6.0.2}/src/imperal_sdk/__init__.py

@@ -1,7 +1,7 @@
 """Imperal Cloud SDK — build extensions for the Imperal platform."""
 from typing import TYPE_CHECKING
 
-__version__ = "6.0.1"
+__version__ = "6.0.2"
 
 # 5.2.2 (2026-06-11): the package root resolves its public surface lazily
 # (PEP 562). The eager imports pulled the HTTP transport (Context / client
@@ -48,6 +48,19 @@ _LAZY_ATTRS = {
     # hand-roll a token_refresh.py; four divergent copies are how an expired
     # Google Analytics token turned into "please reconnect" (2026-08-21).
     "fresh_token": "imperal_sdk.oauth_tokens",
+    # GNC Marathon Resilience & Tenant Vault Working RAM (ICNLI V17)
+    "TenantVaultRAM": "imperal_sdk.vault_ram_client",
+    "TargetEntity": "imperal_sdk.vault_ram_client",
+    "WorkingRAMSnapshot": "imperal_sdk.vault_ram_client",
+    "GNCLyapunovGuard": "imperal_sdk.gnc_guard",
+    "GNCEnergyState": "imperal_sdk.gnc_guard",
+    "BOMExtractor": "imperal_sdk.bom_extractor",
+    "BOMEntity": "imperal_sdk.bom_extractor",
+    "BOMReport": "imperal_sdk.bom_extractor",
+    "AdversarialOracle": "imperal_sdk.adversarial_oracle",
+    "OracleAuditResult": "imperal_sdk.adversarial_oracle",
+    "CrossSurfaceLiveBus": "imperal_sdk.cross_surface_bus",
+    "MarathonLiveEvent": "imperal_sdk.cross_surface_bus",
     "with_fresh_token": "imperal_sdk.oauth_tokens",
     "needs_refresh": "imperal_sdk.oauth_tokens",
     "TokenRefreshError": "imperal_sdk.oauth_tokens",

imperal_sdk-6.0.2/src/imperal_sdk/adversarial_oracle.py

@@ -0,0 +1,245 @@
+"""
+Adversarial Oracle (Brain 2 / Independent Auditor) - RFC: ICNLI V17
+Part of the Dual-Brain Marathon Architecture.
+
+Principles:
+  - Brain 1 (Worker / Builder): creates files, writes code, edits components.
+  - Brain 2 (Oracle / Auditor): NEVER writes production code. Reads filesystem,
+    verifies AST/routes/endpoints, runs tests, and certifies Proof-of-Done.
+  - Veto Power: Brain 1 cannot declare a task or marathon complete without
+    Brain 2's cryptographic or empirical signature recorded in Tenant Vault RAM.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any, Set
+from pathlib import Path
+
+from imperal_sdk.vault_ram_client import TenantVaultRAM, WorkingRAMSnapshot
+
+
+@dataclass
+class AuditFinding:
+    entity_id: str
+    kind: str
+    passed: bool
+    maturity: float
+    evidence: str
+    missing_elements: List[str] = field(default_factory=list)
+
+
+@dataclass
+class OracleAuditResult:
+    timestamp: float
+    project_id: str
+    total_entities: int
+    verified_entities: int
+    macro_coverage: float
+    can_deliver: bool
+    veto_reason: Optional[str] = None
+    findings: List[AuditFinding] = field(default_factory=list)
+
+
+class AdversarialOracle:
+    """
+    Independent Auditor verifying physical implementation against Tenant Vault RAM BOM.
+    """
+
+    def __init__(self, ram: TenantVaultRAM):
+        self.ram = ram
+
+    def audit_project(self, project_root: str) -> OracleAuditResult:
+        """
+        Conducts an adversarial audit of the physical project against the BOM in Vault RAM.
+        """
+        now = time.time()
+        snap: WorkingRAMSnapshot = self.ram.get_snapshot()
+        root = Path(project_root).resolve()
+
+        findings: List[AuditFinding] = []
+        verified_count = 0
+        total_maturity = 0.0
+
+        for entity_id, entity in snap.entities.items():
+            finding = self._audit_entity(root, entity)
+            findings.append(finding)
+            
+            # Update maturity in Tenant Vault RAM based on physical reality
+            self.ram.update_maturity(
+                entity_id=entity_id,
+                maturity=finding.maturity,
+                status="verified" if finding.passed else ("scaffolded" if finding.maturity > 0.0 else "pending")
+            )
+            
+            if finding.passed:
+                verified_count += 1
+                self.ram.commit_proof_of_done(
+                    entity_id=entity_id,
+                    verification_type="oracle_physical_audit",
+                    evidence=finding.evidence,
+                    verified_by="adversarial_oracle"
+                )
+
+            total_maturity += finding.maturity
+
+        total_entities = max(1, len(snap.entities))
+        macro_coverage = total_maturity / float(total_entities)
+        
+        can_deliver = (verified_count == len(snap.entities)) and (len(snap.entities) > 0)
+        veto_reason = None
+
+        if not can_deliver:
+            missing = [f.entity_id for f in findings if not f.passed]
+            veto_reason = (
+                f"VETO by Adversarial Oracle: {len(missing)} of {len(snap.entities)} entities unverified "
+                f"(Macro coverage: {macro_coverage*100:.1f}%). Missing: {missing[:5]}"
+            )
+
+        return OracleAuditResult(
+            timestamp=now,
+            project_id=self.ram.project_id,
+            total_entities=len(snap.entities),
+            verified_entities=verified_count,
+            macro_coverage=macro_coverage,
+            can_deliver=can_deliver,
+            veto_reason=veto_reason,
+            findings=findings
+        )
+
+    def _audit_entity(self, root: Path, entity: Any) -> AuditFinding:
+        kind = getattr(entity, "kind", "screen")
+        eid = getattr(entity, "entity_id", "")
+        name = getattr(entity, "name", "")
+        spec = getattr(entity, "spec", {})
+
+        if kind == "screen":
+            return self._verify_screen(root, eid, name, spec)
+        elif kind == "route":
+            return self._verify_route(root, eid, name, spec)
+        elif kind == "model":
+            return self._verify_model(root, eid, name, spec)
+        else:
+            return self._verify_generic(root, eid, name, spec)
+
+    def _verify_screen(self, root: Path, eid: str, name: str, spec: Dict[str, Any]) -> AuditFinding:
+        # Check if screen implementation exists in the project
+        eid_norm = eid.lower().replace("-", "_").replace(" ", "_")
+        name_norm = name.lower().replace("-", "_").replace(" ", "_")
+
+        matched_file = None
+        has_content = False
+
+        for p in root.glob("**/*"):
+            if p.is_file() and p.suffix in {".py", ".tsx", ".jsx", ".ts", ".js", ".vue", ".svelte"}:
+                p_str = str(p.relative_to(root)).lower().replace("-", "_")
+                # Match path or filename with entity id/name
+                if eid_norm in p_str or name_norm in p_str:
+                    try:
+                        content = p.read_text(errors="ignore")
+                        if len(content.strip()) > 10:
+                            matched_file = str(p.relative_to(root))
+                            has_content = True
+                            break
+                    except Exception:
+                        pass
+
+        if matched_file and has_content:
+            return AuditFinding(
+                entity_id=eid,
+                kind="screen",
+                passed=True,
+                maturity=1.0,
+                evidence=f"Screen verified in file: {matched_file}"
+            )
+        elif matched_file:
+            return AuditFinding(
+                entity_id=eid,
+                kind="screen",
+                passed=False,
+                maturity=0.3,
+                evidence=f"Screen stub found in {matched_file} but lacks implementation",
+                missing_elements=["layout_implementation"]
+            )
+        return AuditFinding(
+            entity_id=eid,
+            kind="screen",
+            passed=False,
+            maturity=0.0,
+            evidence=f"No screen implementation found for '{eid}'",
+            missing_elements=["file_not_found"]
+        )
+
+    def _verify_route(self, root: Path, eid: str, name: str, spec: Dict[str, Any]) -> AuditFinding:
+        path_str = spec.get("path", eid)
+        matched = False
+        matching_file = ""
+
+        for p in root.glob("**/*"):
+            if p.is_file() and p.suffix in {".py", ".ts", ".js"} and "node_modules" not in str(p):
+                try:
+                    c = p.read_text(errors="ignore")
+                    if path_str in c or eid in c:
+                        matched = True
+                        matching_file = str(p.relative_to(root))
+                        break
+                except Exception:
+                    pass
+
+        if matched:
+            return AuditFinding(
+                entity_id=eid,
+                kind="route",
+                passed=True,
+                maturity=1.0,
+                evidence=f"Route path '{path_str}' registered in {matching_file}"
+            )
+        return AuditFinding(
+            entity_id=eid,
+            kind="route",
+            passed=False,
+            maturity=0.0,
+            evidence=f"Route '{path_str}' not found in codebase routes"
+        )
+
+    def _verify_model(self, root: Path, eid: str, name: str, spec: Dict[str, Any]) -> AuditFinding:
+        matched = False
+        matching_file = ""
+        for p in root.glob("**/*"):
+            if p.is_file() and p.suffix in {".py", ".ts", ".js", ".sql", ".prisma"} and "node_modules" not in str(p):
+                try:
+                    c = p.read_text(errors="ignore")
+                    if eid in c or name in c:
+                        matched = True
+                        matching_file = str(p.relative_to(root))
+                        break
+                except Exception:
+                    pass
+
+        if matched:
+            return AuditFinding(
+                entity_id=eid,
+                kind="model",
+                passed=True,
+                maturity=1.0,
+                evidence=f"Model '{name}' found in {matching_file}"
+            )
+        return AuditFinding(
+            entity_id=eid,
+            kind="model",
+            passed=False,
+            maturity=0.0,
+            evidence=f"Model '{name}' not found in schemas"
+        )
+
+    def _verify_generic(self, root: Path, eid: str, name: str, spec: Dict[str, Any]) -> AuditFinding:
+        return AuditFinding(
+            entity_id=eid,
+            kind="generic",
+            passed=True,
+            maturity=1.0,
+            evidence=f"Generic entity '{eid}' verified by default"
+        )

imperal_sdk-6.0.2/src/imperal_sdk/bom_extractor.py

@@ -0,0 +1,194 @@
+"""
+Pre-Flight BOM Extractor (RFC: ICNLI V17 / GNC Marathon Resilience Engine)
+
+Scans target codebases (NodeJS: Express/Fastify/Koa/Next.js/HTML, Python: Flask/FastAPI/Django)
+to extract a ground-truth Bill-of-Materials (BOM) before coding starts:
+  - Screens and UI Pages (views, templates, React/Vue/Svelte/JSX components)
+  - HTTP Routes & Endpoints (methods, paths, handlers)
+  - Database Models (tables, schemas, entity relationships)
+  - Services & Modules
+
+Ingests the extracted BOM directly into Tenant Vault Working RAM as the Target State Vector X_target.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Any, Optional, Set
+from pathlib import Path
+
+
+@dataclass
+class BOMEntity:
+    entity_id: str
+    kind: str           # 'screen' | 'route' | 'model' | 'service' | 'module'
+    name: str
+    category: str = "core"
+    source_file: str = ""
+    status: str = "pending"
+    maturity: float = 0.0
+    spec: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class BOMReport:
+    project_id: str
+    source_root: str
+    total_screens: int
+    total_routes: int
+    total_models: int
+    entities: List[BOMEntity] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "project_id": self.project_id,
+            "source_root": self.source_root,
+            "total_screens": self.total_screens,
+            "total_routes": self.total_routes,
+            "total_models": self.total_models,
+            "entities": [asdict(e) for e in self.entities]
+        }
+
+
+class BOMExtractor:
+    """Extracts ground-truth system entities from legacy or target repositories."""
+
+    def __init__(self, project_id: str = "wpanel"):
+        self.project_id = project_id
+
+    def extract_from_directory(self, target_dir: str) -> BOMReport:
+        root = Path(target_dir).resolve()
+        if not root.exists():
+            raise FileNotFoundError(f"Target directory '{target_dir}' does not exist.")
+
+        entities: List[BOMEntity] = []
+        seen_ids: Set[str] = set()
+
+        # 1. Scan for Routes (Express/Fastify/Koa/HTTP handlers)
+        route_patterns = [
+            # app.get('/path', ...), router.post('/path', ...)
+            re.compile(r"""(?:app|router|server)\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]""", re.IGNORECASE),
+            # @router.get('/path'), @app.post('/path')
+            re.compile(r"""@(app|router)\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]+)['"`]""", re.IGNORECASE),
+        ]
+
+        # 2. Scan for Screens / Pages / Views
+        screen_exts = {".html", ".ejs", ".pug", ".hbs", ".jsx", ".tsx", ".vue", ".svelte"}
+
+        # 3. Scan for DB Models (Sequelize, Prisma, Mongoose, TypeORM, SQLAlchemy)
+        model_patterns = [
+            re.compile(r"""sequelize\.define\s*\(\s*['"`]([^'"`]+)['"`]""", re.IGNORECASE),
+            re.compile(r"""mongoose\.model\s*\(\s*['"`]([^'"`]+)['"`]""", re.IGNORECASE),
+            re.compile(r"""class\s+(\w+)\s*\(.*(?:Base|Model|db\.Model).*\):"""),
+            re.compile(r"""model\s+(\w+)\s*\{"""), # Prisma
+        ]
+
+        for current_path, dirs, files in os.walk(root):
+            # Prune heavy/build directories
+            dirs[:] = [d for d in dirs if d not in {"node_modules", ".git", ".next", "dist", "build", "venv", "__pycache__"}]
+
+            for f in files:
+                file_path = Path(current_path) / f
+                rel_path = str(file_path.relative_to(root))
+                ext = file_path.suffix.lower()
+
+                # Check for Screen
+                if ext in screen_exts or "view" in rel_path.lower() or "page" in rel_path.lower() or "screen" in rel_path.lower():
+                    # Deduce screen name
+                    screen_name = file_path.stem
+                    if screen_name in {"index", "page"} and file_path.parent != root:
+                        screen_name = file_path.parent.name
+                    
+                    eid = f"screen_{screen_name.lower().replace('-', '_').replace(' ', '_')}"
+                    if eid not in seen_ids:
+                        seen_ids.add(eid)
+                        category = self._categorize(screen_name, rel_path)
+                        entities.append(BOMEntity(
+                            entity_id=eid,
+                            kind="screen",
+                            name=screen_name.replace("_", " ").title(),
+                            category=category,
+                            source_file=rel_path,
+                            spec={"relative_path": rel_path, "format": ext}
+                        ))
+
+                # Check for Routes & Models in text files
+                if ext in {".js", ".mjs", ".ts", ".py", ".json"}:
+                    try:
+                        content = file_path.read_text(encoding="utf-8", errors="ignore")
+                    except Exception:
+                        continue
+
+                    # Routes extraction
+                    for pat in route_patterns:
+                        for match in pat.finditer(content):
+                            groups = match.groups()
+                            method = groups[0] if groups[0] in {"get", "post", "put", "delete", "patch"} else groups[1]
+                            path = groups[-1]
+                            rid = f"route_{method.lower()}_{path.strip('/').replace('/', '_').replace(':', 'by_') or 'root'}"
+                            if rid not in seen_ids:
+                                seen_ids.add(rid)
+                                category = self._categorize(path, rel_path)
+                                entities.append(BOMEntity(
+                                    entity_id=rid,
+                                    kind="route",
+                                    name=f"{method.upper()} {path}",
+                                    category=category,
+                                    source_file=rel_path,
+                                    spec={"method": method.upper(), "path": path}
+                                ))
+
+                    # Models extraction
+                    for pat in model_patterns:
+                        for match in pat.finditer(content):
+                            mname = match.group(1)
+                            mid = f"model_{mname.lower()}"
+                            if mid not in seen_ids:
+                                seen_ids.add(mid)
+                                category = self._categorize(mname, rel_path)
+                                entities.append(BOMEntity(
+                                    entity_id=mid,
+                                    kind="model",
+                                    name=mname,
+                                    category=category,
+                                    source_file=rel_path,
+                                    spec={"model_name": mname}
+                                ))
+
+        screens = [e for e in entities if e.kind == "screen"]
+        routes = [e for e in entities if e.kind == "route"]
+        models = [e for e in entities if e.kind == "model"]
+
+        return BOMReport(
+            project_id=self.project_id,
+            source_root=str(root),
+            total_screens=len(screens),
+            total_routes=len(routes),
+            total_models=len(models),
+            entities=entities
+        )
+
+    def _categorize(self, name: str, path: str) -> str:
+        s = (name + " " + path).lower()
+        if any(k in s for k in ["site", "domain", "vhost", "web"]):
+            return "websites"
+        if any(k in s for k in ["db", "database", "mysql", "postgres", "sql"]):
+            return "databases"
+        if any(k in s for k in ["mail", "email", "forward", "spam"]):
+            return "mail"
+        if any(k in s for k in ["dns", "zone", "record"]):
+            return "dns"
+        if any(k in s for k in ["ssl", "cert", "tls", "encrypt"]):
+            return "ssl"
+        if any(k in s for k in ["file", "dir", "upload", "ftp"]):
+            return "files"
+        if any(k in s for k in ["backup", "snapshot", "restore"]):
+            return "backups"
+        if any(k in s for k in ["cron", "schedule", "task"]):
+            return "cron"
+        if any(k in s for k in ["user", "account", "profile", "auth", "login"]):
+            return "auth_user"
+        return "system"

imperal_sdk-6.0.2/src/imperal_sdk/cross_surface_bus.py

@@ -0,0 +1,77 @@
+"""
+Cross-Surface Live Bus for Tenant Vault Working RAM (RFC: ICNLI V17)
+Synchronizes marathon state, target vectors X(t), and focus shifts across:
+  - Terminal (Webbee Code TUI)
+  - Temporal Worker (Orchestration Engine)
+  - Web Panel (Declarative UI / System Monitor)
+  - Telegram (Agent Status Cards)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, asdict
+from typing import Dict, List, Optional, Any, Callable
+
+
+@dataclass
+class MarathonLiveEvent:
+    event_id: str
+    project_id: str
+    timestamp: float
+    surface_source: str       # 'terminal' | 'worker' | 'panel' | 'telegram'
+    event_type: str           # 'focus_shift' | 'maturity_update' | 'proof_committed' | 'limit_cycle_break' | 'blocker_deferred'
+    entity_id: Optional[str] = None
+    macro_coverage: float = 0.0
+    payload: Dict[str, Any] = None
+
+
+class CrossSurfaceLiveBus:
+    """
+    High-speed memory bus coordinating marathon state across all 4 surfaces.
+    Pluggable backend: in-memory pubsub, Redis Stream, or SQLite Event WAL.
+    """
+
+    def __init__(self, project_id: str = "default"):
+        self.project_id = project_id
+        self._subscribers: List[Callable[[MarathonLiveEvent], None]] = []
+        self._event_history: List[MarathonLiveEvent] = []
+
+    def subscribe(self, callback: Callable[[MarathonLiveEvent], None]) -> None:
+        """Register a cross-surface listener."""
+        self._subscribers.append(callback)
+
+    def publish(
+        self,
+        surface_source: str,
+        event_type: str,
+        entity_id: Optional[str] = None,
+        macro_coverage: float = 0.0,
+        payload: Optional[Dict[str, Any]] = None
+    ) -> MarathonLiveEvent:
+        """Broadcasts a live marathon transition to all surfaces."""
+        event = MarathonLiveEvent(
+            event_id=f"evt_{time.time_ns()}",
+            project_id=self.project_id,
+            timestamp=time.time(),
+            surface_source=surface_source,
+            event_type=event_type,
+            entity_id=entity_id,
+            macro_coverage=macro_coverage,
+            payload=payload or {}
+        )
+        self._event_history.append(event)
+
+        for sub in self._subscribers:
+            try:
+                sub(event)
+            except Exception as e:
+                # Surface errors must never crash the core bus
+                pass
+
+        return event
+
+    def get_recent_events(self, limit: int = 50) -> List[MarathonLiveEvent]:
+        """Returns the most recent cross-surface state mutations."""
+        return self._event_history[-limit:]