sopvm 0.2.0__py3-none-any.whl

sopvm/__init__.py

@@ -0,0 +1,92 @@
+"""SOPVM — Public API (Milestone 13).
+
+Per INTERFACES.md §8:
+
+    sopvm.compile(sop_path: str, policy_path: str) -> CompiledProgram
+    sopvm.check(compiled: CompiledProgram) -> CheckResult
+    sopvm.Runtime(compiled: CompiledProgram, providers: list[ToolProvider])
+        .run() -> RunResult
+
+Anything not in this list is internal and may change without a version bump.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from typing import TYPE_CHECKING
+
+from sopvm.compiler.pipeline import compile_sop
+from sopvm.ir.model import CompiledProgram
+
+if TYPE_CHECKING:
+    from sopvm.checker.check import CheckResult
+    from sopvm.plugins.base import ToolProvider
+    from sopvm.runtime.executor import RunResult
+
+
+# --- Public API surface ------------------------------------------------------
+
+def compile(sop_path: str, policy_path: str) -> CompiledProgram:
+    """Compile a SOP YAML into a ``CompiledProgram``.
+
+    This is the primary entry point for the compiler pipeline.
+    """
+    return compile_sop(sop_path, policy_path)
+
+
+def check(compiled: CompiledProgram) -> CheckResult:
+    """Check a compiled program against its embedded policy.
+
+    Returns a ``CheckResult`` with ``passed`` (bool) and ``violations``.
+    """
+    from sopvm.checker.check import check as _check
+    from sopvm.capability.policy import load_policy
+    policy = load_policy(compiled.policy_ref)  # type: ignore[attr-defined]
+    return _check(compiled, policy)
+
+
+class Runtime:
+    """Runtime for executing a compiled SOP program.
+
+    Per INTERFACES.md §8::
+
+        sopvm.Runtime(compiled, providers).run() -> RunResult
+    """
+
+    def __init__(
+        self,
+        compiled: CompiledProgram,
+        providers: list[ToolProvider] | None = None,
+    ) -> None:
+        from sopvm.plugins.registry import ProviderRegistry
+
+        self._compiled = compiled
+        self._registry = ProviderRegistry()
+        if providers:
+            for p in providers:
+                self._registry.register(p)
+
+    def run(self) -> RunResult:
+        """Execute the compiled SOP and return a ``RunResult``."""
+        from sopvm.runtime.executor import Executor
+        from sopvm.runtime.state import StepState
+
+        class _SimpleHandler:
+            def execute(self, node, request_tool=None):
+                return StepState.DONE
+
+        executor = Executor(
+            program=self._compiled,
+            handler=_SimpleHandler(),
+            registry=self._registry,
+        )
+        return executor.run()
+
+
+__all__ = [
+    "CompiledProgram",
+    "Runtime",
+    "check",
+    "compile",
+]

sopvm/capability/__init__.py

@@ -0,0 +1,12 @@
+"""Capability token package (Milestone 4)."""
+
+from .policy import Policy, load_policy
+from .token import CapabilityGrammarError, CapabilityToken, parse_capability
+
+__all__ = [
+    "CapabilityGrammarError",
+    "CapabilityToken",
+    "Policy",
+    "load_policy",
+    "parse_capability",
+]

sopvm/capability/policy.py

@@ -0,0 +1,94 @@
+"""Policy loader — parses YAML policy files per INTERFACES.md §3.
+
+Policy format:
+
+```yaml
+policy_version: "0.1"
+allowed_capabilities:
+  - "db:read(orders)"
+  - "payments:refund(max_amount<=100.00)"
+  - "notify:email"
+```
+
+Each entry in ``allowed_capabilities`` is a capability string parsed
+into a ``CapabilityToken``. Comparator params (``<=``, ``>=``, etc.)
+express ceilings that the static checker evaluates against SOP requests.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .token import CapabilityToken, CapabilityGrammarError, parse_capability
+
+
+class PolicyError(Exception):
+    """Raised when a policy file is invalid or missing required fields."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class Policy:
+    """A parsed capability policy.
+
+    Attributes:
+        policy_version: Policy schema version.
+        allowed_capabilities: List of ceiling capability tokens.
+    """
+
+    policy_version: str
+    allowed_capabilities: tuple[CapabilityToken, ...] = field(default_factory=tuple)
+
+
+def load_policy(path: str | Path) -> Policy:
+    """Load and parse a YAML policy file.
+
+    Args:
+        path: Filesystem path to the policy YAML file.
+
+    Returns:
+        A validated ``Policy``.
+
+    Raises:
+        PolicyError: If the file is missing required fields or contains
+            malformed capability strings.
+    """
+    path = Path(path)
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+
+    if not isinstance(raw, dict):
+        raise PolicyError(
+            f"policy file must be a YAML mapping, got {type(raw).__name__}"
+        )
+
+    if "policy_version" not in raw:
+        raise PolicyError("policy file missing required field: policy_version")
+
+    if "allowed_capabilities" not in raw:
+        raise PolicyError("policy file missing required field: allowed_capabilities")
+
+    caps_raw = raw["allowed_capabilities"]
+    if not isinstance(caps_raw, list) or len(caps_raw) == 0:
+        raise PolicyError("allowed_capabilities must be a non-empty list")
+
+    tokens: list[CapabilityToken] = []
+    for entry in caps_raw:
+        if not isinstance(entry, str):
+            raise PolicyError(
+                f"allowed_capabilities entries must be strings, got: {type(entry).__name__}"
+            )
+        try:
+            tokens.append(parse_capability(entry))
+        except CapabilityGrammarError as e:
+            raise PolicyError(f"malformed capability in policy: {e}") from e
+
+    return Policy(
+        policy_version=raw["policy_version"],
+        allowed_capabilities=tuple(tokens),
+    )

sopvm/capability/token.py

@@ -0,0 +1,159 @@
+"""Capability token data model and parser.
+
+Grammar: ``namespace:action(param=value, ...)``
+
+Policy entries may use comparator params (``max_amount<=100.00``) to
+express ceilings. SOP-declared requests use concrete values only
+(``max_amount=100.00``). The parser accepts both forms; the semantic
+distinction is enforced by the checker, not the parser.
+
+Param forms:
+- ``ns:action(key<=value)`` — comparator (policy ceiling)
+- ``ns:action(key=value)`` — named assignment
+- ``ns:action(resource)`` — bare resource identifier
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Matches: namespace:action  or  namespace:action(params)
+_CAP_RE = re.compile(
+    r"^(?P<ns>[a-zA-Z_][a-zA-Z0-9_]*)"
+    r":(?P<action>[a-zA-Z_][a-zA-Z0-9_]*)"
+    r"(?:\((?P<params>.*)\))?$"
+)
+
+# Comparator: key<=value, key>=value, key<value, key>value, key==value
+_PARAM_COMPARATOR_RE = re.compile(
+    r"^\s*(?P<key>[a-zA-Z_][a-zA-Z0-9_]*)"
+    r"\s*(?P<op><=|>=|<|>|==)"
+    r"\s*(?P<value>.+?)\s*$"
+)
+
+# Assignment: key=value
+_PARAM_ASSIGN_RE = re.compile(
+    r"^\s*(?P<key>[a-zA-Z_][a-zA-Z0-9_]*)"
+    r"\s*=\s*"
+    r"(?P<value>.+?)\s*$"
+)
+
+# Bare resource identifier: just a word (e.g. "orders", "/tmp/out")
+_PARAM_BARE_RE = re.compile(
+    r"^\s*(?P<key>.+?)\s*$"
+)
+
+
+class CapabilityGrammarError(Exception):
+    """Raised when a capability string is malformed."""
+
+    def __init__(self, message: str, raw: str | None = None) -> None:
+        self.raw = raw
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class CapabilityToken:
+    """A parsed capability token.
+
+    Attributes:
+        namespace: The capability namespace (e.g. ``db``, ``payments``).
+        action: The action within the namespace (e.g. ``read``, ``refund``).
+        params: Parsed parameters. Values may be:
+            - ``True`` for bare resource identifiers (e.g. ``db:read(orders)``)
+            - ``str`` or ``float`` for assignment params (e.g. ``channel=slack``)
+            - ``{"op": str, "value": float|str}`` for comparator params
+        raw: The original unparsed string.
+    """
+
+    namespace: str
+    action: str
+    params: dict[str, str | float | bool | dict[str, str | float]]
+    raw: str
+
+
+def parse_capability(s: str) -> CapabilityToken:
+    """Parse a capability string into a ``CapabilityToken``.
+
+    Accepts both concrete requests (``ns:action(k=v)``) and ceiling
+    expressions with comparators (``ns:action(k<=v)``).
+
+    Args:
+        s: The capability string to parse.
+
+    Returns:
+        A ``CapabilityToken``.
+
+    Raises:
+        CapabilityGrammarError: If the string doesn't match the grammar.
+    """
+    m = _CAP_RE.match(s)
+    if not m:
+        raise CapabilityGrammarError(
+            f"malformed capability string: {s!r}", raw=s
+        )
+
+    ns = m.group("ns")
+    action = m.group("action")
+    params_str = m.group("params")
+
+    params: dict[str, str | float | bool | dict[str, str | float]] = {}
+    if params_str and params_str.strip():
+        for param_part in _split_params(params_str):
+            # Try comparator first: key<=value
+            pm = _PARAM_COMPARATOR_RE.match(param_part)
+            if pm:
+                params[pm.group("key")] = {
+                    "op": pm.group("op"),
+                    "value": _coerce_value(pm.group("value")),
+                }
+                continue
+
+            # Try assignment: key=value
+            pm = _PARAM_ASSIGN_RE.match(param_part)
+            if pm:
+                params[pm.group("key")] = _coerce_value(pm.group("value"))
+                continue
+
+            # Bare resource identifier
+            key = param_part.strip()
+            if key:
+                params[key] = True
+            else:
+                raise CapabilityGrammarError(
+                    f"empty parameter in capability {s!r}",
+                    raw=s,
+                )
+
+    return CapabilityToken(namespace=ns, action=action, params=params, raw=s)
+
+
+def _split_params(params_str: str) -> list[str]:
+    """Split a parameter string on commas, respecting parentheses."""
+    parts = []
+    depth = 0
+    current: list[str] = []
+    for ch in params_str:
+        if ch == "(":
+            depth += 1
+            current.append(ch)
+        elif ch == ")":
+            depth -= 1
+            current.append(ch)
+        elif ch == "," and depth == 0:
+            parts.append("".join(current))
+            current = []
+        else:
+            current.append(ch)
+    if current:
+        parts.append("".join(current))
+    return parts
+
+
+def _coerce_value(raw: str) -> str | float:
+    """Try to parse a value as a float, otherwise keep as string."""
+    try:
+        return float(raw)
+    except ValueError:
+        return raw

