clm-kernel 0.0.0__py3-none-any.whl

clm/cross_cutting/cel_ops_strings.py

@@ -0,0 +1,64 @@
+"""CEL string, path, and comparison ops (Sprint 133.2).
+
+Extracted from ``cel_ops.py``.
+"""
+import os
+from collections.abc import Callable
+
+from clm.cross_cutting.cel_engine import _resolve_arg
+
+
+def op_path_join(cel: dict, ctx: dict):
+    parts = [str(_resolve_arg(p, ctx)) for p in cel["parts"]]
+    return os.path.join(*parts)
+
+
+def op_path_basename(cel: dict, ctx: dict):
+    value = _resolve_arg(cel["value"], ctx)
+    return os.path.basename(str(value))
+
+
+def op_string_concat(cel: dict, ctx: dict):
+    parts = [_resolve_arg(p, ctx) for p in cel["parts"]]
+    return "".join(str(p) for p in parts)
+
+
+def op_string_join(cel: dict, ctx: dict):
+    separator = str(_resolve_arg(cel["separator"], ctx))
+    parts = [_resolve_arg(p, ctx) for p in cel["parts"]]
+    return separator.join(str(p) for p in parts)
+
+
+def op_replace(cel: dict, ctx: dict):
+    value = str(_resolve_arg(cel["value"], ctx))
+    old = str(_resolve_arg(cel["old"], ctx))
+    new = str(_resolve_arg(cel["new"], ctx))
+    return value.replace(old, new)
+
+
+_COMPARE_OPS: dict[str, Callable] = {
+    "eq": lambda a, b: a == b,
+    "ne": lambda a, b: a != b,
+    "gt": lambda a, b: a > b,
+    "gte": lambda a, b: a >= b,
+    "lt": lambda a, b: a < b,
+    "lte": lambda a, b: a <= b,
+    "in": lambda a, b: (tuple(a) if isinstance(a, list) else a) in b,
+    "not_in": lambda a, b: (tuple(a) if isinstance(a, list) else a) not in b,
+}
+
+
+def op_compare(cel: dict, ctx: dict):
+    left = _resolve_arg(cel["left"], ctx)
+    right = _resolve_arg(cel["right"], ctx)
+    operator = cel["operator"]
+    fn = _COMPARE_OPS.get(operator)
+    if fn is None:
+        raise ValueError(f"Unknown CEL compare operator: {operator}")
+    return fn(left, right)
+
+
+def op_contains(cel: dict, ctx: dict):
+    haystack = _resolve_arg(cel["haystack"], ctx)
+    needle = _resolve_arg(cel["needle"], ctx)
+    return needle in haystack

clm/cross_cutting/cel_resolver.py

@@ -0,0 +1,63 @@
+"""Unified CEL reference resolver (Sprint 133 §7.4).
+
+Extracted from ``cel_engine._resolve_ref`` and ``CelStore.select``.
+Both operated on the same dot-notation namespace dispatch but were
+duplicated — one for raw ``dict`` contexts, one for typed ``CelStore``.
+
+This module provides a single ``resolve_ref`` function that works against
+either a ``dict`` or a ``CelStore``, eliminating the duplication.
+"""
+from typing import Any
+
+
+def resolve_ref(ref_str: str, source: Any) -> Any:
+    """Resolve a dot-notation reference against a dict or CelStore.
+
+    Namespaces:
+        inputs.<key>    -> source["inputs"][key] / source.state.inputs[key]
+        outputs.<key>   -> source["outputs"][key] / source.state.outputs[key]
+        state.<key>     -> source["retrieve"](key) / source.state.vars[key]
+        env.<key>       -> source["tmp_dir"] etc. / source.env.tmp_dir etc.
+        services.<name> -> source["db"] etc. / source.services.db etc.
+
+    Args:
+        ref_str: Dot-notation reference (e.g. ``"inputs.schema_path"``).
+        source: A ``dict`` (legacy context) or a ``CelStore``.
+
+    Returns:
+        The resolved value.
+
+    Raises:
+        ValueError: If the namespace is unknown.
+        KeyError: If the key is not found in the namespace.
+    """
+    parts = ref_str.split(".", 1)
+    namespace = parts[0]
+    key = parts[1] if len(parts) > 1 else ""
+
+    # CelStore path (typed)
+    if hasattr(source, "state") and hasattr(source, "env"):
+        if namespace == "inputs":
+            return source.state.inputs[key]
+        if namespace == "outputs":
+            return source.state.outputs[key]
+        if namespace == "state":
+            return source.state.vars[key]
+        if namespace == "env":
+            env_map = {"tmp_dir": source.env.tmp_dir, "clm_root": source.env.clm_root, "rc": source.state.rc}
+            return env_map.get(key, key)
+        if namespace == "services":
+            return getattr(source.services, key, None)
+        raise ValueError(f"Unknown CEL reference namespace: {namespace}")
+
+    # Dict path (legacy context)
+    if namespace == "inputs":
+        return source["inputs"][key]
+    if namespace == "outputs":
+        return source["outputs"][key]
+    if namespace == "state":
+        return source["retrieve"](key)
+    if namespace == "env":
+        env_map = {"tmp_dir": "tmp_dir", "clm_root": "clm_root", "rc": "rc"}
+        return source[env_map.get(key, key)]
+    raise ValueError(f"Unknown CEL reference namespace: {namespace}")

