loopx 0.4.8__py3-none-any.whl

loopx/capabilities/decision_context/private_state.py

@@ -0,0 +1,189 @@
+"""Private cursor-state IO for Decision Context."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from collections.abc import Mapping
+from pathlib import Path
+
+from .assembler import DecisionContextAssembly
+from .profile import DecisionContextProfile
+
+
+DECISION_PENDING_SETTLEMENT_SCHEMA_VERSION = (
+    "decision_context_pending_settlement_v0"
+)
+
+
+def load_private_decision_cursors(
+    path: Path | None,
+    *,
+    profile: DecisionContextProfile,
+) -> dict[str, str]:
+    """Load private cursors without projecting their values into public output."""
+
+    if path is None or not path.expanduser().exists():
+        return {}
+    try:
+        with path.expanduser().open(encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError("decision-context cursor state is unavailable") from exc
+    if not isinstance(payload, Mapping):
+        raise ValueError("decision-context cursor state must be an object")
+
+    source_ids = {source.source_id for source in profile.sources}
+    unexpected = sorted(str(key) for key in payload if str(key) not in source_ids)
+    if unexpected:
+        raise ValueError(
+            "decision-context cursor state contains unknown source ids: "
+            + ", ".join(unexpected)
+        )
+
+    cursors: dict[str, str] = {}
+    for source_id, value in payload.items():
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError("decision-context cursor values must be non-empty strings")
+        cursors[str(source_id)] = value.strip()
+    return cursors
+
+
+def private_file_digest(path: Path) -> str:
+    try:
+        payload = path.expanduser().read_bytes()
+    except OSError as exc:
+        raise ValueError("decision-context private state is unavailable") from exc
+    return hashlib.sha256(payload).hexdigest()
+
+
+def write_private_decision_cursors_atomic(
+    path: Path,
+    cursors: Mapping[str, str],
+) -> None:
+    _write_private_json_atomic(path, dict(sorted(cursors.items())))
+
+
+def write_private_pending_decision_settlement(
+    path: Path,
+    assembly: DecisionContextAssembly,
+) -> None:
+    """Persist unapplied cursor proposals for a cross-turn owner gate."""
+
+    _write_private_json_atomic(
+        path,
+        {
+            "schema_version": DECISION_PENDING_SETTLEMENT_SCHEMA_VERSION,
+            "assembly": assembly.public_packet(),
+            "proposed_cursors": dict(sorted(assembly.proposed_cursors.items())),
+            "expected_cursors": dict(sorted(assembly.expected_cursors.items())),
+            "profile_digest": assembly.profile_digest,
+            "runtime_bound_provider_ids": list(assembly.runtime_bound_provider_ids),
+            "active_cursor_state_mutated": False,
+        },
+    )
+
+
+def load_private_pending_decision_settlement(
+    path: Path,
+) -> DecisionContextAssembly:
+    """Reload a private pending settlement without exposing cursor values."""
+
+    try:
+        with path.expanduser().open(encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError("decision-context pending settlement is unavailable") from exc
+    if not isinstance(payload, Mapping):
+        raise ValueError("decision-context pending settlement must be an object")
+    allowed = {
+        "schema_version",
+        "assembly",
+        "proposed_cursors",
+        "expected_cursors",
+        "profile_digest",
+        "runtime_bound_provider_ids",
+        "active_cursor_state_mutated",
+    }
+    if set(payload) != allowed:
+        raise ValueError("decision-context pending settlement fields are invalid")
+    if payload.get("schema_version") != DECISION_PENDING_SETTLEMENT_SCHEMA_VERSION:
+        raise ValueError("decision-context pending settlement schema is invalid")
+    if payload.get("active_cursor_state_mutated") is not False:
+        raise ValueError("decision-context pending settlement cannot apply cursors")
+    assembly = payload.get("assembly")
+    proposed = payload.get("proposed_cursors")
+    expected = payload.get("expected_cursors")
+    provider_ids = payload.get("runtime_bound_provider_ids")
+    profile_digest = payload.get("profile_digest")
+    if not isinstance(assembly, Mapping):
+        raise ValueError("decision-context pending assembly is invalid")
+    if not isinstance(proposed, Mapping) or any(
+        not isinstance(key, str)
+        or not isinstance(value, str)
+        or not key.strip()
+        or not value.strip()
+        for key, value in proposed.items()
+    ):
+        raise ValueError("decision-context pending cursor proposals are invalid")
+    if not isinstance(expected, Mapping) or any(
+        not isinstance(key, str)
+        or not key.strip()
+        or (value is not None and (not isinstance(value, str) or not value.strip()))
+        for key, value in expected.items()
+    ):
+        raise ValueError("decision-context pending expected cursors are invalid")
+    if (
+        isinstance(provider_ids, (str, bytes))
+        or not isinstance(provider_ids, list)
+        or any(not isinstance(value, str) or not value.strip() for value in provider_ids)
+    ):
+        raise ValueError("decision-context pending provider ids are invalid")
+    if not isinstance(profile_digest, str) or not profile_digest.strip():
+        raise ValueError("decision-context pending profile digest is invalid")
+    return DecisionContextAssembly(
+        packet=dict(assembly),
+        proposed_cursors={str(key): str(value) for key, value in proposed.items()},
+        expected_cursors={str(key): value for key, value in expected.items()},
+        profile_digest=profile_digest,
+        runtime_bound_provider_ids=tuple(sorted(set(provider_ids))),
+    )
+
+
+def _write_private_json_atomic(
+    path: Path,
+    payload: Mapping[str, object],
+) -> None:
+    destination = path.expanduser()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{destination.name}.",
+        suffix=".tmp",
+        dir=destination.parent,
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(
+                payload,
+                handle,
+                ensure_ascii=True,
+                sort_keys=True,
+                separators=(",", ":"),
+            )
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, destination)
+        directory_fd = os.open(
+            destination.parent,
+            os.O_RDONLY | getattr(os, "O_DIRECTORY", 0),
+        )
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    finally:
+        temporary.unlink(missing_ok=True)

loopx/capabilities/decision_context/profile.py

@@ -0,0 +1,453 @@
+"""Default-off, goal-scoped Decision Context profile and activation status."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Collection, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .providers import decision_source_provider_registered
+from .sources import DecisionSourceSpec
+
+DECISION_CONTEXT_PROFILE_SCHEMA_VERSION = "decision_context_profile_v0"
+DECISION_CONTEXT_ACTIVATION_STATUS_SCHEMA_VERSION = (
+    "decision_context_activation_status_v0"
+)
+MAX_DECISION_SOURCES = 64
+MAX_SOURCE_PROVIDER_BINDINGS = 16
+
+_TOKEN_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
+_CONFIG_FIELDS = {
+    "schema_version",
+    "goal_id",
+    "enabled",
+    "enabled_agents",
+    "source_provider_bindings",
+    "sources",
+    "context_provider",
+    "automation",
+}
+_PROVIDER_BINDING_FIELDS = {"provider_id", "adapter", "config"}
+_SOURCE_FIELDS = {
+    "source_id",
+    "provider_id",
+    "source_kind",
+    "priority",
+    "evidence_level",
+    "objectives",
+    "scan_mode",
+    "exact_read_policy",
+    "freshness_seconds",
+    "private_locator",
+    "max_changes",
+    "enabled",
+}
+_CONTEXT_PROVIDER_FIELDS = {
+    "provider",
+    "namespace",
+    "scope_ref",
+    "max_results",
+    "timeout_seconds",
+    "config",
+}
+_AUTOMATION_FIELDS = {"automatic_capture", "fail_open"}
+
+
+def _strict_mapping(
+    value: object,
+    *,
+    label: str,
+    allowed: set[str],
+) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise ValueError(f"{label} must be an object")
+    unexpected = sorted(set(value) - allowed)
+    if unexpected:
+        raise ValueError(
+            f"{label} contains unsupported fields: {', '.join(unexpected)}"
+        )
+    return value
+
+
+def _bounded_mappings(
+    value: object,
+    *,
+    label: str,
+    maximum: int,
+    allow_empty: bool = False,
+) -> list[Mapping[str, Any]]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes)):
+        raise ValueError(f"{label} must be a bounded object list")
+    rows = list(value)
+    if (not allow_empty and not rows) or len(rows) > maximum:
+        raise ValueError(f"{label} must be a bounded object list")
+    if any(not isinstance(row, Mapping) for row in rows):
+        raise ValueError(f"{label} must be a bounded object list")
+    return rows
+
+
+def _token(value: object, *, field_name: str) -> str:
+    text = str(value or "").strip()
+    if not _TOKEN_RE.fullmatch(text):
+        raise ValueError(f"{field_name} must be a compact public-safe token")
+    return text
+
+
+def _boolean(value: object, *, field_name: str) -> bool:
+    if not isinstance(value, bool):
+        raise ValueError(f"{field_name} must be a boolean")
+    return value
+
+
+def _positive_number(
+    value: object,
+    *,
+    field_name: str,
+    maximum: float,
+) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{field_name} must be a positive number")
+    result = float(value)
+    if not 0 < result <= maximum:
+        raise ValueError(f"{field_name} must be between 0 and {maximum}")
+    return result
+
+
+def _positive_int(
+    value: object,
+    *,
+    field_name: str,
+    maximum: int,
+) -> int:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int)
+        or not 1 <= value <= maximum
+    ):
+        raise ValueError(f"{field_name} must be between 1 and {maximum}")
+    return value
+
+
+@dataclass(frozen=True)
+class DecisionSourceProviderBinding:
+    provider_id: str
+    adapter: str
+    config: Mapping[str, Any] = field(repr=False)
+
+    def public_record(self, *, runtime_bound: bool = False) -> dict[str, object]:
+        adapter_registered = decision_source_provider_registered(self.adapter)
+        return {
+            "adapter": (
+                "runtime-bound"
+                if runtime_bound
+                else self.adapter
+                if adapter_registered
+                else "unregistered"
+            ),
+            "adapter_registered": adapter_registered,
+            "runtime_bound": runtime_bound,
+            "private_config_captured": False,
+        }
+
+
+@dataclass(frozen=True)
+class DecisionContextProfile:
+    goal_id: str
+    enabled: bool
+    enabled_agents: tuple[str, ...]
+    provider_bindings: tuple[DecisionSourceProviderBinding, ...]
+    sources: tuple[DecisionSourceSpec, ...]
+    context_provider: Mapping[str, Any] | None = field(default=None, repr=False)
+    automatic_capture: bool = False
+    fail_open: bool = True
+
+    def provider_binding_map(self) -> dict[str, Mapping[str, Any]]:
+        return {
+            binding.provider_id: {
+                "provider_id": binding.provider_id,
+                "adapter": binding.adapter,
+                "config": dict(binding.config),
+            }
+            for binding in self.provider_bindings
+        }
+
+
+def normalize_decision_context_profile(
+    raw: Mapping[str, Any],
+) -> DecisionContextProfile:
+    config = _strict_mapping(
+        raw,
+        label="decision-context profile",
+        allowed=_CONFIG_FIELDS,
+    )
+    if config.get("schema_version") != DECISION_CONTEXT_PROFILE_SCHEMA_VERSION:
+        raise ValueError(
+            "decision-context profile must use "
+            + DECISION_CONTEXT_PROFILE_SCHEMA_VERSION
+        )
+    goal_id = _token(config.get("goal_id"), field_name="goal_id")
+    enabled = _boolean(config.get("enabled"), field_name="enabled")
+
+    raw_agents = config.get("enabled_agents")
+    if not isinstance(raw_agents, Sequence) or isinstance(raw_agents, (str, bytes)):
+        raise ValueError("enabled_agents must be a bounded token list")
+    enabled_agents = tuple(
+        sorted({_token(value, field_name="enabled_agents[]") for value in raw_agents})
+    )
+    if enabled and not enabled_agents:
+        raise ValueError("an enabled profile requires at least one enabled agent")
+
+    bindings: list[DecisionSourceProviderBinding] = []
+    binding_ids: set[str] = set()
+    for index, row in enumerate(
+        _bounded_mappings(
+            config.get("source_provider_bindings"),
+            label="source_provider_bindings",
+            maximum=MAX_SOURCE_PROVIDER_BINDINGS,
+            allow_empty=True,
+        )
+    ):
+        binding = _strict_mapping(
+            row,
+            label=f"source_provider_bindings[{index}]",
+            allowed=_PROVIDER_BINDING_FIELDS,
+        )
+        provider_id = _token(binding.get("provider_id"), field_name="provider_id")
+        if provider_id in binding_ids:
+            raise ValueError("source provider ids must be unique")
+        adapter = _token(binding.get("adapter"), field_name="adapter")
+        private_config = binding.get("config", {})
+        if not isinstance(private_config, Mapping):
+            raise ValueError("source provider config must be an object")
+        bindings.append(
+            DecisionSourceProviderBinding(
+                provider_id=provider_id,
+                adapter=adapter,
+                config=dict(private_config),
+            )
+        )
+        binding_ids.add(provider_id)
+
+    sources: list[DecisionSourceSpec] = []
+    source_ids: set[str] = set()
+    for index, row in enumerate(
+        _bounded_mappings(
+            config.get("sources"),
+            label="sources",
+            maximum=MAX_DECISION_SOURCES,
+            allow_empty=True,
+        )
+    ):
+        source = _strict_mapping(
+            row,
+            label=f"sources[{index}]",
+            allowed=_SOURCE_FIELDS,
+        )
+        objectives = source.get("objectives")
+        if not isinstance(objectives, Sequence) or isinstance(
+            objectives,
+            (str, bytes),
+        ):
+            raise ValueError("source objectives must be a list")
+        freshness_seconds = _positive_int(
+            source.get("freshness_seconds"),
+            field_name="freshness_seconds",
+            maximum=365 * 24 * 60 * 60,
+        )
+        max_changes = _positive_int(
+            source.get("max_changes", 20),
+            field_name="max_changes",
+            maximum=100,
+        )
+        source_enabled = _boolean(
+            source.get("enabled", True),
+            field_name="source enabled",
+        )
+        spec = DecisionSourceSpec(
+            source_id=str(source.get("source_id") or ""),
+            provider_id=str(source.get("provider_id") or ""),
+            source_kind=str(source.get("source_kind") or ""),
+            priority=str(source.get("priority") or ""),
+            evidence_level=str(source.get("evidence_level") or ""),
+            objectives=tuple(str(value) for value in objectives),
+            scan_mode=str(source.get("scan_mode") or ""),
+            exact_read_policy=str(source.get("exact_read_policy") or ""),
+            freshness_seconds=freshness_seconds,
+            private_locator=str(source.get("private_locator") or ""),
+            max_changes=max_changes,
+            enabled=source_enabled,
+        )
+        if spec.source_id in source_ids:
+            raise ValueError("source ids must be unique")
+        if spec.provider_id not in binding_ids:
+            raise ValueError("every source must reference a declared provider binding")
+        sources.append(spec)
+        source_ids.add(spec.source_id)
+    if enabled and not sources:
+        raise ValueError("an enabled profile requires at least one source")
+
+    context_provider: Mapping[str, Any] | None = None
+    raw_context_provider = config.get("context_provider")
+    if raw_context_provider is not None:
+        context = _strict_mapping(
+            raw_context_provider,
+            label="context_provider",
+            allowed=_CONTEXT_PROVIDER_FIELDS,
+        )
+        private_config = context.get("config", {})
+        if not isinstance(private_config, Mapping):
+            raise ValueError("context provider config must be an object")
+        context_provider = {
+            "provider": _token(context.get("provider"), field_name="context provider"),
+            "namespace": _token(context.get("namespace"), field_name="namespace"),
+            "scope_ref": str(context.get("scope_ref") or "").strip(),
+            "max_results": _positive_int(
+                context.get("max_results", 4),
+                field_name="max_results",
+                maximum=8,
+            ),
+            "timeout_seconds": _positive_number(
+                context.get("timeout_seconds", 10),
+                field_name="timeout_seconds",
+                maximum=60,
+            ),
+            "config": dict(private_config),
+        }
+        if not context_provider["scope_ref"]:
+            raise ValueError("context provider scope_ref is required")
+
+    automation = _strict_mapping(
+        config.get("automation"),
+        label="automation",
+        allowed=_AUTOMATION_FIELDS,
+    )
+    automatic_capture = _boolean(
+        automation.get("automatic_capture"),
+        field_name="automatic_capture",
+    )
+    fail_open = _boolean(automation.get("fail_open"), field_name="fail_open")
+    if automatic_capture:
+        raise ValueError("decision-context automatic capture must stay disabled")
+    if not fail_open:
+        raise ValueError("decision-context providers must fail open")
+
+    return DecisionContextProfile(
+        goal_id=goal_id,
+        enabled=enabled,
+        enabled_agents=enabled_agents,
+        provider_bindings=tuple(bindings),
+        sources=tuple(sources),
+        context_provider=context_provider,
+        automatic_capture=False,
+        fail_open=True,
+    )
+
+
+def load_decision_context_profile(
+    path: Path,
+) -> DecisionContextProfile:
+    try:
+        with path.expanduser().open(encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError("decision-context profile is unavailable") from exc
+    if not isinstance(payload, Mapping):
+        raise ValueError("decision-context profile must be an object")
+    return normalize_decision_context_profile(payload)
+
+
+def resolve_decision_context_activation(
+    *,
+    goal_id: str,
+    agent_id: str,
+    profile_path: Path | None,
+    available_source_provider_ids: Collection[str] | None = None,
+) -> tuple[dict[str, Any], DecisionContextProfile | None]:
+    normalized_goal = _token(goal_id, field_name="goal_id")
+    normalized_agent = _token(agent_id, field_name="agent_id")
+    if isinstance(available_source_provider_ids, (str, bytes)):
+        raise TypeError("available_source_provider_ids must be a collection")
+    runtime_provider_ids = {
+        _token(provider_id, field_name="available_source_provider_ids[]")
+        for provider_id in (available_source_provider_ids or ())
+    }
+    base: dict[str, Any] = {
+        "ok": True,
+        "schema_version": DECISION_CONTEXT_ACTIVATION_STATUS_SCHEMA_VERSION,
+        "capability_id": "decision_context",
+        "scope": "goal",
+        "default_enabled": False,
+        "goal_id": normalized_goal,
+        "agent_id": normalized_agent,
+        "profile_configured": profile_path is not None,
+        "enabled": False,
+        "configured_for_agent": False,
+        "available": False,
+        "source_count": 0,
+        "source_provider_count": 0,
+        "runtime_bound_provider_count": 0,
+        "context_provider_configured": False,
+        "automatic_capture": False,
+        "fail_open": True,
+        "external_writes_performed": False,
+        "raw_content_captured": False,
+        "private_locator_captured": False,
+        "credentials_captured": False,
+    }
+    if profile_path is None:
+        return base | {"status": "disabled"}, None
+    try:
+        config = load_decision_context_profile(profile_path)
+    except ValueError:
+        return base | {
+            "status": "profile_invalid",
+            "reason_code": "profile_unavailable_or_invalid",
+        }, None
+    if config.goal_id != normalized_goal:
+        return base | {
+            "status": "profile_invalid",
+            "reason_code": "goal_scope_mismatch",
+        }, None
+
+    configured_for_agent = normalized_agent in config.enabled_agents
+    declared_provider_ids = {
+        binding.provider_id for binding in config.provider_bindings
+    }
+    if not runtime_provider_ids <= declared_provider_ids:
+        return base | {
+            "status": "profile_invalid",
+            "reason_code": "runtime_provider_scope_mismatch",
+        }, config
+    provider_records = [
+        binding.public_record(
+            runtime_bound=binding.provider_id in runtime_provider_ids,
+        )
+        for binding in config.provider_bindings
+    ]
+    unavailable_adapter_count = sum(
+        not bool(record["adapter_registered"]) and not bool(record["runtime_bound"])
+        for record in provider_records
+    )
+    status = base | {
+        "enabled": config.enabled,
+        "configured_for_agent": configured_for_agent,
+        "source_count": len(config.sources),
+        "source_provider_count": len(config.provider_bindings),
+        "runtime_bound_provider_count": len(runtime_provider_ids),
+        "source_providers": provider_records,
+        "context_provider_configured": config.context_provider is not None,
+    }
+    if not config.enabled:
+        return status | {"status": "disabled"}, config
+    if not configured_for_agent:
+        return status | {"status": "agent_not_enabled"}, config
+    if unavailable_adapter_count:
+        return status | {
+            "status": "provider_unavailable",
+            "reason_code": "source_provider_adapter_unavailable",
+            "unavailable_adapter_count": unavailable_adapter_count,
+        }, config
+    return status | {"status": "available", "available": True}, config