loopx 0.4.8__py3-none-any.whl

loopx/capabilities/decision_context/providers.py

@@ -0,0 +1,228 @@
+"""Replaceable current-authority providers for Decision Context."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Callable, Mapping
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .sources import (
+    DecisionSourceExactRead,
+    DecisionSourceItem,
+    DecisionSourceProvider,
+    DecisionSourceScan,
+    DecisionSourceSpec,
+)
+
+LOCAL_FILE_SOURCE_ADAPTER = "local-file"
+LOCAL_FILE_SOURCE_PROVIDER_VERSION = "builtin-v0"
+DEFAULT_LOCAL_FILE_MAX_BYTES = 1_048_576
+MAX_LOCAL_FILE_MAX_BYTES = 4_194_304
+
+DecisionSourceProviderBuilder = Callable[
+    [str, Mapping[str, Any]], DecisionSourceProvider
+]
+_SOURCE_PROVIDER_BUILDERS: dict[str, DecisionSourceProviderBuilder] = {}
+
+
+def register_decision_source_provider(
+    adapter: str,
+    builder: DecisionSourceProviderBuilder,
+) -> None:
+    normalized = str(adapter or "").strip()
+    if not normalized:
+        raise ValueError("decision source adapter id is required")
+    if normalized in _SOURCE_PROVIDER_BUILDERS:
+        raise ValueError(f"decision source adapter already registered: {normalized}")
+    _SOURCE_PROVIDER_BUILDERS[normalized] = builder
+
+
+def decision_source_provider_registered(adapter: str) -> bool:
+    return str(adapter or "").strip() in _SOURCE_PROVIDER_BUILDERS
+
+
+def build_decision_source_provider(
+    binding: Mapping[str, Any],
+) -> DecisionSourceProvider:
+    """Resolve one private provider binding without capability-specific branching."""
+
+    provider_id = str(binding.get("provider_id") or "").strip()
+    adapter = str(binding.get("adapter") or "").strip()
+    config = binding.get("config")
+    if not provider_id:
+        raise ValueError("decision source provider_id is required")
+    if not isinstance(config, Mapping):
+        raise ValueError("decision source provider config must be an object")
+    builder = _SOURCE_PROVIDER_BUILDERS.get(adapter)
+    if builder is None:
+        raise ValueError(
+            f"unsupported decision source adapter: {adapter or '<missing>'}"
+        )
+    provider = builder(provider_id, config)
+    if str(getattr(provider, "provider_id", "") or "") != provider_id:
+        raise ValueError("decision source provider identity does not match its binding")
+    return provider
+
+
+def _parse_timestamp(value: str, *, field_name: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(str(value).strip())
+    except ValueError as exc:
+        raise ValueError(f"{field_name} must be an ISO-8601 timestamp") from exc
+    if parsed.tzinfo is None:
+        raise ValueError(f"{field_name} must include a timezone")
+    return parsed
+
+
+def _max_bytes(config: Mapping[str, Any]) -> int:
+    value = config.get("max_bytes", DEFAULT_LOCAL_FILE_MAX_BYTES)
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int)
+        or not 1 <= value <= MAX_LOCAL_FILE_MAX_BYTES
+    ):
+        raise ValueError(
+            f"local-file max_bytes must be between 1 and {MAX_LOCAL_FILE_MAX_BYTES}"
+        )
+    unexpected = sorted(set(config) - {"max_bytes"})
+    if unexpected:
+        raise ValueError(
+            "local-file provider config contains unsupported fields: "
+            + ", ".join(unexpected)
+        )
+    return int(value)
+
+
+class LocalFileDecisionSourceProvider:
+    """Read one explicitly configured local authority file without public capture."""
+
+    def __init__(self, *, provider_id: str, max_bytes: int) -> None:
+        self.provider_id = provider_id
+        self.max_bytes = max_bytes
+
+    def _read(
+        self,
+        source: DecisionSourceSpec,
+    ) -> tuple[Path, bytes, str, str]:
+        if source.provider_id != self.provider_id:
+            raise ValueError("source provider identity does not match")
+        path = Path(source.private_locator).expanduser()
+        if not path.is_file():
+            raise FileNotFoundError("configured authority file is unavailable")
+        stat = path.stat()
+        if stat.st_size > self.max_bytes:
+            raise ValueError("configured authority file exceeds max_bytes")
+        content = path.read_bytes()
+        revision = hashlib.sha256(content).hexdigest()
+        observed_at = datetime.fromtimestamp(
+            stat.st_mtime,
+            tz=timezone.utc,
+        ).isoformat()
+        return path.resolve(), content, revision, observed_at
+
+    def scan(
+        self,
+        *,
+        source: DecisionSourceSpec,
+        after_cursor: str | None,
+        before: str,
+        limit: int,
+        timeout_seconds: float,
+        observed_at: str,
+    ) -> DecisionSourceScan:
+        del observed_at
+        started = time.monotonic()
+        if limit < 1:
+            raise ValueError("limit must be positive")
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        path, _content, revision, item_observed_at = self._read(source)
+        cursor = f"sha256:{revision}"
+        if _parse_timestamp(
+            item_observed_at,
+            field_name="source observed_at",
+        ) > _parse_timestamp(before, field_name="before"):
+            return DecisionSourceScan(
+                provider_id=self.provider_id,
+                source_id=source.source_id,
+                status="no_change",
+                observed_at=before,
+                requested_limit=min(limit, source.max_changes),
+                cursor_before=after_cursor,
+                cursor_after=after_cursor,
+                provider_version=LOCAL_FILE_SOURCE_PROVIDER_VERSION,
+                latency_ms=int((time.monotonic() - started) * 1000),
+            )
+        if after_cursor == cursor:
+            return DecisionSourceScan(
+                provider_id=self.provider_id,
+                source_id=source.source_id,
+                status="no_change",
+                observed_at=item_observed_at,
+                requested_limit=min(limit, source.max_changes),
+                cursor_before=after_cursor,
+                cursor_after=cursor,
+                provider_version=LOCAL_FILE_SOURCE_PROVIDER_VERSION,
+                latency_ms=int((time.monotonic() - started) * 1000),
+            )
+        return DecisionSourceScan(
+            provider_id=self.provider_id,
+            source_id=source.source_id,
+            status="completed",
+            observed_at=item_observed_at,
+            requested_limit=min(limit, source.max_changes),
+            cursor_before=after_cursor,
+            cursor_after=cursor,
+            items=(
+                DecisionSourceItem(
+                    resource_ref=str(path),
+                    revision=revision,
+                    observed_at=item_observed_at,
+                ),
+            ),
+            provider_version=LOCAL_FILE_SOURCE_PROVIDER_VERSION,
+            latency_ms=int((time.monotonic() - started) * 1000),
+        )
+
+    def exact_read(
+        self,
+        *,
+        source: DecisionSourceSpec,
+        item: DecisionSourceItem,
+        timeout_seconds: float,
+        observed_at: str,
+    ) -> DecisionSourceExactRead:
+        del observed_at
+        if timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        path, content, revision, item_observed_at = self._read(source)
+        if str(path) != item.resource_ref or revision != item.revision:
+            raise ValueError("authority file changed after the bounded scan")
+        text = content.decode("utf-8")
+        if not text.strip():
+            raise ValueError("configured authority file is empty")
+        return DecisionSourceExactRead(
+            resource_ref=item.resource_ref,
+            revision=item.revision,
+            observed_at=item_observed_at,
+            content=text,
+        )
+
+
+def _build_local_file_provider(
+    provider_id: str,
+    config: Mapping[str, Any],
+) -> DecisionSourceProvider:
+    return LocalFileDecisionSourceProvider(
+        provider_id=provider_id,
+        max_bytes=_max_bytes(config),
+    )
+
+
+register_decision_source_provider(
+    LOCAL_FILE_SOURCE_ADAPTER,
+    _build_local_file_provider,
+)

loopx/capabilities/decision_context/review_settlement.py

@@ -0,0 +1,136 @@
+"""Owner-gated or quiet settlement for one Decision Context assembly."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from ...rollout_event_log import append_rollout_event, build_rollout_event
+from .assembler import DecisionContextAssembly
+from .cursor_commit import (
+    commit_profile_decision_cursors,
+    resolve_decision_review_source_event,
+)
+from .packets import build_decision_review_receipt
+
+
+DECISION_REVIEW_SETTLEMENT_SCHEMA_VERSION = "decision_review_settlement_v0"
+
+
+def settle_profile_decision_review(
+    *,
+    goal_id: str,
+    agent_id: str,
+    profile_path: Path,
+    cursor_path: Path,
+    assembly: DecisionContextAssembly,
+    lifecycle_event_log_path: Path,
+    actor_ref: str,
+    reason_code: str,
+    summary: str,
+    proposal: Mapping[str, Any] | None = None,
+    source_event_id: str | None = None,
+    execute: bool = False,
+) -> dict[str, Any]:
+    """Settle a reviewed proposal or an explicit semantic no-change result."""
+
+    packet = assembly.public_packet()
+    evidence = packet.get("evidence_packet")
+    if not isinstance(evidence, Mapping):
+        raise ValueError("decision-context assembly has no evidence packet")
+    evidence_ref = str(evidence.get("packet_ref") or "")
+    decision_id = str(packet.get("decision_id") or "")
+
+    gate_event: Mapping[str, Any] | None = None
+    proposal_ref: str | None = None
+    gate_todo_id: str | None = None
+    if source_event_id is not None:
+        if proposal is None:
+            raise ValueError("gated decision review requires a proposal")
+        proposal_ref = str(proposal.get("packet_ref") or "")
+        gate_event, disposition = resolve_decision_review_source_event(
+            event_log_path=lifecycle_event_log_path,
+            source_event_id=source_event_id,
+            proposal_packet_ref=proposal_ref,
+        )
+        gate_todo_id = str(gate_event.get("todo_id") or "")
+        recorded_at = str(gate_event.get("recorded_at") or "")
+    else:
+        if proposal is not None:
+            raise ValueError("proposal settlement requires a user-gate event")
+        disposition = "no_change"
+        recorded_at = str(packet.get("observed_at") or "")
+
+    review_receipt = build_decision_review_receipt(
+        goal_id=goal_id,
+        decision_id=decision_id,
+        evidence_packet_ref=evidence_ref,
+        recorded_at=recorded_at,
+        disposition=disposition,
+        actor_ref=actor_ref,
+        reason_code=reason_code,
+        summary=summary,
+        proposal_packet_ref=proposal_ref,
+        gate_todo_id=gate_todo_id,
+        source_event_id=source_event_id,
+    )
+    artifact_refs = [evidence_ref, str(review_receipt["packet_ref"])]
+    if proposal_ref is not None:
+        artifact_refs.append(proposal_ref)
+    lifecycle_event = build_rollout_event(
+        goal_id=goal_id,
+        event_kind="validation",
+        agent_id=agent_id,
+        todo_id=gate_todo_id,
+        decision_id=decision_id,
+        caused_by=source_event_id,
+        status="committed",
+        summary="Decision review settlement validated.",
+        artifact_refs=artifact_refs,
+        details={
+            "capability": "decision_context",
+            "disposition": disposition,
+            "quiet_noop": disposition == "no_change",
+        },
+        recorded_at=recorded_at,
+    )
+
+    result: dict[str, Any] = {
+        "ok": True,
+        "schema_version": DECISION_REVIEW_SETTLEMENT_SCHEMA_VERSION,
+        "goal_id": goal_id,
+        "decision_id": decision_id,
+        "disposition": disposition,
+        "review_receipt": review_receipt,
+        "lifecycle_event": {
+            "schema_version": lifecycle_event["schema_version"],
+            "event_id": lifecycle_event["event_id"],
+            "event_kind": lifecycle_event["event_kind"],
+            "status": lifecycle_event["status"],
+            "recorded_at": lifecycle_event["recorded_at"],
+        },
+        "executed": execute,
+        "quiet_noop": disposition == "no_change",
+        "external_writes_performed": False,
+        "raw_context_captured": False,
+        "private_paths_captured": False,
+    }
+    if not execute:
+        result["cursor_commit"] = None
+        return result
+
+    appended = append_rollout_event(lifecycle_event_log_path, lifecycle_event)
+    result["lifecycle_event"]["event_id"] = appended["event_id"]
+    result["cursor_commit"] = commit_profile_decision_cursors(
+        goal_id=goal_id,
+        agent_id=agent_id,
+        profile_path=profile_path,
+        cursor_path=cursor_path,
+        assembly=assembly,
+        proposal=proposal,
+        review_receipt=review_receipt,
+        lifecycle_event_log_path=lifecycle_event_log_path,
+        lifecycle_event_id=str(appended["event_id"]),
+    )
+    return result

