causal-memory-layer 0.4.0__py3-none-any.whl

cml/ctag.py

@@ -0,0 +1,274 @@
+"""
+cml.ctag — Causal Tag (CTAG) computation (v0.4)
+
+16-bit semantic marker:
+
+  b15..b12  DOM   (4 bits) — trust domain
+  b11..b8   CLASS (4 bits) — action class
+  b7..b4    GEN   (4 bits) — generation/epoch (mod 16)
+  b3..b1    LHINT (3 bits) — lineage hint derived from parent_cause
+  b0        SEAL  (1 bit)  — chain continuation flag
+
+Reference: vcml/CTAG.md
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# DOM table
+# ---------------------------------------------------------------------------
+
+class DOM:
+    UNKNOWN     = 0
+    KERNEL      = 1
+    PLATFORM    = 2
+    SERVICE     = 3
+    USER        = 4
+    ADMIN       = 5
+    CI_CD       = 6
+    TENANT_A    = 7
+    TENANT_B    = 8
+    TENANT_C    = 9
+    SANDBOX     = 10
+    UNTRUSTED   = 11
+    THIRD_PARTY = 12
+    AGENT       = 13
+    BREAK_GLASS = 14
+    RESERVED    = 15
+
+    _BY_NAME = {
+        "UNKNOWN": 0, "KERNEL": 1, "PLATFORM": 2, "SERVICE": 3,
+        "USER": 4, "ADMIN": 5, "CI_CD": 6,
+        "TENANT_A": 7, "TENANT_B": 8, "TENANT_C": 9,
+        "SANDBOX": 10, "UNTRUSTED": 11, "THIRD_PARTY": 12,
+        "AGENT": 13, "BREAK_GLASS": 14, "RESERVED": 15,
+    }
+    _BY_VAL = {v: k for k, v in _BY_NAME.items()}
+
+    @staticmethod
+    def name(val: int) -> str:
+        return DOM._BY_VAL.get(val, f"DOM({val})")
+
+    @staticmethod
+    def from_name(name: str) -> int:
+        return DOM._BY_NAME[name.upper()]
+
+
+# ---------------------------------------------------------------------------
+# CLASS table
+# ---------------------------------------------------------------------------
+
+class CLASS:
+    NONE        = 0
+    READ        = 1
+    WRITE       = 2
+    EXEC        = 3
+    NET_OUT     = 4
+    NET_IN      = 5
+    IPC         = 6
+    PRIV        = 7
+    CONFIG      = 8
+    SECRET      = 9
+    CRYPTO      = 10
+    FIN_TX      = 11
+    DATA_EGRESS = 12
+    ML_ACTION   = 13
+    OVERRIDE    = 14
+    SYSTEM      = 15
+
+    _BY_NAME = {
+        "NONE": 0, "READ": 1, "WRITE": 2, "EXEC": 3,
+        "NET_OUT": 4, "NET_IN": 5, "IPC": 6, "PRIV": 7,
+        "CONFIG": 8, "SECRET": 9, "CRYPTO": 10, "FIN_TX": 11,
+        "DATA_EGRESS": 12, "ML_ACTION": 13, "OVERRIDE": 14, "SYSTEM": 15,
+    }
+    _BY_VAL = {v: k for k, v in _BY_NAME.items()}
+
+    @staticmethod
+    def name(val: int) -> str:
+        return CLASS._BY_VAL.get(val, f"CLASS({val})")
+
+    @staticmethod
+    def from_name(name: str) -> int:
+        return CLASS._BY_NAME[name.upper()]
+
+    @staticmethod
+    def from_action(action: str) -> int:
+        mapping = {
+            "exec":    CLASS.EXEC,
+            "open":    CLASS.READ,
+            "read":    CLASS.READ,
+            "write":   CLASS.WRITE,
+            "connect": CLASS.NET_OUT,
+            "send":    CLASS.NET_OUT,
+        }
+        return mapping.get(action.lower(), CLASS.NONE)
+
+
+# ---------------------------------------------------------------------------
+# FNV-1a 64-bit
+# ---------------------------------------------------------------------------
+
+_FNV_OFFSET = 0xcbf29ce484222325
+_FNV_PRIME  = 0x100000001b3
+_U64_MASK   = 0xFFFFFFFFFFFFFFFF
+
+
+def _fnv1a_64(data: str) -> int:
+    h = _FNV_OFFSET
+    for byte in data.encode("utf-8"):
+        h ^= byte
+        h = (h * _FNV_PRIME) & _U64_MASK
+    return h
+
+
+# ---------------------------------------------------------------------------
+# LHINT formula (canonical v0.4)
+# ---------------------------------------------------------------------------
+
+def compute_lhint(parent_cause_id: str, dom: int, cls: int, gen: int) -> int:
+    """
+    LHINT = (FNV1a64(parent_cause_id) XOR (dom<<4) XOR (cls<<0) XOR (gen<<2)) & 0b111
+    """
+    h = _fnv1a_64(parent_cause_id)
+    return int((h ^ (dom << 4) ^ (cls << 0) ^ (gen << 2)) & 0b111)
+
+
+# ---------------------------------------------------------------------------
+# GEN bump rules
+# ---------------------------------------------------------------------------
+
+_GEN_BUMP_ACTIONS = {"exec", "priv"}
+_GEN_BUMP_CLASSES = {CLASS.EXEC, CLASS.PRIV}
+
+
+def should_bump_gen(action: str, cls: int, prev_dom: int, new_dom: int,
+                    entering_break_glass: bool = False,
+                    warn_on_mismatch: bool = True) -> bool:
+    """Determine if the GEN counter should bump.
+
+    Both action string and CLASS enum are checked intentionally: the CLASS
+    enum is the authoritative source, but the action string provides a
+    fallback when the caller hasn't mapped action→class yet.  A semantic
+    contradiction (e.g. action="open" with CLASS.EXEC) indicates a
+    misconfigured caller; the bump is still applied to err on the side of
+    caution (new generation = more conservative audit trail).
+
+    Args:
+        warn_on_mismatch: Emit a ``UserWarning`` when the action string and
+            ``cls`` disagree.  Set to ``False`` when the caller intentionally
+            overrides the default class mapping (e.g. an "open" that requires
+            elevated privileges and is classified as ``CLASS.PRIV``).
+    """
+    # Validate action/CLASS consistency
+    expected_cls = CLASS.from_action(action)
+    if warn_on_mismatch and expected_cls != CLASS.NONE and expected_cls != cls:
+        warnings.warn(
+            f"Action '{action}' maps to {CLASS.name(expected_cls)} but "
+            f"cls={CLASS.name(cls)}; possible misconfiguration "
+            f"(bump applied conservatively).",
+            stacklevel=2,
+        )
+    if entering_break_glass:
+        return True
+    if action.lower() in _GEN_BUMP_ACTIONS:
+        return True
+    if cls in _GEN_BUMP_CLASSES:
+        return True
+    if prev_dom != new_dom:
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Main CTAG computation
+# ---------------------------------------------------------------------------
+
+def compute_ctag(
+    dom: int,
+    cls: int,
+    gen: int,
+    parent_cause_id: Optional[str],
+    seal: bool = False,
+) -> int:
+    """
+    Compute the 16-bit CTAG value.
+
+    If parent_cause_id is None (root event), LHINT is 0.
+    """
+    if parent_cause_id is not None:
+        lhint = compute_lhint(parent_cause_id, dom, cls, gen)
+    else:
+        lhint = 0
+
+    seal_bit = 1 if seal else 0
+
+    ctag = (
+        ((dom   & 0xF) << 12) |
+        ((cls   & 0xF) << 8)  |
+        ((gen   & 0xF) << 4)  |
+        ((lhint & 0x7) << 1)  |
+        seal_bit
+    )
+    return ctag & 0xFFFF
+
+
+def decode_ctag(ctag: int) -> dict:
+    """Decode a 16-bit CTAG value into its components."""
+    dom   = (ctag >> 12) & 0xF
+    cls   = (ctag >> 8)  & 0xF
+    gen   = (ctag >> 4)  & 0xF
+    lhint = (ctag >> 1)  & 0x7
+    seal  = ctag & 0x1
+    return {
+        "raw":       f"0x{ctag:04X}",
+        "dom":       dom,
+        "dom_name":  DOM.name(dom),
+        "class":     cls,
+        "class_name": CLASS.name(cls),
+        "gen":       gen,
+        "lhint":     lhint,
+        "seal":      bool(seal),
+    }
+
+
+# ---------------------------------------------------------------------------
+# CTAG propagation helper
+# ---------------------------------------------------------------------------
+
+class CTAGState:
+    """
+    Tracks CTAG state across a causal chain.
+    Manages GEN bumping and DOM transitions.
+    """
+
+    def __init__(self, dom: int = DOM.USER, gen: int = 0):
+        self.dom = dom
+        self.gen = gen
+
+    def next(
+        self,
+        action: str,
+        cls: int,
+        parent_cause_id: Optional[str],
+        new_dom: Optional[int] = None,
+        seal: bool = False,
+    ) -> int:
+        target_dom = new_dom if new_dom is not None else self.dom
+        if should_bump_gen(action, cls, self.dom, target_dom):
+            self.gen = (self.gen + 1) % 16
+        self.dom = target_dom
+
+        seal_auto = cls in (CLASS.OVERRIDE,)
+        ctag = compute_ctag(
+            dom=self.dom,
+            cls=cls,
+            gen=self.gen,
+            parent_cause_id=parent_cause_id,
+            seal=seal or seal_auto,
+        )
+        return ctag

cml/experimental/__init__.py

@@ -0,0 +1,4 @@
+"""Experimental CML research helpers.
+
+This package is intentionally non-normative. APIs here may change while research concepts mature into stable CML semantics.
+"""

cml/experimental/cause_band.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from .cause_band_trajectory import is_oscillating, recovered_to_safe, trajectory_direction
+
+BAND_RANK = {
+    "safe_range": 0,
+    "warning_range": 1,
+    "danger_range": 2,
+    "critical_range": 3,
+}
+
+RANGE_DRIFT = "CML-AUDIT-RANGE-DRIFT"
+PERSISTENT_DEVIATION = "CML-AUDIT-RANGE-PERSISTENT_DEVIATION"
+CRITICAL_EXIT = "CML-AUDIT-RANGE-CRITICAL_EXIT"
+
+DEFAULT_FIXTURE = Path("benchmarks/experimental/07_range_drift_intent.json")
+
+
+def resolve_fixture_path(path: Path) -> Path:
+    """Resolve fixture path safely, preventing directory traversal and absolute paths.
+    
+    Accepts:
+    - Absolute path: rejected (security)
+    - Path with .. traversal: rejected (security)
+    - Full repo-relative path (e.g., 'benchmarks/experimental/07_*.json'): used as-is if exists
+    - Filename only (e.g., '07_range_drift_intent.json'): resolved within benchmarks/experimental/
+    """
+    base_dir = DEFAULT_FIXTURE.parent.resolve()
+    
+    if path.is_absolute():
+        raise SystemExit(f"Fixture path not allowed: {path}")
+    if any(part == ".." for part in path.parts):
+        raise SystemExit(f"Fixture path not allowed: {path}")
+    
+    # Try to use path as-is first (handles repo-relative full paths)
+    candidate = Path(path)
+    if candidate.exists():
+        resolved = candidate.resolve()
+        # Verify it's still within or under the safety zone
+        try:
+            resolved.relative_to(base_dir.parent)  # Allow within repo
+        except ValueError as exc:
+            raise SystemExit(f"Fixture path not allowed: {path}") from exc
+        return resolved
+    
+    # Fall back to treating it as a filename within base_dir
+    candidate = base_dir / path.name
+    if not candidate.exists():
+        raise SystemExit(f"Fixture not found: {candidate}")
+    
+    resolved = candidate.resolve()
+    try:
+        resolved.relative_to(base_dir)
+    except ValueError as exc:
+        raise SystemExit(f"Fixture path not allowed: {path}") from exc
+    return resolved
+
+
+def parse_duration_threshold(raw: Any, default: int = 3) -> int:
+    if isinstance(raw, int) and raw > 0:
+        return raw
+    if isinstance(raw, str):
+        match = re.match(r"\s*(\d+)", raw)
+        if match:
+            value = int(match.group(1))
+            if value > 0:
+                return value
+    return default
+
+
+def load_fixture(path: Path) -> dict[str, Any]:
+    safe_path = resolve_fixture_path(path)
+    try:
+        raw = json.loads(safe_path.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise SystemExit(f"Fixture not found: {safe_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Invalid JSON in {safe_path}: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise SystemExit(f"Fixture must be a JSON object: {safe_path}")
+    return raw
+
+
+def max_consecutive_outside_safe(ranks: list[int]) -> int:
+    current = 0
+    best = 0
+    for rank in ranks:
+        if rank > BAND_RANK["safe_range"]:
+            current += 1
+            best = max(best, current)
+        else:
+            current = 0
+    return best
+
+
+def evaluate_fixture(raw: dict[str, Any]) -> dict[str, Any]:
+    trajectory = raw.get("trajectory")
+    if not isinstance(trajectory, list) or not trajectory:
+        raise SystemExit("Fixture must contain a non-empty trajectory list")
+
+    bands: list[str] = []
+    ranks: list[int] = []
+    invalid_bands: list[str] = []
+
+    for step in trajectory:
+        if not isinstance(step, dict):
+            raise SystemExit("Each trajectory step must be an object")
+        band = step.get("band")
+        if not isinstance(band, str):
+            raise SystemExit("Each trajectory step must contain a string band")
+        bands.append(band)
+        if band not in BAND_RANK:
+            invalid_bands.append(band)
+            continue
+        ranks.append(BAND_RANK[band])
+
+    if invalid_bands:
+        raise SystemExit(f"Unknown Cause Band values: {sorted(set(invalid_bands))}")
+
+    policy = raw.get("cause_band_policy") if isinstance(raw.get("cause_band_policy"), dict) else {}
+    duration_threshold = parse_duration_threshold(policy.get("duration_threshold"), default=3)
+
+    findings: list[str] = []
+    if any(rank >= BAND_RANK["warning_range"] for rank in ranks):
+        findings.append(RANGE_DRIFT)
+
+    max_consecutive = max_consecutive_outside_safe(ranks)
+    if max_consecutive >= duration_threshold:
+        findings.append(PERSISTENT_DEVIATION)
+
+    if any(rank >= BAND_RANK["critical_range"] for rank in ranks):
+        findings.append(CRITICAL_EXIT)
+
+    expected_future = raw.get("expected_future_cause_band_behavior")
+    expected_codes: list[str] = []
+    if isinstance(expected_future, dict) and isinstance(expected_future.get("expected_codes"), list):
+        expected_codes = sorted(str(code) for code in expected_future["expected_codes"])
+
+    predicted_codes = sorted(findings)
+    return {
+        "case_id": raw.get("case_id"),
+        "status": raw.get("status", "experimental"),
+        "duration_threshold": duration_threshold,
+        "bands": bands,
+        "trajectory_direction": trajectory_direction(ranks),
+        "recovered_to_safe": recovered_to_safe(ranks),
+        "oscillating": is_oscillating(ranks),
+        "max_consecutive_outside_safe": max_consecutive,
+        "predicted_codes": predicted_codes,
+        "expected_future_codes": expected_codes,
+        "matches_expected_future": predicted_codes == expected_codes if expected_codes else None,
+    }
+
+
+def render_text(result: dict[str, Any]) -> str:
+    expected = result["expected_future_codes"] or ["<none>"]
+    lines = [
+        "Experimental Cause Band evaluation",
+        f"case_id={result['case_id']}",
+        f"status={result['status']}",
+        f"duration_threshold={result['duration_threshold']}",
+        f"bands={' -> '.join(result['bands'])}",
+        f"trajectory_direction={result['trajectory_direction']}",
+        f"recovered_to_safe={result['recovered_to_safe']}",
+        f"oscillating={result['oscillating']}",
+        f"max_consecutive_outside_safe={result['max_consecutive_outside_safe']}",
+        f"predicted_codes={','.join(result['predicted_codes']) or '-'}",
+        f"expected_future_codes={','.join(expected)}",
+    ]
+    if result["matches_expected_future"] is not None:
+        lines.append(f"matches_expected_future={result['matches_expected_future']}")
+    return "\n".join(lines)

cml/experimental/cause_band_payload.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_fixture_payload(raw: dict[str, Any]) -> dict[str, Any]:
+    """Return a Cause Band fixture from either a fixture file or example sidecar.
+
+    Some demo files wrap the experimental Cause Band fixture under
+    `cause_band_sidecar` so the same JSON can describe a broader agent trace
+    and still carry a runnable Cause Band payload.
+    """
+    sidecar = raw.get("cause_band_sidecar")
+    if isinstance(sidecar, dict):
+        return sidecar
+    return raw

cml/experimental/cause_band_trajectory.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+SAFE_RANK = 0
+
+
+def recovered_to_safe(ranks: list[int]) -> bool:
+    seen_non_safe = False
+    for rank in ranks:
+        if rank > SAFE_RANK:
+            seen_non_safe = True
+        elif seen_non_safe and rank == SAFE_RANK:
+            return True
+    return False
+
+
+def is_oscillating(ranks: list[int]) -> bool:
+    seen_non_safe = False
+    seen_recovery = False
+    for rank in ranks:
+        if rank > SAFE_RANK:
+            if seen_recovery:
+                return True
+            seen_non_safe = True
+        elif seen_non_safe and rank == SAFE_RANK:
+            seen_recovery = True
+    return False
+
+
+def trajectory_direction(ranks: list[int]) -> str:
+    if len(ranks) < 2:
+        return "stable"
+    if is_oscillating(ranks):
+        return "oscillating"
+
+    deltas = [right - left for left, right in zip(ranks, ranks[1:])]
+    has_up = any(delta > 0 for delta in deltas)
+    has_down = any(delta < 0 for delta in deltas)
+
+    if has_up and not has_down:
+        return "degrading"
+    if has_down and not has_up:
+        return "recovering"
+    if has_up and has_down:
+        if ranks[-1] == SAFE_RANK:
+            return "recovering"
+        return "mixed"
+    return "stable"

cml/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional CML integrations."""

