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

cml/record.py

@@ -0,0 +1,196 @@
+"""
+cml.record — Causal Record model (vCML FORMAT v0)
+
+Defines CausalRecord: the minimal semantic unit of causal memory.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass, field, asdict
+from typing import Optional, Union
+
+
+# ---------------------------------------------------------------------------
+# Action constants (canonical boundary types)
+# ---------------------------------------------------------------------------
+
+class Action:
+    EXEC    = "exec"
+    OPEN    = "open"
+    READ    = "read"
+    WRITE   = "write"
+    CONNECT = "connect"
+    SEND    = "send"
+
+
+# ---------------------------------------------------------------------------
+# Actor
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Actor:
+    pid:  int
+    uid:  int
+    ppid: Optional[int] = None
+    gid:  Optional[int] = None
+    comm: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        d = {"pid": self.pid, "uid": self.uid}
+        if self.ppid is not None:
+            d["ppid"] = self.ppid
+        if self.gid is not None:
+            d["gid"] = self.gid
+        if self.comm is not None:
+            d["comm"] = self.comm
+        return d
+
+    @staticmethod
+    def from_dict(d: dict) -> "Actor":
+        return Actor(
+            pid=d["pid"],
+            uid=d["uid"],
+            ppid=d.get("ppid"),
+            gid=d.get("gid"),
+            comm=d.get("comm"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# CausalRecord
+# ---------------------------------------------------------------------------
+
+@dataclass
+class CausalRecord:
+    """
+    The minimal causal record as defined by vCML FORMAT v0.
+
+    Immutable once created (append-only log semantics).
+    """
+    id:           str
+    timestamp:    int                       # nanoseconds
+    actor:        Actor
+    action:       str                       # see Action constants
+    object:       Union[str, dict]          # path, address, fd, etc.
+    permitted_by: str                       # semantic permission reference
+    parent_cause: Optional[str] = None      # id of parent causal record
+    ctag:         Optional[int] = None      # 16-bit CTAG (v0.4+)
+    integrity:    Optional[str] = None      # hash/sig placeholder (v0.5+)
+
+    # ------------------------------------------------------------------
+    # Convenience
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def new(
+        actor: Actor,
+        action: str,
+        object_: Union[str, dict],
+        permitted_by: str,
+        parent_cause: Optional[str] = None,
+        ctag: Optional[int] = None,
+    ) -> "CausalRecord":
+        return CausalRecord(
+            id=str(uuid.uuid4()),
+            timestamp=time.time_ns(),
+            actor=actor,
+            action=action,
+            object=object_,
+            permitted_by=permitted_by,
+            parent_cause=parent_cause,
+            ctag=ctag,
+        )
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "id":           self.id,
+            "timestamp":    self.timestamp,
+            "actor":        self.actor.to_dict(),
+            "action":       self.action,
+            "object":       self.object,
+            "permitted_by": self.permitted_by,
+            "parent_cause": self.parent_cause,
+        }
+        if self.ctag is not None:
+            d["ctag"] = self.ctag
+        if self.integrity is not None:
+            d["integrity"] = self.integrity
+        return d
+
+    def to_jsonl(self) -> str:
+        return json.dumps(self.to_dict(), separators=(",", ":"))
+
+    @staticmethod
+    def from_dict(d: dict) -> "CausalRecord":
+        required = ("id", "timestamp", "actor", "action", "object", "permitted_by")
+        missing = [k for k in required if k not in d]
+        if missing:
+            raise ValueError(
+                f"CausalRecord missing required field(s): {', '.join(missing)}"
+            )
+        actor_raw = d["actor"]
+        if not isinstance(actor_raw, dict):
+            raise ValueError(f"'actor' must be a dict, got {type(actor_raw).__name__}")
+        try:
+            actor = Actor.from_dict(actor_raw)
+        except KeyError as e:
+            raise ValueError(f"'actor' missing required field: {e.args[0]}") from e
+        return CausalRecord(
+            id=d["id"],
+            timestamp=d["timestamp"],
+            actor=actor,
+            action=d["action"],
+            object=d["object"],
+            permitted_by=d["permitted_by"],
+            parent_cause=d.get("parent_cause"),
+            ctag=d.get("ctag"),
+            integrity=d.get("integrity"),
+        )
+
+    @staticmethod
+    def from_json(line: str) -> "CausalRecord":
+        return CausalRecord.from_dict(json.loads(line))
+
+    # ------------------------------------------------------------------
+    # Semantic helpers
+    # ------------------------------------------------------------------
+
+    def is_root(self, prefix: str = "root_event:") -> bool:
+        """True if this record is an explicit root event.
+
+        Uses the default root_event_prefix ("root_event:").  If your audit
+        pipeline uses a custom AuditConfig.root_event_prefix, pass it here:
+            record.is_root(prefix=config.root_event_prefix)
+        The audit engine always calls cfg.is_root(record) instead, which
+        already respects the configured prefix.
+        """
+        return (
+            self.parent_cause is None
+            and isinstance(self.permitted_by, str)
+            and self.permitted_by.startswith(prefix)
+        )
+
+
+# ---------------------------------------------------------------------------
+# Log loader
+# ---------------------------------------------------------------------------
+
+def load_jsonl(path: str) -> list[CausalRecord]:
+    records = []
+    with open(path, "r") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                records.append(CausalRecord.from_json(line))
+    return records
+
+
+def records_to_index(records: list[CausalRecord]) -> dict[str, CausalRecord]:
+    return {r.id: r for r in records}

cml/report.py

@@ -0,0 +1,132 @@
+"""
+cml.report — Audit report generation
+
+Produces human-readable (Markdown) and machine-readable (JSON) reports
+from AuditResult objects.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Optional
+
+from .audit import AuditResult, Finding, Severity
+from .record import CausalRecord
+from .chain import reconstruct_chain
+
+
+# ---------------------------------------------------------------------------
+# JSON report
+# ---------------------------------------------------------------------------
+
+def to_json(result: AuditResult, indent: int = 2) -> str:
+    return json.dumps(result.to_dict(), indent=indent)
+
+
+# ---------------------------------------------------------------------------
+# Markdown report
+# ---------------------------------------------------------------------------
+
+_SEV_EMOJI = {
+    Severity.OK:   "✅",
+    Severity.WARN: "⚠️",
+    Severity.FAIL: "🔴",
+}
+
+
+def to_markdown(
+    result: AuditResult,
+    title: str = "vCML Audit Report",
+    log_path: Optional[str] = None,
+    index: Optional[dict[str, CausalRecord]] = None,
+) -> str:
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    lines = [
+        f"# {title}",
+        "",
+        f"**Generated:** {now}",
+    ]
+    if log_path:
+        lines.append(f"**Log:** `{log_path}`")
+    lines += [
+        "",
+        "---",
+        "",
+        "## Summary",
+        "",
+        f"| Metric | Value |",
+        f"|--------|-------|",
+        f"| Total records | {result.total} |",
+        f"| Failures | {result.failures} |",
+        f"| Warnings | {result.warnings} |",
+        f"| Overall | {'**PASS**' if result.passed() else '**FAIL**'} |",
+        "",
+    ]
+
+    if not result.findings:
+        lines += ["## Findings", "", "_No issues found._", ""]
+        return "\n".join(lines)
+
+    # Group by severity
+    fails  = [f for f in result.findings if f.severity == Severity.FAIL]
+    warns  = [f for f in result.findings if f.severity == Severity.WARN]
+
+    if fails:
+        lines += ["## Failures", ""]
+        for f in fails:
+            lines += _finding_block(f, index)
+
+    if warns:
+        lines += ["## Warnings", ""]
+        for f in warns:
+            lines += _finding_block(f, index)
+
+    return "\n".join(lines)
+
+
+def _finding_block(
+    finding: Finding,
+    index: Optional[dict[str, CausalRecord]],
+) -> list[str]:
+    emoji = _SEV_EMOJI.get(finding.severity, "")
+    lines = [
+        f"### {emoji} `{finding.code}`",
+        "",
+        f"- **Record:** `{finding.record_id}`",
+        f"- **Message:** {finding.message}",
+    ]
+
+    if finding.chain_ids:
+        lines.append(f"- **Related records:** {', '.join(f'`{i}`' for i in finding.chain_ids)}")
+
+    if index and finding.record_id in index:
+        chain = reconstruct_chain(finding.record_id, index)
+        if len(chain) > 1:
+            lines += ["", "**Reconstructed chain:**", "```"]
+            for r in chain:
+                arrow = "→ " if r.id != chain[0].id else "  "
+                lines.append(
+                    f"{arrow}[{r.id[:8]}] {r.action:8s} "
+                    f"| permitted_by={r.permitted_by} "
+                    f"| parent={r.parent_cause or 'null'}"
+                )
+            lines.append("```")
+
+    lines.append("")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Plain text summary (for terminal)
+# ---------------------------------------------------------------------------
+
+def to_text(result: AuditResult) -> str:
+    lines = [
+        f"CML Audit: {result.total} records | "
+        f"FAIL={result.failures} WARN={result.warnings} OK={result.ok}",
+        "Status: " + ("PASS" if result.passed() else "FAIL"),
+    ]
+    for f in result.findings:
+        lines.append(f"  [{f.severity}] {f.code} @ {f.record_id}: {f.message}")
+    return "\n".join(lines)

