clm-kernel 0.0.0__py3-none-any.whl

clm/layer1/operations/builtins.py

@@ -0,0 +1,338 @@
+"""
+Core builtin operations for PythonRuntime.
+"""
+
+import json
+from typing import Any
+
+from clm.cross_cutting.config.config_constants import URL_FETCH_TIMEOUT_SECS
+from clm.layer0.model.card import MCard
+
+
+def op_identity(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Identity operation - returns target content unchanged."""
+    return target.get_content()
+
+
+def op_transform(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Transform operation - applies a named transformation."""
+    transforms = {
+        "upper_case": lambda t: t.get_content().decode("utf-8").upper().encode("utf-8"),
+        "count_bytes": lambda t: len(t.get_content()),
+    }
+    func = impl.get("transform_function")
+    return transforms.get(func, lambda t: t.get_content())(target)
+
+
+def op_arithmetic(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Arithmetic operation on numeric target content."""
+    params = {**impl.get("params", {}), **ctx}
+    op, operand = params.get("op"), params.get("operand")
+
+    try:
+        val = float(target.get_content().decode("utf-8"))
+    except ValueError:
+        return "Error: Target content is not a valid number"
+
+    ops = {
+        "add": lambda x, y: x + y,
+        "sub": lambda x, y: x - y,
+        "mul": lambda x, y: x * y,
+        "div": lambda x, y: x / y if y != 0 else "Error: Division by zero",
+    }
+    return ops.get(op, lambda x, y: f"Error: Unknown operation '{op}'")(val, operand)
+
+
+def op_string(impl: dict, target: MCard, ctx: dict) -> Any:
+    """String operation on target content."""
+    params = {**impl.get("params", {}), **ctx}
+    func = params.get("func")
+    s = target.get_content().decode("utf-8")
+
+    ops = {
+        "reverse": lambda: s[::-1],
+        "len": lambda: len(s),
+        "split": lambda: s.split(params.get("delimiter", " ")),
+    }
+    return ops.get(func, lambda: f"Error: Unknown function '{func}'")()
+
+
+def op_fetch_url(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Fetch content from a URL."""
+
+    from clm.cross_cutting.utils.url_safety import safe_urlopen
+
+    url = target.get_content().decode("utf-8").strip()
+    try:
+        with safe_urlopen(url, timeout=URL_FETCH_TIMEOUT_SECS) as resp:
+            return resp.read().decode("utf-8")[:1000]
+    except (OSError, ValueError, UnicodeDecodeError) as e:
+        return f"Error fetching URL: {e}"
+
+
+def op_session_record(impl: dict, target: MCard, ctx: dict) -> Any:
+    """P2P Session Recording operation."""
+    config = impl.get("config", {})
+    ctx_params = ctx.get("params", {})
+
+    # Extract session_id from various sources
+    session_id = ctx.get("sessionId") or ctx_params.get("sessionId")
+
+    # Check config with potential interpolation
+    if not session_id and "sessionId" in config:
+        val = config["sessionId"]
+        if isinstance(val, str) and val.startswith("${") and val.endswith("}"):
+            key = val[9:-1]  # strip '${params.' and '}'
+            if "." in key:
+                key = key.split(".")[-1]
+            session_id = ctx.get(key) or ctx_params.get(key)
+        else:
+            session_id = val
+
+    # Fallback to target content inspection
+    if not session_id:
+        try:
+            content = target.get_content().decode("utf-8")
+            data = json.loads(content)
+            if isinstance(data, dict):
+                session_id = data.get("sessionId")
+        except json.JSONDecodeError:
+            pass
+
+    return {
+        "success": True,
+        "session_id": session_id,
+        "message": f"Session recording initialized for {session_id}",
+    }
+
+
+def op_precondition_witness(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Precondition event generation operation.
+    Generates a simple PCard to act as the V_Pre gate and logs it.
+    """
+    import json
+    from datetime import datetime, timezone
+
+    from clm.layer0.model.pcard import PCard
+    from clm.layer0.model.vcard import VCardPre
+
+    pcard_hash = ctx.get("pcard_hash", "")
+    verification_evidence = ctx.get("verification_evidence")
+
+    # We could derive managed_event_types from preconditions or inputs.
+    # For now, let's look for a specific key in the target or assume a default.
+    # In a fully fleshed out system, this might be dynamically mapped.
+    managed_event_types = []
+
+    if isinstance(target, PCard):
+        v_pre_pcard = target.create_vcard(
+            vcard_class=VCardPre,
+            managed_event_types=managed_event_types,
+            version="1.0",
+            type="vcard-pre",
+            pcard_hash=pcard_hash,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            target_hash=target.hash,
+            verification_evidence=verification_evidence,
+        )
+    else:
+        content = {
+            "vcard": {
+                "version": "1.0",
+                "type": "vcard-pre",
+                "pcard_hash": pcard_hash,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "target_hash": target.hash if target else None,
+                "managed_event_types": managed_event_types,
+                "wrapped_pcard_hash": target.hash if target else None,
+            }
+        }
+        if verification_evidence:
+            content["vcard"]["verification_evidence"] = verification_evidence
+
+        # We wrap it directly since VCardPre inherits from VCard which inherits from PCard
+        v_pre_pcard = VCardPre(json.dumps(content))
+
+    collection = ctx.get("collection")
+    if collection:
+        vcard_hash = collection.add(v_pre_pcard)
+    else:
+        vcard_hash = v_pre_pcard.hash
+
+    log_db = ctx.get("log_db")
+    if log_db:
+        log_db.add(
+            MCard(
+                f"Execution Trace: PREP Phase Event | PCard: {pcard_hash} | Target: {target.hash} | V_Pre: {vcard_hash}"
+            )
+        )
+        # Register the v_pre with the execution engine or log if needed.
+        # It's now acting as a hook waiting for events.
+
+    return vcard_hash
+
+
+def op_postcondition_witness(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Postcondition event generation operation.
+    Generates a simple PCard to act as the V_Post gate and logs it.
+    """
+    import json
+    from datetime import datetime, timezone
+
+    from clm.layer0.model.pcard import PCard
+    from clm.layer0.model.vcard import VCardPost
+
+    pcard_hash = ctx.get("pcard_hash", "")
+    output = ctx.get("execution_output", "")
+    alignment_score = ctx.get("alignment_score")
+    invariants_preserved = ctx.get("invariants_preserved", True)
+    execution_telemetry = ctx.get("execution_telemetry")
+    governance_telemetry = ctx.get("governance_telemetry")
+
+    if isinstance(output, MCard):
+        output_repr = output.hash
+    elif isinstance(output, dict):
+        output_repr = json.dumps(output, sort_keys=True, default=str)[:512]
+    else:
+        output_repr = str(output)[:512]
+
+    # We could derive managed_event_types from postconditions or outputs.
+    # For now, let's extract it from the target if it specifies types to dispatch.
+    managed_event_types = []
+    try:
+        if isinstance(output, dict) and "dispatch_types" in output:
+            managed_event_types = output["dispatch_types"]
+    except Exception:
+        pass
+
+    if isinstance(target, PCard):
+        v_post_pcard = target.create_vcard(
+            vcard_class=VCardPost,
+            managed_event_types=managed_event_types,
+            version="1.0",
+            type="vcard-post",
+            pcard_hash=pcard_hash,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            output_repr=output_repr,
+            alignment_score=alignment_score,
+            invariants_preserved=invariants_preserved,
+            execution_telemetry=execution_telemetry,
+            governance_telemetry=governance_telemetry,
+        )
+    else:
+        content = {
+            "vcard": {
+                "version": "1.0",
+                "type": "vcard-post",
+                "pcard_hash": pcard_hash,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "output_repr": output_repr,
+                "alignment_score": alignment_score,
+                "invariants_preserved": invariants_preserved,
+                "managed_event_types": managed_event_types,
+                "wrapped_pcard_hash": target.hash if target else None,
+            }
+        }
+
+        if execution_telemetry:
+            content["vcard"]["execution_telemetry"] = execution_telemetry
+        if governance_telemetry:
+            content["vcard"]["governance_telemetry"] = governance_telemetry
+
+        v_post_pcard = VCardPost(json.dumps(content))
+
+    collection = ctx.get("collection")
+    if collection:
+        vcard_hash = collection.add(v_post_pcard)
+    else:
+        vcard_hash = v_post_pcard.hash
+
+    log_db = ctx.get("log_db")
+    if log_db:
+        log_db.add(
+            MCard(
+                f"Execution Trace: POST Phase Event | PCard: {pcard_hash} | Target: {target.hash} | V_Post: {vcard_hash} | Score: {alignment_score}"
+            )
+        )
+
+        # Trigger the dispatcher immediately upon generation
+        v_post_pcard.dispatch_events(log_db)
+
+    return vcard_hash
+
+
+def op_invoke_library(impl: dict, target: MCard, ctx: dict) -> Any:
+    """Invoke a library function directly by its signature/reference."""
+    import importlib
+
+    try:
+        from clm.cross_cutting.config.settings import settings
+
+        allowed_imports = settings.ptr.allowed_imports
+        safe_builtins = settings.ptr.safe_builtins
+    except ImportError:
+        allowed_imports = {}
+        safe_builtins = set()
+
+    module_name = impl.get("module")
+    func_name = impl.get("function")
+
+    if not func_name:
+        return "Error: No function specified in invoke_library"
+
+    # Resolve function
+    if module_name:
+        if module_name not in allowed_imports and module_name != "math":
+            return f"Error: Import of module '{module_name}' is not allowed"
+        try:
+            module = importlib.import_module(module_name)
+            func = getattr(module, func_name)
+        except Exception as e:
+            return f"Error: Could not load {module_name}.{func_name}: {e}"
+    else:
+        import builtins as builtins_module
+
+        if func_name not in safe_builtins:
+            return f"Error: Builtin function '{func_name}' is not allowed"
+        func = getattr(builtins_module, func_name)
+
+    # Collect inputs
+    input_defs = impl.get("inputs", {})
+    # Inputs might be a list or a dict in the spec
+    input_keys = (
+        list(input_defs.keys())
+        if isinstance(input_defs, dict)
+        else (input_defs if isinstance(input_defs, list) else [])
+    )
+
+    args = []
+    # Fetch from context, or target if no input keys defined and we just want to pass the target
+    if not input_keys:
+        try:
+            val = target.get_content().decode("utf-8")
+            # If it's a number, cast it
+            if val.lstrip("-").replace(".", "", 1).isdigit():
+                val = float(val) if "." in val else int(val)
+            args.append(val)
+        except Exception:
+            args.append(target.get_content())
+    else:
+        for key in input_keys:
+            val = ctx.get(key)
+            if val is None and key == "target":
+                try:
+                    target_val = target.get_content().decode("utf-8")
+                    if target_val.lstrip("-").replace(".", "", 1).isdigit():
+                        target_val = (
+                            float(target_val) if "." in target_val else int(target_val)
+                        )
+                    val = target_val
+                except Exception:
+                    val = target.get_content()
+            args.append(val)
+
+    # Invoke
+    try:
+        return func(*args)
+    except Exception as e:
+        return f"Error invoking {func_name}: {e}"

clm/layer1/operations/dispatch.py

@@ -0,0 +1,144 @@
+"""Baldwin Operations Dispatcher (DEL-388-03).
+
+Unified front-end for Baldwin Modularity Operators built directly on top of
+the existing OperationRegistry (clm.layer1.operations.base).
+Provides syntactic closure validation, semantic closure checks, and declarative dispatch.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from clm.layer0.model.card import MCard
+from clm.layer1.operations.augment import op_augment
+from clm.layer1.operations.base import OperationRegistry
+from clm.layer1.operations.exclude import op_exclude
+from clm.layer1.operations.invert import op_invert
+from clm.layer1.operations.port import op_port
+from clm.layer1.operations.split import op_split
+from clm.layer1.operations.substitute import op_substitute
+
+BALDWIN_OPERATIONS: dict[str, Callable] = {
+    "split": op_split,
+    "substitute": op_substitute,
+    "augment": op_augment,
+    "exclude": op_exclude,
+    "invert": op_invert,
+    "port": op_port,
+}
+
+
+def verify_syntactic_closure(manifest: dict[str, Any]) -> bool:
+    """Validate that a manifest satisfies triadic syntactic closure.
+
+    Per spec/40-behavior/baldwin_monadic_pcard_algebra.md §0:
+    Every operator application must preserve:
+      1. abstract_spec (or abstract)
+      2. concrete_impl (or concrete)
+      3. balanced_exp (or balanced)
+    """
+    if not isinstance(manifest, dict):
+        return False
+    has_abstract = "abstract_spec" in manifest or "abstract" in manifest
+    has_concrete = "concrete_impl" in manifest or "concrete" in manifest
+    has_balanced = "balanced_exp" in manifest or "balanced" in manifest
+    return bool(has_abstract and has_concrete and has_balanced)
+
+
+def verify_semantic_closure(result: dict[str, Any]) -> bool:
+    """Validate that the operation result forms a valid morphism in Poly(X)."""
+    if not isinstance(result, dict):
+        return False
+    if not result.get("success", False):
+        return False
+    # If the result returns a manifest or branch manifests, check closure
+    if "manifest" in result:
+        return verify_syntactic_closure(result["manifest"])
+    if "branch_a" in result and "branch_b" in result:
+        m_a = result["branch_a"].get("manifest", {})
+        m_b = result["branch_b"].get("manifest", {})
+        return verify_syntactic_closure(m_a) and verify_syntactic_closure(m_b)
+    return True
+
+
+def register_baldwin_operations(registry: OperationRegistry) -> None:
+    """Register the six Baldwin modularity operators onto an existing OperationRegistry."""
+    registry.register_many(BALDWIN_OPERATIONS)
+
+
+def get_baldwin_registry() -> OperationRegistry:
+    """Construct an OperationRegistry with all default and Baldwin operations registered."""
+    from clm.layer1.operations import DEFAULT_OPERATIONS
+
+    reg = OperationRegistry()
+    reg.register_many(DEFAULT_OPERATIONS)
+    reg.register_many(BALDWIN_OPERATIONS)
+    return reg
+
+
+def dispatch_baldwin_operation(
+    op_name: str,
+    impl: dict[str, Any] | None = None,
+    target: MCard | None = None,
+    ctx: dict[str, Any] | None = None,
+    registry: OperationRegistry | None = None,
+) -> Any:
+    """Dispatch a Baldwin operation by name.
+
+    Args:
+        op_name: Name of operator ('split', 'substitute', 'augment', 'exclude', 'invert', 'port').
+        impl: Implementation parameters.
+        target: Target MCard to transform (if None, creates empty placeholder MCard).
+        ctx: Execution context.
+        registry: Optional custom OperationRegistry.
+
+    Returns:
+        Operation execution result.
+    """
+    impl = impl or {}
+    ctx = ctx or {}
+    if target is None:
+        target = MCard("abstract_spec:\n  type: default\nconcrete_impl:\n  runtime: python\nbalanced_exp:\n  invariants: []")
+
+    reg = registry or get_baldwin_registry()
+    handler = reg.get(op_name)
+    if handler is None:
+        raise KeyError(f"Baldwin operation '{op_name}' not found in registry. Registered: {reg.list_operations()}")
+
+    result = handler(impl, target, ctx)
+    return result
+
+
+class BaldwinOperationDispatcher:
+    """High-level dispatcher for Baldwin modularity operators."""
+
+    def __init__(self, registry: OperationRegistry | None = None):
+        self.registry = registry or get_baldwin_registry()
+
+    def split(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("split", impl, target, ctx, self.registry)
+
+    def substitute(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("substitute", impl, target, ctx, self.registry)
+
+    def augment(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("augment", impl, target, ctx, self.registry)
+
+    def exclude(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("exclude", impl, target, ctx, self.registry)
+
+    def invert(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("invert", impl, target, ctx, self.registry)
+
+    def port(self, target: MCard, impl: dict[str, Any] | None = None, ctx: dict[str, Any] | None = None) -> dict[str, Any]:
+        return dispatch_baldwin_operation("port", impl, target, ctx, self.registry)
+
+
+__all__ = [
+    "BALDWIN_OPERATIONS",
+    "verify_syntactic_closure",
+    "verify_semantic_closure",
+    "register_baldwin_operations",
+    "get_baldwin_registry",
+    "dispatch_baldwin_operation",
+    "BaldwinOperationDispatcher",
+]

clm/layer1/operations/exclude.py

@@ -0,0 +1,107 @@
+"""Baldwin Exclude Operator (DEL-388-02).
+
+Pruning Operator (-): A(B) -> A(-B).
+Prunes constraints, steps, or capabilities from a CLM manifest,
+archives the excluded content as an audit trail record, and enforces
+triadic syntactic closure on the retained structure.
+"""
+from __future__ import annotations
+
+import copy
+import time
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import yaml
+
+from clm.layer0.model.card import MCard
+from clm.layer0.utils import clm_hash_string
+from clm.layer1.operations.split import _parse_manifest, ensure_triadic_closure
+
+
+@dataclass
+class BaldwinAuditRecord:
+    """Audit record preserving provenance for excluded/pruned components."""
+    operator: str
+    target_id: str
+    excluded_hash: str
+    excluded_content: str
+    timestamp: str
+    details: dict[str, Any]
+
+
+def op_exclude(impl: dict[str, Any], target: MCard, ctx: dict[str, Any]) -> dict[str, Any]:
+    """Execute the Baldwin Exclude (-) operation.
+
+    Args:
+        impl: Configuration dict for exclude:
+              exclude_path (str): Dot-separated path or key to prune.
+        target: Target MCard to prune.
+        ctx: Execution context.
+
+    Returns:
+        Dict containing the pruned manifest, new MCard, audit record, and closure proof.
+    """
+    manifest = _parse_manifest(target)
+
+    exclude_path = impl.get("exclude_path", ctx.get("exclude_path", ""))
+    if not exclude_path:
+        # Check alternative parameter names
+        exclude_path = impl.get("target_id", ctx.get("target_id", ""))
+
+    updated = copy.deepcopy(manifest)
+    excluded_val: Any = None
+
+    if exclude_path:
+        path_str = exclude_path.strip().lstrip(".")
+        parts = [p for p in path_str.split(".") if p]
+
+        # Retrieve value before pruning
+        curr = updated
+        for p in parts[:-1]:
+            if isinstance(curr, dict) and p in curr:
+                curr = curr[p]
+            else:
+                curr = None
+                break
+        if isinstance(curr, dict) and parts and parts[-1] in curr:
+            excluded_val = curr.pop(parts[-1])
+    else:
+        # Default: prune an optional or deprecated section if found
+        for candidate in ["deprecated", "debug", "legacy", "metadata"]:
+            if candidate in updated:
+                exclude_path = candidate
+                excluded_val = updated.pop(candidate)
+                break
+
+    excluded_str = yaml.dump(excluded_val, default_flow_style=False) if excluded_val is not None else ""
+    excl_hash = clm_hash_string(excluded_str) if excluded_str else ""
+    ts = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+    audit = BaldwinAuditRecord(
+        operator="exclude",
+        target_id=exclude_path or "none",
+        excluded_hash=excl_hash,
+        excluded_content=excluded_str,
+        timestamp=ts,
+        details={"retained_keys": list(updated.keys())},
+    )
+
+    final_manifest = ensure_triadic_closure(updated)
+    yaml_content = yaml.dump(final_manifest, default_flow_style=False)
+    new_card = MCard(yaml_content)
+
+    return {
+        "success": True,
+        "operator": "exclude",
+        "exclude_path": exclude_path,
+        "syntactic_closure": True,
+        "audit": asdict(audit),
+        "manifest": final_manifest,
+        "hash": new_card.hash,
+        "content": yaml_content,
+        "mcard": new_card,
+    }
+
+
+__all__ = ["op_exclude", "BaldwinAuditRecord"]