clm/cross_cutting/cel_slices.py

@@ -0,0 +1,56 @@
+"""CelStore state slices (Sprint 133.2).
+
+Extracted from ``cel_store.py``. The three Pydantic slice models that
+structure the store's state: ``StateSlice`` (mutable), ``ServiceSlice``
+(read-only services), ``EnvSlice`` (read-only environment).
+"""
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class StateSlice(BaseModel):
+    """Mutable test state — the data that changes during a test case."""
+    inputs: dict[str, Any] = Field(default_factory=dict)
+    outputs: dict[str, Any] = Field(default_factory=dict)
+    rc: int = 0
+    vars: dict[str, Any] = Field(default_factory=dict)
+    card_vars: dict[str, str] = Field(default_factory=dict)
+
+    def get(self, key: str) -> Any:
+        return self.vars.get(key)
+
+    def set(self, key: str, value: Any) -> Any:
+        self.vars[key] = value
+        self.card_vars.pop(key, None)
+        return value
+
+    def set_card(self, key: str, handle: str, value: Any) -> Any:
+        self.vars[key] = value
+        self.card_vars[key] = handle
+        return value
+
+
+class ServiceSlice(BaseModel):
+    """Read-only services injected into the store."""
+    db: Any = None
+    ctx: Any = None
+    repo: Any = None
+    classify_clm: Any = None
+    detect_dialect: Any = None
+    modules: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class EnvSlice(BaseModel):
+    """Read-only environment configuration."""
+    clm_root: str = ""
+    tmp_dir: str = ""
+    os: Any = None
+    sys: Any = None
+    time: Any = None
+    hashlib: Any = None
+    str: type = str
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)

clm/cross_cutting/cel_store.py