loopx/capabilities/decision_context/runtime.py

@@ -0,0 +1,273 @@
+"""Thin profile-to-evidence orchestration for Decision Context."""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping, Sequence
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from ..context_providers import build_context_provider
+from ..context_providers.base import ContextProvider
+from .assembler import (
+    DecisionContextAssembly,
+    DecisionEvidenceRebaser,
+    DecisionEvidenceRecords,
+    assemble_decision_evidence,
+)
+from .private_state import load_private_decision_cursors, private_file_digest
+from .profile import (
+    DecisionContextProfile,
+    resolve_decision_context_activation,
+)
+from .providers import build_decision_source_provider
+from .sources import DecisionSourceProvider, DecisionSourceScan, DecisionSourceSpec
+
+
+_DECISION_EVIDENCE_RECORD_FIELDS = {
+    "changed_facts",
+    "recalled_claims",
+    "stale_or_rejected_claims",
+    "conflicts",
+    "semantic_no_change",
+}
+
+
+def decision_evidence_records_from_mapping(
+    value: Mapping[str, Any],
+) -> DecisionEvidenceRecords:
+    """Load a strict domain rebase result without trusting private raw content."""
+
+    if not isinstance(value, Mapping):
+        raise TypeError("decision evidence records must be an object")
+    unexpected = sorted(set(value) - _DECISION_EVIDENCE_RECORD_FIELDS)
+    if unexpected:
+        raise ValueError(
+            "decision evidence records contain unsupported fields: "
+            + ", ".join(unexpected)
+        )
+
+    def records(field: str) -> tuple[Mapping[str, Any], ...]:
+        raw = value.get(field, [])
+        if isinstance(raw, (str, bytes)) or not isinstance(raw, list):
+            raise TypeError(f"{field} must be a list of objects")
+        if any(not isinstance(item, Mapping) for item in raw):
+            raise TypeError(f"{field} must be a list of objects")
+        return tuple(dict(item) for item in raw)
+
+    semantic_no_change = value.get("semantic_no_change", False)
+    if not isinstance(semantic_no_change, bool):
+        raise TypeError("semantic_no_change must be a boolean")
+    return DecisionEvidenceRecords(
+        changed_facts=records("changed_facts"),
+        recalled_claims=records("recalled_claims"),
+        stale_or_rejected_claims=records("stale_or_rejected_claims"),
+        conflicts=records("conflicts"),
+        semantic_no_change=semantic_no_change,
+    )
+
+
+class _UnavailableContextProvider:
+    """Preserve a public fail-open receipt when provider construction fails."""
+
+    provider_id = "context-provider"
+
+    def retrieve(self, **_: Any) -> Any:
+        raise RuntimeError("context provider is unavailable")
+
+    def sync(self, **_: Any) -> Any:
+        raise RuntimeError("context provider is unavailable")
+
+
+class _UnavailableDecisionSourceProvider:
+    """Report a configured-but-invalid binding without exposing its config."""
+
+    def __init__(
+        self,
+        provider_id: str,
+        *,
+        reason_code: str = "provider_configuration_failed",
+    ) -> None:
+        self.provider_id = provider_id
+        self.reason_code = reason_code
+
+    def scan(
+        self,
+        *,
+        source: DecisionSourceSpec,
+        after_cursor: str | None,
+        before: str,
+        limit: int,
+        timeout_seconds: float,
+        observed_at: str,
+    ) -> DecisionSourceScan:
+        del after_cursor, before, limit, timeout_seconds
+        return DecisionSourceScan(
+            provider_id=self.provider_id,
+            source_id=source.source_id,
+            status="unavailable",
+            observed_at=observed_at,
+            requested_limit=source.max_changes,
+            reason_code=self.reason_code,
+        )
+
+    def exact_read(self, **_: Any) -> Any:
+        raise RuntimeError("decision source provider is unavailable")
+
+
+def _build_source_providers(
+    profile: DecisionContextProfile,
+    *,
+    sources: Sequence[DecisionSourceSpec],
+    source_provider_overrides: Mapping[str, DecisionSourceProvider],
+) -> dict[str, DecisionSourceProvider]:
+    enabled_provider_ids = {source.provider_id for source in sources}
+    providers: dict[str, DecisionSourceProvider] = {}
+    for provider_id, binding in profile.provider_binding_map().items():
+        if provider_id not in enabled_provider_ids:
+            continue
+        runtime_provider = source_provider_overrides.get(provider_id)
+        if runtime_provider is not None:
+            if str(getattr(runtime_provider, "provider_id", "") or "") != provider_id:
+                providers[provider_id] = _UnavailableDecisionSourceProvider(
+                    provider_id,
+                    reason_code="runtime_provider_identity_mismatch",
+                )
+            else:
+                providers[provider_id] = runtime_provider
+            continue
+        try:
+            providers[provider_id] = build_decision_source_provider(binding)
+        except Exception:
+            providers[provider_id] = _UnavailableDecisionSourceProvider(provider_id)
+    return providers
+
+
+def _selected_sources(
+    profile: DecisionContextProfile,
+    *,
+    source_ids: Collection[str] | None,
+) -> tuple[DecisionSourceSpec, ...]:
+    enabled = {source.source_id: source for source in profile.sources if source.enabled}
+    if source_ids is None:
+        return tuple(
+            source
+            for source in profile.sources
+            if source.enabled and source.scan_mode != "on_demand"
+        )
+    if isinstance(source_ids, (str, bytes)):
+        raise TypeError("source_ids must be a collection of source ids")
+    selected_ids = {str(source_id).strip() for source_id in source_ids}
+    unavailable = sorted(
+        source_id for source_id in selected_ids if source_id not in enabled
+    )
+    if unavailable:
+        raise ValueError(
+            "requested decision sources are unknown or disabled: "
+            + ", ".join(unavailable)
+        )
+    return tuple(enabled[source_id] for source_id in sorted(selected_ids))
+
+
+def _build_advisory_context_provider(
+    profile: DecisionContextProfile,
+) -> ContextProvider | None:
+    if profile.context_provider is None:
+        return None
+    private_config = profile.context_provider.get("config", {})
+    binding = {
+        "provider": profile.context_provider["provider"],
+        **(dict(private_config) if isinstance(private_config, Mapping) else {}),
+    }
+    try:
+        return build_context_provider(binding)
+    except Exception:
+        return _UnavailableContextProvider()
+
+
+def assemble_profile_decision_evidence(
+    *,
+    goal_id: str,
+    agent_id: str,
+    profile_path: Path | None,
+    decision_id: str,
+    observed_at: str,
+    before: str,
+    rebase: DecisionEvidenceRebaser,
+    cursor_path: Path | None = None,
+    source_ids: Collection[str] | None = None,
+    recall_query: str = "current decision evidence",
+    recall_query_summary: str = "current decision evidence",
+    timeout_seconds: float | None = None,
+    source_provider_overrides: Mapping[str, DecisionSourceProvider] | None = None,
+) -> tuple[dict[str, Any], DecisionContextAssembly | None]:
+    """Resolve one enabled profile and assemble evidence without applying cursors.
+
+    The caller owns domain reasoning through ``rebase``. Raw exact reads and
+    advisory recall stay in-process, while the returned public packet contains
+    only opaque refs and compact evidence. ``proposed_cursors`` remain private;
+    a caller may keep them in the dedicated pending-settlement store, but must
+    not apply them to active cursor state before validated lifecycle writeback.
+    """
+
+    try:
+        profile_digest_before = (
+            private_file_digest(profile_path) if profile_path is not None else None
+        )
+    except ValueError:
+        profile_digest_before = None
+    if source_provider_overrides is None:
+        provider_overrides: Mapping[str, DecisionSourceProvider] = {}
+    elif not isinstance(source_provider_overrides, Mapping):
+        raise TypeError("source_provider_overrides must be a mapping")
+    else:
+        provider_overrides = source_provider_overrides
+    activation, profile = resolve_decision_context_activation(
+        goal_id=goal_id,
+        agent_id=agent_id,
+        profile_path=profile_path,
+        available_source_provider_ids=provider_overrides,
+    )
+    if activation["available"] is not True or profile is None:
+        return activation, None
+
+    context_config = profile.context_provider or {}
+    configured_timeout = context_config.get("timeout_seconds", 10.0)
+    effective_timeout = (
+        float(timeout_seconds)
+        if timeout_seconds is not None
+        else float(configured_timeout)
+    )
+    cursors = load_private_decision_cursors(cursor_path, profile=profile)
+    sources = _selected_sources(profile, source_ids=source_ids)
+    assembly = assemble_decision_evidence(
+        goal_id=goal_id,
+        decision_id=decision_id,
+        observed_at=observed_at,
+        before=before,
+        sources=sources,
+        source_providers=_build_source_providers(
+            profile,
+            sources=sources,
+            source_provider_overrides=provider_overrides,
+        ),
+        cursors=cursors,
+        rebase=rebase,
+        context_provider=_build_advisory_context_provider(profile),
+        context_namespace=str(context_config.get("namespace") or "decision-context"),
+        context_scope_ref=str(context_config.get("scope_ref") or "goal"),
+        recall_query=recall_query,
+        recall_query_summary=recall_query_summary,
+        recall_limit=int(context_config.get("max_results", 5)),
+        timeout_seconds=effective_timeout,
+    )
+    if profile_path is None or profile_digest_before is None:
+        raise ValueError("decision-context profile became unavailable")
+    profile_digest_after = private_file_digest(profile_path)
+    if profile_digest_before != profile_digest_after:
+        raise ValueError("decision-context profile changed during evidence assembly")
+    return activation, replace(
+        assembly,
+        profile_digest=profile_digest_after,
+        runtime_bound_provider_ids=tuple(sorted(provider_overrides)),
+    )