spanforge 1.0.0__py3-none-any.whl

spanforge/consent.py

@@ -0,0 +1,228 @@
+"""Consent boundary enforcement for SpanForge compliance pipeline.
+
+Provides runtime monitoring that flags agent decisions made on
+out-of-consent data, distinct from PII redaction. Consent enforcement
+checks whether data *should be used at all*, while redaction masks
+sensitive values.
+
+Configuration
+-------------
+* ``consent_enforcement=True`` on :class:`~spanforge.config.SpanForgeConfig`
+  activates consent boundary checks.
+* Call :func:`grant_consent` / :func:`revoke_consent` to manage the
+  consent store, then :func:`check_consent` before data processing.
+
+Emits ``consent.granted``, ``consent.revoked``, ``consent.violation``
+events into the HMAC audit chain via :func:`emit_rfc_event`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from spanforge.namespaces.consent import ConsentPayload
+
+__all__ = [
+    "ConsentBoundary",
+    "ConsentRecord",
+    "check_consent",
+    "grant_consent",
+    "revoke_consent",
+]
+
+
+@dataclass
+class ConsentRecord:
+    """A single consent grant for a data subject."""
+
+    subject_id: str
+    scope: str
+    purpose: str
+    legal_basis: str = "consent"
+    expiry: str | None = None  # ISO 8601
+    data_categories: list[str] = field(default_factory=list)
+
+
+class ConsentBoundary:
+    """Thread-safe runtime consent store and boundary enforcer.
+
+    Manages active consent records and checks data-use against them.
+    Emits HMAC-signed events for grants, revocations, and violations.
+    """
+
+    def __init__(self, *, auto_emit: bool = True) -> None:
+        self._lock = threading.Lock()
+        self._records: dict[tuple[str, str], ConsentRecord] = {}
+        self._auto_emit = auto_emit
+
+    def grant(
+        self,
+        subject_id: str,
+        scope: str,
+        purpose: str,
+        *,
+        legal_basis: str = "consent",
+        expiry: str | None = None,
+        agent_id: str | None = None,
+        data_categories: list[str] | None = None,
+    ) -> ConsentRecord:
+        """Record a consent grant and emit a ``consent.granted`` event."""
+        if not subject_id:
+            raise ValueError("subject_id must be non-empty")
+        if not scope:
+            raise ValueError("scope must be non-empty")
+        if not purpose:
+            raise ValueError("purpose must be non-empty")
+
+        record = ConsentRecord(
+            subject_id=subject_id,
+            scope=scope,
+            purpose=purpose,
+            legal_basis=legal_basis,
+            expiry=expiry,
+            data_categories=data_categories or [],
+        )
+        with self._lock:
+            self._records[(subject_id, scope)] = record
+
+        if self._auto_emit:
+            payload = ConsentPayload(
+                subject_id=subject_id,
+                scope=scope,
+                purpose=purpose,
+                status="granted",
+                legal_basis=legal_basis,
+                expiry=expiry,
+                agent_id=agent_id,
+                data_categories=data_categories or [],
+            )
+            self._emit(payload, "granted")
+        return record
+
+    def revoke(
+        self,
+        subject_id: str,
+        scope: str,
+        *,
+        reason: str = "user request",
+        agent_id: str | None = None,
+    ) -> bool:
+        """Revoke a consent record and emit a ``consent.revoked`` event.
+
+        Returns ``True`` if a matching record was found and removed.
+        """
+        with self._lock:
+            removed = self._records.pop((subject_id, scope), None)
+
+        if removed is not None and self._auto_emit:
+            payload = ConsentPayload(
+                subject_id=subject_id,
+                scope=scope,
+                purpose=removed.purpose,
+                status="revoked",
+                legal_basis=removed.legal_basis,
+                agent_id=agent_id,
+                violation_detail=reason,
+            )
+            self._emit(payload, "revoked")
+        return removed is not None
+
+    def check(
+        self,
+        subject_id: str,
+        scope: str,
+        *,
+        agent_id: str | None = None,
+        purpose: str = "",
+    ) -> bool:
+        """Check whether consent is active for the given subject + scope.
+
+        If no active consent exists, emits a ``consent.violation`` event
+        and returns ``False``.
+        """
+        with self._lock:
+            record = self._records.get((subject_id, scope))
+
+        if record is not None:
+            return True
+
+        # Violation: no consent for this subject + scope
+        if self._auto_emit:
+            payload = ConsentPayload(
+                subject_id=subject_id,
+                scope=scope,
+                purpose=purpose or "unspecified",
+                status="violation",
+                agent_id=agent_id,
+                violation_detail=f"No active consent for subject={subject_id!r} scope={scope!r}",
+            )
+            self._emit(payload, "violation")
+        return False
+
+    def has_consent(self, subject_id: str, scope: str) -> bool:
+        """Return ``True`` if an active consent record exists (no event emitted)."""
+        with self._lock:
+            return (subject_id, scope) in self._records
+
+    def list_consents(self, subject_id: str | None = None) -> list[ConsentRecord]:
+        """Return all active consent records, optionally filtered by subject."""
+        with self._lock:
+            if subject_id is None:
+                return list(self._records.values())
+            return [r for r in self._records.values() if r.subject_id == subject_id]
+
+    def clear(self) -> None:
+        """Remove all consent records (for testing)."""
+        with self._lock:
+            self._records.clear()
+
+    @staticmethod
+    def _emit(payload: ConsentPayload, status: str) -> None:
+        """Emit a consent event into the HMAC audit chain."""
+        try:
+            from spanforge._stream import emit_rfc_event
+            from spanforge.types import EventType
+
+            _status_to_event = {
+                "granted": EventType.CONSENT_GRANTED,
+                "revoked": EventType.CONSENT_REVOKED,
+                "violation": EventType.CONSENT_VIOLATION,
+            }
+            et = _status_to_event.get(status)
+            if et is not None:
+                with contextlib.suppress(Exception):
+                    emit_rfc_event(
+                        et, payload.to_dict()
+                    )  # never let auto-emit failures disrupt the caller
+        except ImportError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton & convenience functions
+# ---------------------------------------------------------------------------
+
+_boundary = ConsentBoundary()
+
+
+def grant_consent(
+    subject_id: str,
+    scope: str,
+    purpose: str,
+    **kwargs: Any,
+) -> ConsentRecord:
+    """Grant consent via the module-level :class:`ConsentBoundary`."""
+    return _boundary.grant(subject_id, scope, purpose, **kwargs)
+
+
+def revoke_consent(subject_id: str, scope: str, **kwargs: Any) -> bool:
+    """Revoke consent via the module-level :class:`ConsentBoundary`."""
+    return _boundary.revoke(subject_id, scope, **kwargs)
+
+
+def check_consent(subject_id: str, scope: str, **kwargs: Any) -> bool:
+    """Check consent via the module-level :class:`ConsentBoundary`."""
+    return _boundary.check(subject_id, scope, **kwargs)

spanforge/consumer.py

@@ -0,0 +1,377 @@
+"""Consumer registration API for spanforge.
+
+Provides a lightweight registry that downstream tools, services, and libraries
+can use to declare which event namespaces and schema versions they depend on.
+This enables proactive compatibility checking between producers and consumers
+before runtime failures occur.
+
+Typical usage::
+
+    from spanforge.consumer import register_consumer, assert_compatible
+
+    # Register your tool's schema requirements.
+    register_consumer(
+        tool_name="my-analytics-pipeline",
+        namespaces=["trace", "eval"],
+        schema_version="1.0",
+    )
+
+    # Later — verify all registered consumers are compatible with the current schema.
+    assert_compatible()   # raises IncompatibleSchemaError if any consumer is incompatible
+
+See :class:`ConsumerRegistry` for the full registry API.
+"""
+
+from __future__ import annotations
+
+import re
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "ConsumerRecord",
+    "ConsumerRegistry",
+    "IncompatibleSchemaError",
+    "assert_compatible",
+    "get_registry",
+    "register_consumer",
+]
+
+# ---------------------------------------------------------------------------
+# Sentinel — current schema version understood by the library
+# ---------------------------------------------------------------------------
+
+_CURRENT_SCHEMA_VERSION = "2.0"
+
+# Accepted schema version patterns (semver-like, e.g. "1.0", "1.1", "2.0")
+_VERSION_RE = re.compile(r"^\d+\.\d+$")
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class IncompatibleSchemaError(Exception):
+    """Raised when a consumer requires a schema version incompatible with the installed one.
+
+    Not compatible with the currently installed library version.
+
+    Attributes:
+        incompatible:  List of ``(tool_name, required_version)`` pairs that
+                       are incompatible with the installed schema version.
+    """
+
+    def __init__(self, incompatible: Sequence[tuple[str, str]]) -> None:
+        self.incompatible = list(incompatible)
+        pairs = ", ".join(f"{t!r} ({v})" for t, v in self.incompatible)
+        super().__init__(
+            f"Incompatible schema consumers: {pairs}. "
+            f"Installed schema version: {_CURRENT_SCHEMA_VERSION}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ConsumerRecord:
+    """A record of a registered consumer's schema requirements.
+
+    Attributes:
+        tool_name:       Human-readable name of the consuming tool or service.
+        namespaces:      Event namespaces the consumer depends on, e.g.
+                         ``["trace", "eval"]``.
+        schema_version:  Minimum schema version required.  Must be in
+                         ``MAJOR.MINOR`` format (e.g. ``"1.0"``).
+        contact:         Optional contact info (e.g. email, team name, Slack
+                         channel) for compatibility issue escalation.
+        metadata:        Optional freeform metadata for tooling.
+    """
+
+    tool_name: str
+    namespaces: tuple[str, ...]
+    schema_version: str
+    contact: str | None = None
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"ConsumerRecord(tool_name={self.tool_name!r}, "
+            f"namespaces={list(self.namespaces)!r}, "
+            f"schema_version={self.schema_version!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+
+class ConsumerRegistry:
+    """Thread-safe registry of downstream consumer schema requirements.
+
+    Consumers register themselves with :meth:`register` declaring which
+    namespaces and schema version they depend on.  Operators can then call
+    :meth:`assert_compatible` to validate all consumers before deploying a
+    new schema version.
+
+    Example::
+
+        registry = ConsumerRegistry()
+        registry.register("my-tool", namespaces=["trace"], schema_version="1.0")
+        registry.assert_compatible()
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._records: list[ConsumerRecord] = []
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        tool_name: str,
+        *,
+        namespaces: Sequence[str],
+        schema_version: str,
+        contact: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> ConsumerRecord:
+        """Register a consumer's schema requirements.
+
+        Args:
+            tool_name:       Name of the consuming tool or service.
+            namespaces:      Event namespaces required (e.g. ``["trace", "eval"]``).
+            schema_version:  Minimum schema version required (``"MAJOR.MINOR"``).
+            contact:         Optional contact info for compatibility escalations.
+            metadata:        Optional freeform metadata dict.
+
+        Returns:
+            The created :class:`ConsumerRecord`.
+
+        Raises:
+            ValueError: If *tool_name* is empty, *namespaces* is empty, or
+                        *schema_version* is not in ``MAJOR.MINOR`` format.
+        """
+        if not tool_name or not tool_name.strip():
+            raise ValueError("tool_name must be a non-empty string")
+        if not namespaces:
+            raise ValueError("namespaces must contain at least one entry")
+        if not _VERSION_RE.match(schema_version):
+            raise ValueError(
+                f"schema_version must be in MAJOR.MINOR format (got {schema_version!r})"
+            )
+
+        record = ConsumerRecord(
+            tool_name=tool_name.strip(),
+            namespaces=tuple(str(ns).strip() for ns in namespaces),
+            schema_version=schema_version,
+            contact=contact,
+            metadata=dict(metadata) if metadata else {},
+        )
+        with self._lock:
+            self._records.append(record)
+        return record
+
+    # ------------------------------------------------------------------
+    # Querying
+    # ------------------------------------------------------------------
+
+    def all(self) -> list[ConsumerRecord]:
+        """Return a snapshot of all registered consumer records.
+
+        Returns:
+            List of all :class:`ConsumerRecord` instances.
+        """
+        with self._lock:
+            return list(self._records)
+
+    def by_namespace(self, namespace: str) -> list[ConsumerRecord]:
+        """Return all consumers that depend on *namespace*.
+
+        Args:
+            namespace: The namespace string to filter by (e.g. ``"trace"``).
+
+        Returns:
+            Filtered list of :class:`ConsumerRecord` instances.
+        """
+        with self._lock:
+            return [r for r in self._records if namespace in r.namespaces]
+
+    def by_tool(self, tool_name: str) -> ConsumerRecord | None:
+        """Return the first record registered under *tool_name*, or ``None``.
+
+        Args:
+            tool_name: The tool name to look up.
+
+        Returns:
+            The :class:`ConsumerRecord` or ``None`` if not found.
+        """
+        with self._lock:
+            for r in self._records:
+                if r.tool_name == tool_name:
+                    return r
+        return None
+
+    # ------------------------------------------------------------------
+    # Compatibility checking
+    # ------------------------------------------------------------------
+
+    def check_compatible(
+        self,
+        installed_version: str = _CURRENT_SCHEMA_VERSION,
+    ) -> list[tuple[str, str]]:
+        """Check all consumers against *installed_version*.
+
+        A consumer is *compatible* if its ``schema_version`` major matches and
+        minor is less than or equal to the installed minor version.  That is:
+
+        * Major version bump → always incompatible (breaking changes).
+        * Minor version bump → backwards-compatible (new events only).
+
+        Args:
+            installed_version: Schema version to check against.  Defaults to
+                                the current library schema version.
+
+        Returns:
+            List of ``(tool_name, required_version)`` pairs that are
+            incompatible.  Empty list means everything is compatible.
+        """
+        try:
+            inst_major, inst_minor = _parse_version(installed_version)
+        except ValueError as exc:
+            raise ValueError(f"installed_version must be MAJOR.MINOR format: {exc}") from exc
+
+        incompatible: list[tuple[str, str]] = []
+        with self._lock:
+            for record in self._records:
+                req_major, req_minor = _parse_version(record.schema_version)
+                if req_major != inst_major or req_minor > inst_minor:
+                    incompatible.append((record.tool_name, record.schema_version))
+        return incompatible
+
+    def assert_compatible(
+        self,
+        installed_version: str = _CURRENT_SCHEMA_VERSION,
+    ) -> None:
+        """Assert that all consumers are compatible with *installed_version*.
+
+        Args:
+            installed_version: Schema version to check against.  Defaults to
+                                the current library schema version.
+
+        Raises:
+            IncompatibleSchemaError: If any registered consumer is incompatible.
+        """
+        incompatible = self.check_compatible(installed_version)
+        if incompatible:
+            raise IncompatibleSchemaError(incompatible)
+
+    def clear(self) -> None:
+        """Remove all records from the registry (useful in tests).
+
+        .. warning::
+            Not safe to call from production code while other threads may be
+            registering consumers.
+        """
+        with self._lock:
+            self._records.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._records)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"ConsumerRegistry(consumers={len(self)})"
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton and helpers
+# ---------------------------------------------------------------------------
+
+_GLOBAL_REGISTRY = ConsumerRegistry()
+
+
+def get_registry() -> ConsumerRegistry:
+    """Return the module-level :class:`ConsumerRegistry` singleton.
+
+    Returns:
+        The global :class:`ConsumerRegistry` instance.
+    """
+    return _GLOBAL_REGISTRY
+
+
+def register_consumer(
+    tool_name: str,
+    *,
+    namespaces: Sequence[str],
+    schema_version: str,
+    contact: str | None = None,
+    metadata: dict[str, str] | None = None,
+) -> ConsumerRecord:
+    """Register a consumer in the global registry.
+
+    Convenience wrapper around :meth:`ConsumerRegistry.register` that operates
+    on the global singleton registry.
+
+    Args:
+        tool_name:       Name of the consuming tool or service.
+        namespaces:      Event namespaces required (e.g. ``["trace", "eval"]``).
+        schema_version:  Minimum schema version required (``"MAJOR.MINOR"``).
+        contact:         Optional contact info for compatibility escalations.
+        metadata:        Optional freeform metadata dict.
+
+    Returns:
+        The created :class:`ConsumerRecord`.
+
+    Raises:
+        ValueError: See :meth:`ConsumerRegistry.register`.
+    """
+    return _GLOBAL_REGISTRY.register(
+        tool_name,
+        namespaces=namespaces,
+        schema_version=schema_version,
+        contact=contact,
+        metadata=metadata,
+    )
+
+
+def assert_compatible(
+    installed_version: str = _CURRENT_SCHEMA_VERSION,
+) -> None:
+    """Assert all globally registered consumers are compatible with *installed_version*.
+
+    Convenience wrapper around :meth:`ConsumerRegistry.assert_compatible` that
+    operates on the global singleton registry.
+
+    Args:
+        installed_version: Schema version to check against.  Defaults to the
+                           current library schema version.
+
+    Raises:
+        IncompatibleSchemaError: If any registered consumer is incompatible.
+    """
+    _GLOBAL_REGISTRY.assert_compatible(installed_version)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_version(version: str) -> tuple[int, int]:
+    """Parse a ``"MAJOR.MINOR"`` version string into ``(int, int)``."""
+    parts = version.split(".", 1)
+    try:
+        return int(parts[0]), int(parts[1])
+    except (IndexError, ValueError) as exc:
+        raise ValueError(f"Not a valid MAJOR.MINOR version: {version!r}") from exc

spanforge/core/__init__.py

@@ -0,0 +1,5 @@
+"""spanforge.core — AI compliance platform core package."""
+
+from __future__ import annotations
+
+__all__: list[str] = []