@@ -0,0 +1,330 @@
+"""CelStore — Flux-pattern store for CEL evaluation state (Sprint 128.1+128.2).
+
+Implements the Single Source of Truth principle from the Flux/Redux/Zustand
+pattern. Replaces the 30+ key mutable ``context`` dict ("God Object") with a
+typed store structured into three slices:
+
+    - ``StateSlice``    — mutable test state (inputs, outputs, rc, vars)
+    - ``ServiceSlice``  — read-only services (db, repo, ctx, classifiers)
+    - ``EnvSlice``      — read-only environment (clm_root, tmp_dir)
+
+Unidirectional data flow:
+
+    action -> pre-middleware -> reducer -> post-middleware -> action log
+           -> notify subscribers
+
+Backward compatibility: :meth:`CelStore.to_dict` produces the exact dict shape
+that existing CEL op handlers and tests expect, so handlers continue to
+receive ``dict`` and require no changes during migration.
+
+Design references:
+    - Sprint 128 spec (docs/sprints/sprint-128-flux-store-architecture.md)
+    - Redux (single store, unidirectional flow)
+    - Zustand (minimal get/set/subscribe API)
+    - nanostores (computed selectors)
+    - Thunk (side-effect isolation via EffectRegistry)
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel  # noqa: F401 — re-exported for backward compat
+
+# Sprint 133.2: middleware types (re-exported from cel_builder for backward compat)
+from clm.cross_cutting.cel_builder import (  # noqa: F401
+    Listener,
+    PostMiddleware,
+    PreMiddleware,
+)
+
+# Sprint 133.2: slices extracted to cel_slices.py
+from clm.cross_cutting.cel_slices import EnvSlice, ServiceSlice, StateSlice  # noqa: F401
+
+# ---------------------------------------------------------------------------
+# CelStore (Sprint 128.1 + 128.2)
+# ---------------------------------------------------------------------------
+
+class CelStore:
+    """Flux-pattern store — the Single Source of Truth for CEL evaluation.
+
+    API (Zustand-inspired minimal surface):
+
+        store.get_state()       -> StateSlice
+        store.get_services()    -> ServiceSlice
+        store.get_env()         -> EnvSlice
+        store.set(key, value)   -> mutate state.vars[key]
+        store.get(key)          -> read state.vars[key]
+        store.select(ref)       -> dot-notation selector
+        store.dispatch(action)  -> unidirectional flow
+        store.subscribe(fn)     -> listen for state changes
+        store.to_dict()         -> backward-compat dict adapter
+
+    The dispatch flow is:
+
+        1. Run pre-middleware (can modify or reject action by returning None)
+        2. Invoke reducer via CelOpRegistry.dispatch()
+        3. Run post-middleware (observes result)
+        4. Append to action_log
+        5. Notify subscribers
+    """
+
+    def __init__(
+        self,
+        state: StateSlice | None = None,
+        services: ServiceSlice | None = None,
+        env: EnvSlice | None = None,
+    ) -> None:
+        self.state: StateSlice = state or StateSlice()
+        self.services: ServiceSlice = services or ServiceSlice()
+        self.env: EnvSlice = env or EnvSlice()
+        self.action_log: list[dict[str, Any]] = []
+        self._listeners: list[Listener] = []
+        self._pre_middleware: list[PreMiddleware] = []
+        self._post_middleware: list[PostMiddleware] = []
+        # Lazily-injected side-effect registry (Sprint 128.4)
+        self.effects: Any = None
+        # Writer monad delegate (Sprint 132.1 — handle_history persistence)
+        from clm.cross_cutting.writer import StoreWriter
+        self.writer: StoreWriter = StoreWriter(self)
+        # Sprint 132.5: cached to_dict() — invalidated on set()/set_persisted()
+        self._ctx_cache: dict[str, Any] | None = None
+
+    def _invalidate_cache(self) -> None:
+        """Invalidate the to_dict() cache (Sprint 132.5)."""
+        self._ctx_cache = None
+
+    # ------------------------------------------------------------------
+    # Slice accessors
+    # ------------------------------------------------------------------
+
+    def get_state(self) -> StateSlice:
+        return self.state
+
+    def get_services(self) -> ServiceSlice:
+        return self.services
+
+    def get_env(self) -> EnvSlice:
+        return self.env
+
+    # ------------------------------------------------------------------
+    # State mutation (Zustand-style minimal API)
+    # ------------------------------------------------------------------
+
+    def get(self, key: str) -> Any:
+        return self.state.get(key)
+
+    def set(self, key: str, value: Any) -> Any:
+        self._invalidate_cache()
+        return self.state.set(key, value)
+
+    def select(self, ref: str) -> Any:
+        """Resolve a dot-notation reference against the store.
+
+        Sprint 133 §7.4: delegates to ``cel_resolver.resolve_ref`` for a
+        single implementation shared with ``cel_engine._resolve_ref``.
+        """
+        from clm.cross_cutting.cel_resolver import resolve_ref
+        return resolve_ref(ref, self)
+
+    # ------------------------------------------------------------------
+    # Handle-backed persistence (Sprint 131.3 — opt-in, backward-compatible)
+    # ------------------------------------------------------------------
+
+    def set_persisted(self, key: str, value: Any, pillar: str = "execution_log") -> Any:
+        """Delegate to StoreWriter (Writer monad — moved to writer.py in Sprint 132.1)."""
+        self._invalidate_cache()
+        return self.writer.set_persisted(key, value, pillar)
+
+    def select_card(self, ref: str) -> Any:
+        """Delegate to StoreWriter (Writer monad — moved to writer.py in Sprint 132.1)."""
+        return self.writer.select_card(ref)
+
+    # ------------------------------------------------------------------
+    # Middleware registration
+    # ------------------------------------------------------------------
+
+    def add_pre_middleware(self, mw: PreMiddleware) -> None:
+        self._pre_middleware.append(mw)
+
+    def add_post_middleware(self, mw: PostMiddleware) -> None:
+        self._post_middleware.append(mw)
+
+    # ------------------------------------------------------------------
+    # Subscribers
+    # ------------------------------------------------------------------
+
+    def subscribe(self, listener: Listener) -> Callable[[], None]:
+        """Subscribe to state changes. Returns an unsubscribe function."""
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            if listener in self._listeners:
+                self._listeners.remove(listener)
+
+        return unsubscribe
+
+    # ------------------------------------------------------------------
+    # Dispatch (Sprint 128.2 — unidirectional data flow)
+    # ------------------------------------------------------------------
+
+    def dispatch(self, action: dict) -> Any:
+        """Dispatch a CEL action through the middleware pipeline.
+
+        Flow:
+            pre-middleware -> reducer -> post-middleware -> log -> notify
+
+        If any pre-middleware returns ``None``, the action is rejected
+        and ``None`` is returned without invoking the reducer.
+        """
+        ctx = self.to_dict()
+
+        # 1. Pre-middleware (can reject by returning None)
+        for mw in self._pre_middleware:
+            result = mw(self, action)
+            if result is None:
+                self._log_action(action, None, rejected=True)
+                return None
+            action = result
+            ctx = self.to_dict()
+
+        # 2. Reducer (delegate to CelOpRegistry)
+        from clm.cross_cutting.cel_engine import _DEFAULT_REGISTRY
+        result = _DEFAULT_REGISTRY.dispatch(action, ctx)
+
+        # 3. Post-middleware
+        for mw in self._post_middleware:
+            mw(self, action, result)
+
+        # 4. Action log
+        self._log_action(action, result)
+
+        # 5. Notify subscribers
+        for listener in self._listeners:
+            listener(self, action, result)
+
+        return result
+
+    def _log_action(self, action: dict, result: Any, rejected: bool = False) -> None:
+        self.action_log.append({
+            "type": "cel_dispatch",
+            "op": action.get("op"),
+            "action": action,
+            "result": repr(result)[:200],
+            "rejected": rejected,
+            "timestamp": time.time(),
+        })
+
+    # ------------------------------------------------------------------
+    # Backward-compatibility adapter (Sprint 128.1)
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        """Produce the legacy context dict shape for op handlers.
+
+        Sprint 132.5: caches the result; invalidated on set()/set_persisted().
+        """
+        if self._ctx_cache is not None:
+            return self._ctx_cache
+        ctx: dict[str, Any] = {
+            # State slice
+            "inputs": self.state.inputs,
+            "outputs": self.state.outputs,
+            "rc": self.state.rc,
+            "store": self.state.set,
+            "retrieve": self.state.get,
+            # Service slice
+            "db": self.services.db,
+            "ctx": self.services.ctx,
+            "repo": self.services.repo,
+            "classify_clm": self.services.classify_clm,
+            "detect_dialect": self.services.detect_dialect,
+            # Env slice
+            "clm_root": self.env.clm_root,
+            "tmp_dir": self.env.tmp_dir,
+            "os": self.env.os,
+            "sys": self.env.sys,
+            "time": self.env.time,
+            "hashlib": self.env.hashlib,
+            "str": self.env.str,
+        }
+        # Merge any extra service modules (write_file, make_mcard_content, etc.)
+        ctx.update(self.services.modules)
+        # Expose the effect registry for side-effect isolation (Sprint 128.4).
+        ctx["effects"] = self.effects
+        self._ctx_cache = ctx
+        return ctx
+
+    # ------------------------------------------------------------------
+    # Monadic operations (Sprint 129.2 — bind/unit)
+    # ------------------------------------------------------------------
+
+    def bind(self, next_fn: Callable[["CelStore", Any], Any]) -> Any:
+        """Monadic bind (>>= operator).
+
+        Threads the store through a sequence of computations:
+            store.bind(f).bind(g) == store >>= f >>= g
+
+        Each bind:
+            1. If there's a pending action, dispatch it and use the result
+            2. Otherwise, use the monadic value from the previous unit()
+            3. Pass the value to next_fn
+            4. Return the result
+
+        This satisfies the three monad laws (verified in tests/test_monadic_laws.py):
+            Left identity:  unit(a).bind(f) == f(store, a)
+            Right identity: store.bind(f).bind(unit) == store.bind(f)
+            Associativity:  store.bind(f).bind(g) == store.bind(lambda s, x: f(s,x).bind(g))
+        """
+        result = None
+        pending = getattr(self, "_pending_action", None)
+        if pending is not None:
+            self._pending_action = None
+            result = self.dispatch(pending)
+        else:
+            # Use monadic value from previous unit() call
+            result = self.state.get("_monadic_value")
+        return next_fn(self, result)
+
+    def unit(self, value: Any) -> "CelStore":
+        """Monadic unit/return — wraps a value in the store context.
+
+        Stores the value as a state var, ready for the next bind in the chain.
+        """
+        self.set("_monadic_value", value)
+        self._pending_action = None
+        return self
+
+    @property
+    def pending_action(self) -> dict | None:
+        """Get or set the pending action for deferred dispatch via bind()."""
+        return getattr(self, "_pending_action", None)
+
+    @pending_action.setter
+    def pending_action(self, action: dict | None) -> None:
+        self._pending_action = action
+
+    # ------------------------------------------------------------------
+    # Flux event store persistence (Sprint 129.3)
+    # ------------------------------------------------------------------
+
+    def flush_action_log(self, ctx: Any) -> str | None:
+        """Delegate to StoreWriter (Writer monad — moved to writer.py in Sprint 132.1)."""
+        return self.writer.flush_action_log(ctx)
+
+
+# Sprint 133.2: thunk moved to vcard.py (Sprint 132.1); re-exported here.
+# Sprint 133.2: middleware factories + build_store extracted to cel_builder.py
+from clm.cross_cutting.cel_builder import (  # noqa: E402,F401
+    _build_write_file_fn,
+    action_log_middleware,
+    build_store,
+    vcard_post_middleware,
+    vcard_pre_middleware,
+)
+
+# Sprint 133.2: EffectRegistry re-exported from effects.py (Sprint 132.1)
+from clm.cross_cutting.effects import EffectRegistry, register_default_effects  # noqa: E402,F401
+from clm.cross_cutting.vcard import thunk  # noqa: E402,F401

clm/cross_cutting/clm_logger.py

@@ -0,0 +1,140 @@
+"""CLMLogger — Unified logging for the CLM platform (Sprint 129.1).
+
+Replaces all ad-hoc ``print(..., file=sys.stderr)`` calls with a structured,
+leveled, configurable logger. Extends Python's ``logging`` module with
+CLM-specific structured fields (agent_did, run_id, pcard_hash, op).
+
+Configuration via environment variables:
+    CLM_LOG_LEVEL:      DEBUG | INFO | WARNING | ERROR (default: INFO)
+    CLM_LOG_FORMAT:     text | json (default: text)
+    CLM_LOG_FILE:       Path to log file (default: stderr only)
+    CLM_LOG_STRUCTURED: true | false (default: false; if true, forces JSON)
+
+Cross-runtime protocol:
+    Rust/WASM/Shell runtimes emit the same JSON schema to stderr,
+    enabling unified observability across language boundaries.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from typing import Any
+
+from clm.cross_cutting.timeutil import default_agent_did, now_g_time
+
+
+class CLMJsonFormatter(logging.Formatter):
+    """JSON formatter for cross-runtime log compatibility."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_entry: dict[str, Any] = {
+            "timestamp": now_g_time(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        for attr in ("agent_did", "run_id", "pcard_hash", "op"):
+            if hasattr(record, attr):
+                log_entry[attr] = getattr(record, attr)
+        return json.dumps(log_entry)
+
+
+class DynamicStreamHandler(logging.StreamHandler):
+    """A StreamHandler that resolves sys.stderr dynamically on every write,
+    allowing unit tests to redirect stderr using sys.stderr = StringIO().
+    """
+
+    @property
+    def stream(self) -> Any:
+        return sys.stderr
+
+    @stream.setter
+    def stream(self, value: Any) -> None:
+        pass
+
+
+class CLMLogger:
+    """Unified logger for the CLM platform.
+
+    Extends Python's logging.Logger with CLM-specific structured fields:
+        - agent_did:  The DID of the executing agent
+        - run_id:     The current CLM run ID
+        - pcard_hash: The PCard being executed (if applicable)
+        - op:         The CEL operation being dispatched (if applicable)
+    """
+
+    _instance: CLMLogger | None = None
+
+    @classmethod
+    def get(cls, name: str = "clm") -> CLMLogger:
+        """Get the singleton CLMLogger instance."""
+        if cls._instance is None:
+            cls._instance = cls(name)
+        return cls._instance
+
+    def __init__(self, name: str = "clm") -> None:
+        self._logger = logging.getLogger(name)
+        self._agent_did = default_agent_did()
+        self._run_id = os.environ.get("CLM_RUN_ID", "")
+        self._configure()
+
+    def _configure(self) -> None:
+        level = os.environ.get("CLM_LOG_LEVEL", "INFO").upper()
+        fmt = os.environ.get("CLM_LOG_FORMAT", "text")
+        log_file = os.environ.get("CLM_LOG_FILE", "")
+
+        self._logger.setLevel(getattr(logging, level, logging.INFO))
+
+        if self._logger.handlers:
+            return
+
+        if fmt == "json" or os.environ.get("CLM_LOG_STRUCTURED", "").lower() == "true":
+            handler: logging.Handler = DynamicStreamHandler()
+            handler.setFormatter(CLMJsonFormatter())
+        else:
+            handler = DynamicStreamHandler()
+            handler.setFormatter(logging.Formatter(
+                "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S%z",
+            ))
+
+        self._logger.addHandler(handler)
+
+        if log_file:
+            file_handler = logging.FileHandler(log_file)
+            file_handler.setFormatter(handler.formatter)
+            self._logger.addHandler(file_handler)
+
+    def _extra(self, **kwargs: Any) -> dict:
+        extra: dict[str, Any] = {"agent_did": self._agent_did, "run_id": self._run_id}
+        extra.update(kwargs)
+        return extra
+
+    def debug(self, msg: str, **kwargs: Any) -> None:
+        exc_info = kwargs.pop("exc_info", None)
+        self._logger.debug(msg, extra=self._extra(**kwargs), exc_info=exc_info)
+
+    def info(self, msg: str, **kwargs: Any) -> None:
+        exc_info = kwargs.pop("exc_info", None)
+        self._logger.info(msg, extra=self._extra(**kwargs), exc_info=exc_info)
+
+    def warning(self, msg: str, **kwargs: Any) -> None:
+        exc_info = kwargs.pop("exc_info", None)
+        self._logger.warning(msg, extra=self._extra(**kwargs), exc_info=exc_info)
+
+    def error(self, msg: str, **kwargs: Any) -> None:
+        exc_info = kwargs.pop("exc_info", None)
+        self._logger.error(msg, extra=self._extra(**kwargs), exc_info=exc_info)
+
+    def critical(self, msg: str, **kwargs: Any) -> None:
+        exc_info = kwargs.pop("exc_info", None)
+        self._logger.critical(msg, extra=self._extra(**kwargs), exc_info=exc_info)
+
+
+
+def get_logger(name: str = "clm") -> CLMLogger:
+    """Convenience function to get the CLMLogger singleton."""
+    return CLMLogger.get(name)