cml/integrations/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP integration for CML agent-audit tools."""

cml/integrations/mcp/core.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from cml import AuditEngine
+from cml.experimental.cause_band import evaluate_fixture
+from cml.experimental.cause_band_payload import extract_fixture_payload
+from cml.record import CausalRecord
+
+
+def health() -> dict[str, Any]:
+    return {
+        "service": "cml-agent-audit-mcp",
+        "status": "ok",
+        "tools": [
+            "health",
+            "audit_trace",
+            "evaluate_cause_band",
+        ],
+        "scope": "experimental MCP integration skeleton",
+    }
+
+
+def _records_from_payload(payload: Any) -> list[CausalRecord]:
+    if isinstance(payload, dict):
+        if isinstance(payload.get("records"), list):
+            raw_records = payload["records"]
+        elif isinstance(payload.get("agent_trace"), list):
+            raw_records = payload["agent_trace"]
+        else:
+            raise ValueError("Trace payload must contain a 'records' or 'agent_trace' list")
+    elif isinstance(payload, list):
+        raw_records = payload
+    else:
+        raise ValueError("Trace payload must be a list or object")
+
+    records: list[CausalRecord] = []
+    for index, raw in enumerate(raw_records):
+        if not isinstance(raw, dict):
+            raise ValueError(f"Trace record at index {index} must be an object")
+        records.append(CausalRecord.from_dict(raw))
+    return records
+
+
+def audit_trace(payload: Any) -> dict[str, Any]:
+    """Run the core CML audit engine over JSON-compatible records."""
+    records = _records_from_payload(payload)
+    return AuditEngine().run(records).to_dict()
+
+
+def evaluate_cause_band(payload: dict[str, Any]) -> dict[str, Any]:
+    """Evaluate a Cause Band fixture or an example containing cause_band_sidecar."""
+    if not isinstance(payload, dict):
+        raise ValueError("Cause Band payload must be an object")
+    return evaluate_fixture(extract_fixture_payload(payload))

cml/integrations/mcp/server.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from . import core
+
+_MISSING_MCP_EXTRA_MESSAGE = """\
+The CML MCP server requires the optional MCP dependency.
+
+Install CML with MCP support:
+
+  pip install "causal-memory-layer[mcp]"
+
+For local development from the repository root:
+
+  pip install -e ".[mcp]"
+"""
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ModuleNotFoundError as exc:
+    if exc.name != "mcp":
+        raise
+    FastMCP = None  # type: ignore[assignment]
+
+
+if FastMCP is not None:
+    mcp = FastMCP("cml-agent-audit")
+
+    @mcp.tool()
+    def health() -> dict[str, Any]:
+        """Return basic CML MCP integration status."""
+        return core.health()
+
+    @mcp.tool()
+    def audit_trace(payload: Any) -> dict[str, Any]:
+        """Audit JSON-compatible CML records or an agent_trace payload."""
+        return core.audit_trace(payload)
+
+    @mcp.tool()
+    def evaluate_cause_band(payload: dict[str, Any]) -> dict[str, Any]:
+        """Evaluate a Cause Band fixture or payload containing cause_band_sidecar."""
+        return core.evaluate_cause_band(payload)
+else:
+    mcp = None
+
+
+def main() -> None:
+    if mcp is None:
+        print(_MISSING_MCP_EXTRA_MESSAGE, file=sys.stderr)
+        raise SystemExit(2)
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()