cml/safety_eval.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .audit import AuditConfig, AuditEngine
+from .record import CausalRecord
+
+
+@dataclass
+class SafetyEvalCase:
+    case_id: str
+    description: str
+    expected_passed: bool
+    expected_codes: list[str]
+    records: list[CausalRecord]
+    config: AuditConfig = field(default_factory=AuditConfig)
+
+
+@dataclass
+class SafetyEvalResult:
+    case_id: str
+    description: str
+    expected_passed: bool
+    predicted_passed: bool
+    expected_codes: list[str]
+    predicted_codes: list[str]
+    matched: bool
+
+
+@dataclass
+class SafetyEvalSummary:
+    total_cases: int
+    matched_cases: int
+    mismatches: int
+    expected_passed: int
+    expected_failed: int
+    predicted_passed: int
+    predicted_failed: int
+
+
+_ALLOWED_KEYS = {"case_id", "description", "expected_passed", "expected_codes", "records", "config"}
+
+
+def _config_from_raw(raw: dict | None) -> AuditConfig:
+    if raw is None:
+        return AuditConfig()
+    if not isinstance(raw, dict):
+        raise ValueError("config must be an object")
+    return AuditConfig._apply_raw(AuditConfig(), raw)
+
+
+def load_safety_eval_cases(fixtures_root: Path) -> list[SafetyEvalCase]:
+    fixtures_root = Path(fixtures_root)
+    if not fixtures_root.exists():
+        raise FileNotFoundError(f"Fixtures directory not found: {fixtures_root}")
+
+    cases: list[SafetyEvalCase] = []
+    seen: set[str] = set()
+    for path in sorted(fixtures_root.glob("*.json")):
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            raise ValueError(f"{path} must contain a JSON object")
+        unknown = set(raw) - _ALLOWED_KEYS
+        if unknown:
+            raise ValueError(f"{path} contains unsupported keys: {sorted(unknown)}")
+
+        case_id = raw.get("case_id")
+        description = raw.get("description")
+        expected_passed = raw.get("expected_passed")
+        expected_codes = raw.get("expected_codes")
+        records = raw.get("records")
+
+        if not isinstance(case_id, str) or not case_id.strip():
+            raise ValueError(f"{path} is missing a valid case_id")
+        if case_id in seen:
+            raise ValueError(f"Duplicate case_id: {case_id}")
+        seen.add(case_id)
+        if not isinstance(description, str) or not description.strip():
+            raise ValueError(f"{path} is missing a valid description")
+        if not isinstance(expected_passed, bool):
+            raise ValueError(f"{path} is missing a boolean expected_passed")
+        if not isinstance(expected_codes, list) or any(not isinstance(code, str) for code in expected_codes):
+            raise ValueError(f"{path} must define expected_codes as a list of strings")
+        if not isinstance(records, list) or not records:
+            raise ValueError(f"{path} must define a non-empty records list")
+
+        cases.append(
+            SafetyEvalCase(
+                case_id=case_id,
+                description=description,
+                expected_passed=expected_passed,
+                expected_codes=sorted(expected_codes),
+                records=[CausalRecord.from_dict(item) for item in records],
+                config=_config_from_raw(raw.get("config")),
+            )
+        )
+    return cases
+
+
+def run_safety_eval(fixtures_root: Path) -> tuple[list[SafetyEvalResult], SafetyEvalSummary]:
+    cases = load_safety_eval_cases(fixtures_root)
+    results: list[SafetyEvalResult] = []
+
+    expected_passed = 0
+    predicted_passed = 0
+    matched_cases = 0
+
+    for case in cases:
+        audit_result = AuditEngine(case.config).run(case.records)
+        predicted_codes = sorted(f.code for f in audit_result.findings)
+        predicted_ok = audit_result.passed()
+        matched = predicted_ok == case.expected_passed and predicted_codes == case.expected_codes
+        if case.expected_passed:
+            expected_passed += 1
+        if predicted_ok:
+            predicted_passed += 1
+        if matched:
+            matched_cases += 1
+        results.append(
+            SafetyEvalResult(
+                case_id=case.case_id,
+                description=case.description,
+                expected_passed=case.expected_passed,
+                predicted_passed=predicted_ok,
+                expected_codes=case.expected_codes,
+                predicted_codes=predicted_codes,
+                matched=matched,
+            )
+        )
+
+    total_cases = len(cases)
+    return results, SafetyEvalSummary(
+        total_cases=total_cases,
+        matched_cases=matched_cases,
+        mismatches=total_cases - matched_cases,
+        expected_passed=expected_passed,
+        expected_failed=total_cases - expected_passed,
+        predicted_passed=predicted_passed,
+        predicted_failed=total_cases - predicted_passed,
+    )
+
+
+def render_text_report(results: list[SafetyEvalResult], summary: SafetyEvalSummary) -> str:
+    lines = [
+        "CML safety-eval benchmark",
+        f"total_cases={summary.total_cases} matched={summary.matched_cases} mismatches={summary.mismatches}",
+        f"expected_passed={summary.expected_passed} expected_failed={summary.expected_failed}",
+        f"predicted_passed={summary.predicted_passed} predicted_failed={summary.predicted_failed}",
+        "",
+    ]
+    for result in results:
+        status = "PASS" if result.matched else "FAIL"
+        lines.append(
+            f"- {result.case_id}: {status} expected_passed={result.expected_passed} predicted_passed={result.predicted_passed} expected_codes={','.join(result.expected_codes) or '-'} predicted_codes={','.join(result.predicted_codes) or '-'}"
+        )
+    return "\n".join(lines)
+
+
+def render_markdown_report(results: list[SafetyEvalResult], summary: SafetyEvalSummary) -> str:
+    lines = [
+        "# CML Safety-Eval Results",
+        "",
+        "Deterministic benchmark report generated from `benchmarks/fixtures`.",
+        "",
+        "## Summary",
+        "",
+        f"- Total cases: **{summary.total_cases}**",
+        f"- Matched cases: **{summary.matched_cases}**",
+        f"- Mismatches: **{summary.mismatches}**",
+        f"- Expected passed / failed: **{summary.expected_passed} / {summary.expected_failed}**",
+        f"- Predicted passed / failed: **{summary.predicted_passed} / {summary.predicted_failed}**",
+        "",
+        "## Per-case results",
+        "",
+        "| case_id | expected | predicted | status | expected_codes | predicted_codes |",
+        "|---|---|---|---|---|---|",
+    ]
+    for result in results:
+        expected = "pass" if result.expected_passed else "fail"
+        predicted = "pass" if result.predicted_passed else "fail"
+        status = "PASS" if result.matched else "FAIL"
+        expected_codes = "<none>" if not result.expected_codes else ", ".join(result.expected_codes)
+        predicted_codes = "<none>" if not result.predicted_codes else ", ".join(result.predicted_codes)
+        lines.append(
+            f"| {result.case_id} | {expected} | {predicted} | {status} | {expected_codes} | {predicted_codes} |"
+        )
+    return "\n".join(lines) + "\n"