sopvm/checker/__init__.py

@@ -0,0 +1,5 @@
+"""Checker package (Milestone 4)."""
+
+from .check import CheckResult, Violation, check, satisfies
+
+__all__ = ["CheckResult", "Violation", "check", "satisfies"]

sopvm/checker/check.py

@@ -0,0 +1,176 @@
+"""Static capability checker (Milestone 4).
+
+Deterministic, side-effect-free: checks a compiled IR against a policy
+without any I/O beyond loading the input files. This is the project's
+headline claim — pure static analysis, usable as a pre-commit hook.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sopvm.capability.policy import Policy
+from sopvm.capability.token import CapabilityToken, parse_capability
+from sopvm.ir.model import CompiledProgram
+
+
+@dataclass(frozen=True)
+class Violation:
+    """A single capability policy violation.
+
+    Attributes:
+        step_id: The step that requested the violating capability.
+        requested: The raw capability string that was requested.
+        reason: Human-readable explanation of why it was denied.
+    """
+
+    step_id: str
+    requested: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    """Result of a static capability check.
+
+    Attributes:
+        passed: True if no violations were found.
+        violations: List of violations (empty if passed).
+    """
+
+    passed: bool
+    violations: tuple[Violation, ...] = field(default_factory=tuple)
+
+
+def satisfies(requested: CapabilityToken, allowed: CapabilityToken) -> bool:
+    """Check if a requested capability satisfies a policy ceiling.
+
+    Rules:
+    - namespace and action must match exactly.
+    - For each param in ``allowed`` that has a comparator (``<=``, ``>=``,
+      ``<``, ``>``, ``==``), the corresponding param in ``requested`` must
+      satisfy it numerically.
+    - Params in ``allowed`` without comparators must match exactly.
+    - Params in ``requested`` not mentioned in ``allowed`` are unconstrained
+      (allowed is a ceiling, not an exact-match contract).
+
+    Design note: this means a request can carry extra params beyond what
+    the policy mentions, and still pass. This is intentional — the policy
+    is a ceiling on constrained dimensions, not a whitelist of all params.
+    This choice is flagged for discussion in the PR description.
+    """
+    if requested.namespace != allowed.namespace:
+        return False
+    if requested.action != allowed.action:
+        return False
+
+    for key, allowed_val in allowed.params.items():
+        requested_val = requested.params.get(key)
+        if requested_val is None:
+            # Param in allowed but not in requested — violation.
+            return False
+
+        if isinstance(allowed_val, dict):
+            # Comparator param in policy ceiling.
+            op = allowed_val["op"]
+            ceiling = allowed_val["value"]
+            if not _compare(requested_val, op, ceiling):
+                return False
+        elif allowed_val is True:
+            # Bare param in allowed — requested must also have bare param.
+            if requested_val is not True:
+                return False
+        else:
+            # Named param — exact match.
+            if requested_val != allowed_val:
+                return False
+
+    return True
+
+
+def _compare(
+    requested: object,
+    op: object,
+    ceiling: object,
+) -> bool:
+    """Evaluate a single comparator constraint."""
+    req = _to_float(requested)
+    ceil = _to_float(ceiling)
+    if req is None or ceil is None:
+        # Non-numeric values: only == and != are meaningful.
+        if op == "==":
+            return requested == ceiling
+        return False
+
+    if op == "<=":
+        return req <= ceil
+    elif op == ">=":
+        return req >= ceil
+    elif op == "<":
+        return req < ceil
+    elif op == ">":
+        return req > ceil
+    elif op == "==":
+        return req == ceil
+    return False
+
+
+def _to_float(v: object) -> float | None:
+    if isinstance(v, (int, float)):
+        return float(v)
+    try:
+        return float(v)  # type: ignore[arg-type]
+    except (ValueError, TypeError):
+        return None
+
+
+def check(program: CompiledProgram, policy: Policy) -> CheckResult:
+    """Static check: does every declared capability satisfy the policy?
+
+    For every ``IrNode``, for every capability in ``capabilities_declared``,
+    check it against every entry in ``policy.allowed_capabilities``. If
+    none satisfy, record a violation.
+
+    Malformed capability strings are caught and reported as violations
+    rather than raising exceptions — the checker must not crash on bad input.
+
+    This function is fully deterministic and side-effect-free.
+    """
+    from sopvm.capability.token import CapabilityGrammarError
+
+    violations: list[Violation] = []
+
+    for step_id, node in program.nodes.items():
+        for cap_str in node.capabilities_declared:
+            try:
+                token = parse_capability(cap_str)
+            except CapabilityGrammarError:
+                violations.append(Violation(
+                    step_id=step_id,
+                    requested=cap_str,
+                    reason=f"malformed capability string {cap_str!r}",
+                ))
+                continue
+
+            if not any(satisfies(token, allowed) for allowed in policy.allowed_capabilities):
+                # Find the ceiling for the reason message.
+                matching = [
+                    a for a in policy.allowed_capabilities
+                    if a.namespace == token.namespace and a.action == token.action
+                ]
+                if matching:
+                    ceiling_str = matching[0].raw
+                    reason = f"exceeds policy ceiling {ceiling_str}"
+                else:
+                    reason = f"capability {cap_str!r} not mentioned in policy"
+
+                violations.append(Violation(
+                    step_id=step_id,
+                    requested=cap_str,
+                    reason=reason,
+                ))
+
+    return CheckResult(
+        passed=len(violations) == 0,
+        violations=tuple(violations),
+    )

sopvm/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package (Milestone 11)."""