superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/core/operation_policy_registry.py

@@ -1,542 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""OperationPolicyRegistry — declarative admission / policy layer (V4 Phase 4).
-
-Design contract (NON-NEGOTIABLE):
-1. evaluate() is PURE and CPU-ONLY. No file, network, or DB access. Microseconds.
-2. Default policy is ADDITIVE: every operation kind that succeeds today continues
-   to succeed after this module is imported. The registry adds checks on top of
-   the existing trust hook + RBAC + ingest gate — it does NOT replace them.
-3. Unknown kind: fail-OPEN in local/single-user mode (annotate with audit=True).
-              fail-CLOSED in company/remote mode (deny with reason string).
-4. Payload > max_payload_bytes: ANNOTATED only — never rejected here. The ingest
-   gate already enforces the 1 MiB hard cap; double-rejection is forbidden.
-5. The module-level _DEFAULT_REGISTRY singleton is the safe default for all
-   call sites. It never rejects any REMEMBER that the existing stack accepts.
-
-Part of SuperLocalMemory V4 | Phase 4: Admission/Policy Layer
-"""
-
-from __future__ import annotations
-
-import types
-from dataclasses import dataclass, field
-
-from superlocalmemory.core.actor_context import ActorContext, ActorRole, Transport
-from superlocalmemory.core.operation_policy import (
-    _ADMIN_TRANSPORTS,
-    _ALL_TRANSPORTS,
-    _MESH_TRANSPORTS,
-    OperationPolicy,
-)
-from superlocalmemory.core.operation_request import OperationKind
-
-# ---------------------------------------------------------------------------
-# Mode sentinel sets — used by evaluate() to decide unknown-kind behaviour.
-# ---------------------------------------------------------------------------
-
-_LOCAL_MODES: frozenset[str] = frozenset({
-    "local", "single-user", "single_user", "personal",
-})
-_COMPANY_MODES: frozenset[str] = frozenset({
-    "company", "remote", "multi-user", "multi_user", "enterprise",
-})
-
-# ---------------------------------------------------------------------------
-# PolicyDecision — the return value of evaluate()
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True, slots=True)
-class PolicyDecision:
-    """Result of one OperationPolicyRegistry.evaluate() call.
-
-    ``allowed``     Whether the operation is admitted by policy.
-    ``reason``      Machine-readable reason code (never a user-visible message).
-    ``annotations`` Supplementary key/value pairs for audit, telemetry, and
-                    downstream enrichment. Exposed as a read-only mapping so a
-                    frozen decision cannot be mutated after construction.
-    """
-
-    allowed: bool
-    reason: str
-    annotations: dict = field(default_factory=dict)
-
-    def __post_init__(self) -> None:
-        # Freeze the annotations mapping so the whole decision is immutable
-        # (the outer dataclass is frozen; this closes the nested-dict hole).
-        from types import MappingProxyType
-
-        if not isinstance(self.annotations, MappingProxyType):
-            object.__setattr__(
-                self, "annotations", MappingProxyType(dict(self.annotations))
-            )
-
-
-# ---------------------------------------------------------------------------
-# OperationPolicyRegistry
-# ---------------------------------------------------------------------------
-
-
-class OperationPolicyRegistry:
-    """Declarative, immutable registry mapping OperationKind → OperationPolicy.
-
-    Construction
-    ------------
-    Use ``OperationPolicyRegistry.default()`` to obtain the safe production
-    default. All known OperationKind values are pre-populated with policies
-    that preserve the current single-user allow behaviour.
-
-    Immutability
-    ------------
-    The internal policy table is wrapped in ``types.MappingProxyType`` to
-    prevent external mutation. ``register_deny`` and ``with_policy`` return
-    NEW registry instances (immutable-update pattern).
-
-    evaluate() contract
-    -------------------
-    - Pure: no I/O, no global mutation, no side effects.
-    - Fast: dict lookup + frozenset.isdisjoint() + field comparisons.
-    - Thread-safe: all state is read-only after construction.
-    """
-
-    def __init__(
-        self,
-        policies: dict[OperationKind, OperationPolicy],
-        explicit_denies: frozenset[OperationKind] = frozenset(),
-    ) -> None:
-        # MappingProxyType enforces read-only access after construction.
-        self._policies: types.MappingProxyType[
-            OperationKind, OperationPolicy
-        ] = types.MappingProxyType(dict(policies))
-        self._explicit_denies: frozenset[OperationKind] = frozenset(explicit_denies)
-
-    # ------------------------------------------------------------------
-    # Constructors
-    # ------------------------------------------------------------------
-
-    @classmethod
-    def default(cls) -> OperationPolicyRegistry:
-        """Build the production-default registry.
-
-        Every known OperationKind is assigned a policy whose required_roles
-        includes ActorRole.OWNER and allowed_transports includes
-        Transport.INTERNAL — so the existing in-process Python API path and the
-        single-user HTTP path continue to be admitted without any new rejection.
-
-        Policy table rationale
-        ----------------------
-        REMEMBER / RECALL      Core R/W — open to OWNER, ADMIN, MEMBER.
-        FORGET / CORRECT       Reversible mutations — OWNER and ADMIN only.
-        ERASE                  Irreversible — OWNER only.
-        CONSOLIDATE / ARCHIVE  Maintenance — OWNER and ADMIN.
-        BACKUP / RESTORE_BACKUP Administrative — OWNER only, any transport.
-        MESH_*                 Collaboration — OWNER, ADMIN, MEMBER; mesh transports.
-        PROVIDER_TEST          Internal probing — OWNER and ADMIN; CLI/INTERNAL only.
-        MODE_CHANGE            System config — OWNER only; admin transports only.
-        PROFILE_SWITCH         Profile ops — OWNER and ADMIN; all transports.
-        SCHEMA_MIGRATE         Dangerous DDL — OWNER only; CLI/INTERNAL only.
-        VECTOR_MIGRATE         Index DDL — OWNER and ADMIN; CLI/INTERNAL only.
-        """
-        _owner_only = frozenset({ActorRole.OWNER})
-        _owner_admin = frozenset({ActorRole.OWNER, ActorRole.ADMIN})
-        _owner_admin_member = frozenset({
-            ActorRole.OWNER, ActorRole.ADMIN, ActorRole.MEMBER,
-        })
-        _all_reads = frozenset({
-            ActorRole.OWNER, ActorRole.ADMIN, ActorRole.MEMBER, ActorRole.VIEWER,
-        })
-
-        policies: dict[OperationKind, OperationPolicy] = {
-            OperationKind.REMEMBER: OperationPolicy(
-                kind=OperationKind.REMEMBER,
-                required_roles=_owner_admin_member,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.RECALL: OperationPolicy(
-                kind=OperationKind.RECALL,
-                required_roles=_all_reads,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="none",
-            ),
-            OperationKind.FORGET: OperationPolicy(
-                kind=OperationKind.FORGET,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-            ),
-            OperationKind.ARCHIVE: OperationPolicy(
-                kind=OperationKind.ARCHIVE,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.RESTORE: OperationPolicy(
-                kind=OperationKind.RESTORE,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.CORRECT: OperationPolicy(
-                kind=OperationKind.CORRECT,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-            ),
-            OperationKind.ERASE: OperationPolicy(
-                kind=OperationKind.ERASE,
-                required_roles=_owner_only,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-                redaction_policy="full",
-                resource_ownership_check=True,
-            ),
-            OperationKind.CONSOLIDATE: OperationPolicy(
-                kind=OperationKind.CONSOLIDATE,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.BACKUP: OperationPolicy(
-                kind=OperationKind.BACKUP,
-                required_roles=_owner_only,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.RESTORE_BACKUP: OperationPolicy(
-                kind=OperationKind.RESTORE_BACKUP,
-                required_roles=_owner_only,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-            ),
-            OperationKind.MESH_SEND: OperationPolicy(
-                kind=OperationKind.MESH_SEND,
-                required_roles=_owner_admin_member,
-                required_authentication=True,
-                allowed_transports=_MESH_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.MESH_LOCK: OperationPolicy(
-                kind=OperationKind.MESH_LOCK,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=frozenset({
-                    Transport.MESH, Transport.INTERNAL, Transport.MCP,
-                }),
-                audit_level="full",
-            ),
-            OperationKind.PROVIDER_TEST: OperationPolicy(
-                kind=OperationKind.PROVIDER_TEST,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=frozenset({
-                    Transport.CLI, Transport.INTERNAL, Transport.DASHBOARD,
-                }),
-                audit_level="standard",
-            ),
-            OperationKind.MODE_CHANGE: OperationPolicy(
-                kind=OperationKind.MODE_CHANGE,
-                required_roles=_owner_only,
-                required_authentication=True,
-                allowed_transports=_ADMIN_TRANSPORTS | frozenset({Transport.MCP}),
-                audit_level="full",
-            ),
-            OperationKind.PROFILE_SWITCH: OperationPolicy(
-                kind=OperationKind.PROFILE_SWITCH,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            OperationKind.SCHEMA_MIGRATE: OperationPolicy(
-                kind=OperationKind.SCHEMA_MIGRATE,
-                required_roles=_owner_only,
-                required_authentication=True,
-                allowed_transports=frozenset({Transport.CLI, Transport.INTERNAL}),
-                audit_level="full",
-            ),
-            OperationKind.VECTOR_MIGRATE: OperationPolicy(
-                kind=OperationKind.VECTOR_MIGRATE,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=frozenset({Transport.CLI, Transport.INTERNAL}),
-                audit_level="full",
-            ),
-            OperationKind.EVOLVE_SKILL: OperationPolicy(
-                kind=OperationKind.EVOLVE_SKILL,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-            ),
-            # Operational recovery & admin remediation (resilience slice)
-            # OPS_INSPECT: read-only listing of failed/stuck/degraded ops.
-            # Allowed over all transports so dashboard, MCP, and CLI all work.
-            OperationKind.OPS_INSPECT: OperationPolicy(
-                kind=OperationKind.OPS_INSPECT,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="standard",
-            ),
-            # OPS_RESOLVE: retry/force-reconcile/cancel a failed operation.
-            # Write permission — OWNER/ADMIN only, full audit trail.
-            OperationKind.OPS_RESOLVE: OperationPolicy(
-                kind=OperationKind.OPS_RESOLVE,
-                required_roles=_owner_admin,
-                required_authentication=True,
-                allowed_transports=_ALL_TRANSPORTS,
-                audit_level="full",
-            ),
-        }
-        return cls(policies)
-
-    # ------------------------------------------------------------------
-    # Immutable-update helpers
-    # ------------------------------------------------------------------
-
-    def with_policy(self, policy: OperationPolicy) -> OperationPolicyRegistry:
-        """Return a new registry with one policy replaced or added."""
-        updated = dict(self._policies)
-        updated[policy.kind] = policy
-        return OperationPolicyRegistry(updated, self._explicit_denies)
-
-    def register_deny(self, kind: OperationKind) -> OperationPolicyRegistry:
-        """Return a new registry that explicitly denies ``kind`` regardless of actor."""
-        return OperationPolicyRegistry(
-            dict(self._policies),
-            self._explicit_denies | {kind},
-        )
-
-    # ------------------------------------------------------------------
-    # Queries
-    # ------------------------------------------------------------------
-
-    def coverage(self) -> dict[str, dict]:
-        """Return a coverage summary for every known OperationKind.
-
-        Returns a mapping of {kind_value: {"has_policy": bool}} for every
-        value in OperationKind. Used by the startup self-check and unit tests.
-
-        Example::
-
-            cov = _DEFAULT_REGISTRY.coverage()
-            assert cov["remember"]["has_policy"] is True
-        """
-        result: dict[str, dict] = {}
-        for kind in OperationKind:
-            has_policy = kind in self._policies
-            entry: dict = {"has_policy": has_policy, "kind": kind.value}
-            if has_policy:
-                policy = self._policies[kind]
-                entry["has_transports"] = len(policy.allowed_transports) > 0
-            else:
-                entry["has_transports"] = False
-            result[kind.value] = entry
-        return result
-
-    def get_policy(
-        self,
-        kind: OperationKind,
-        transport: Transport | None = None,  # reserved for future per-transport overrides
-    ) -> OperationPolicy | None:
-        """Return the policy for ``kind``, or None if no policy is registered.
-
-        The ``transport`` argument is reserved for future per-transport policy
-        overrides. In V4 the table is keyed only by kind; the argument is
-        accepted but not used for lookup.
-        """
-        return self._policies.get(kind)
-
-    # ------------------------------------------------------------------
-    # Core: pure, CPU-only evaluation
-    # ------------------------------------------------------------------
-
-    def evaluate(
-        self,
-        kind: OperationKind | str,
-        actor: ActorContext,
-        mode: str = "local",
-        *,
-        payload_bytes: int = 0,
-    ) -> PolicyDecision:
-        """Evaluate whether ``actor`` may perform ``kind`` under ``mode``.
-
-        This method is PURE. No I/O of any kind. Microseconds.
-
-        Parameters
-        ----------
-        kind            The operation being requested.  May be an OperationKind
-                        enum value or a raw string (unknown strings are treated
-                        as unknown kinds).
-        actor           Server-derived actor identity. NEVER from request body.
-        mode            Deployment mode: "local" / "single-user" → fail-open for
-                        unknown kinds. "company" / "remote" → fail-closed.
-                        Defaults to "local" (safe for internal path).
-        payload_bytes   Optional advisory payload size. If > policy.max_payload_bytes,
-                        the decision is annotated but NOT denied (double-rejection
-                        is forbidden — the ingest gate already enforces the cap).
-
-        Returns
-        -------
-        PolicyDecision  ``allowed=True`` → proceed; ``allowed=False`` → deny.
-                        Never raises; all errors produce ``allowed=False``.
-        """
-        annotations: dict = {}
-
-        # ----------------------------------------------------------------
-        # Step 1: Resolve kind string → OperationKind enum.
-        # ----------------------------------------------------------------
-        if not isinstance(kind, OperationKind):
-            try:
-                kind = OperationKind(str(kind))
-            except ValueError:
-                return self._unknown_kind_decision(str(kind), mode)
-
-        # ----------------------------------------------------------------
-        # Step 2: Check explicit deny list (highest priority).
-        # ----------------------------------------------------------------
-        if kind in self._explicit_denies:
-            return PolicyDecision(
-                allowed=False,
-                reason="explicit_deny",
-                annotations={"kind": kind.value},
-            )
-
-        # ----------------------------------------------------------------
-        # Step 3: Look up policy for this kind.
-        # ----------------------------------------------------------------
-        policy = self._policies.get(kind)
-        if policy is None:
-            # Known enum value but no policy registered — treat as unknown.
-            return self._unknown_kind_decision(kind.value, mode)
-
-        # ----------------------------------------------------------------
-        # Step 4: Role check — actor must hold at least one required role.
-        # An empty required_roles set means "deny all" (explicit deny policy).
-        # ----------------------------------------------------------------
-        if not policy.required_roles:
-            return PolicyDecision(
-                allowed=False,
-                reason="policy_denies_all_roles",
-                annotations={"kind": kind.value},
-            )
-
-        # ----------------------------------------------------------------
-        # Step 5: Authentication before authorization — an unauthenticated
-        # actor is rejected for authentication, not role, so the reason is
-        # actionable.
-        # ----------------------------------------------------------------
-        if policy.required_authentication and not actor.is_authenticated:
-            return PolicyDecision(
-                allowed=False,
-                reason="authentication_required",
-                annotations={"kind": kind.value, "principal_id": actor.principal_id},
-            )
-
-        # ----------------------------------------------------------------
-        # Step 6: Role check — actor must hold at least one required role.
-        # ----------------------------------------------------------------
-        if actor.roles.isdisjoint(policy.required_roles):
-            return PolicyDecision(
-                allowed=False,
-                reason="insufficient_roles",
-                annotations={
-                    "kind": kind.value,
-                    "actor_roles": sorted(r.value for r in actor.roles),
-                    "required_roles": sorted(r.value for r in policy.required_roles),
-                },
-            )
-
-        # ----------------------------------------------------------------
-        # Step 7: Transport check.
-        # ----------------------------------------------------------------
-        if actor.transport not in policy.allowed_transports:
-            return PolicyDecision(
-                allowed=False,
-                reason="transport_not_allowed",
-                annotations={
-                    "kind": kind.value,
-                    "actor_transport": actor.transport.value,
-                    "allowed_transports": sorted(
-                        t.value for t in policy.allowed_transports
-                    ),
-                },
-            )
-
-        # ----------------------------------------------------------------
-        # Step 7: Payload size — annotate only, never reject.
-        # The ingest gate already enforces the 1 MiB hard cap. Annotating
-        # here gives the audit log a signal without double-rejecting.
-        # ----------------------------------------------------------------
-        if payload_bytes > 0 and payload_bytes > policy.max_payload_bytes:
-            annotations["payload_oversized"] = True
-            annotations["payload_bytes"] = payload_bytes
-            annotations["max_payload_bytes"] = policy.max_payload_bytes
-
-        # ----------------------------------------------------------------
-        # Step 8: Admit.
-        # ----------------------------------------------------------------
-        return PolicyDecision(
-            allowed=True,
-            reason="allow",
-            annotations=annotations,
-        )
-
-    # ------------------------------------------------------------------
-    # Private helpers
-    # ------------------------------------------------------------------
-
-    def _unknown_kind_decision(self, kind_raw: str, mode: str) -> PolicyDecision:
-        """Fail-open in local mode, fail-closed in company/remote mode."""
-        if mode in _LOCAL_MODES:
-            return PolicyDecision(
-                allowed=True,
-                reason="unknown_kind_allow_local",
-                annotations={"audit": True, "kind_raw": kind_raw},
-            )
-        # Company / remote mode: fail closed. An unknown kind may be a
-        # future privileged operation or a typo from an untrusted caller.
-        return PolicyDecision(
-            allowed=False,
-            reason="unknown_kind_deny_company",
-            annotations={"kind_raw": kind_raw},
-        )
-
-    def __repr__(self) -> str:
-        return (
-            f"OperationPolicyRegistry("
-            f"kinds={sorted(k.value for k in self._policies)}, "
-            f"explicit_denies={sorted(k.value for k in self._explicit_denies)})"
-        )
-
-
-# ---------------------------------------------------------------------------
-# Module-level singleton — safe default for all wire-up call sites.
-#
-# CRIT: This singleton is constructed ONCE at import time. It is read-only
-# (MappingProxyType internal storage). Thread-safe by construction.
-# The default evaluate() for REMEMBER + OWNER + local ALWAYS returns
-# allowed=True — zero new rejections on the existing happy path.
-# ---------------------------------------------------------------------------
-
-_DEFAULT_REGISTRY: OperationPolicyRegistry = OperationPolicyRegistry.default()
-
-
-__all__ = [
-    "OperationPolicyRegistry",
-    "PolicyDecision",
-    "_DEFAULT_REGISTRY",
-]

package/src/superlocalmemory/core/operation_request.py

@@ -1,127 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Admission envelope (OperationRequest) and status types for V4.
-
-OperationRequest is the typed, immutable boundary between every caller and the
-policy/ingestion layer. The registry uses only the fields it can evaluate
-purely in memory (kind, actor, scope, payload_hash) — no I/O.
-
-Part of SuperLocalMemory V4 | Phase 4: Admission/Policy Layer
-"""
-
-from __future__ import annotations
-
-import uuid
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from enum import Enum
-from typing import TYPE_CHECKING
-
-from superlocalmemory.core.actor_context import ActorContext, ActorRole, Transport
-
-if TYPE_CHECKING:
-    pass  # reserved for future typing imports
-
-
-class OperationKind(str, Enum):
-    """Canonical names for every mutation kind the system accepts.
-
-    The registry stores one OperationPolicy per OperationKind. An operation
-    whose kind is absent from the registry is treated as "unknown" and
-    evaluated by the mode-specific fallback rule (fail-open local /
-    fail-closed company).
-    """
-
-    REMEMBER = "remember"
-    RECALL = "recall"
-    FORGET = "forget"
-    ARCHIVE = "archive"
-    RESTORE = "restore"
-    CORRECT = "correct"
-    ERASE = "erase"
-    CONSOLIDATE = "consolidate"
-    BACKUP = "backup"
-    RESTORE_BACKUP = "restore_backup"
-    MESH_SEND = "mesh_send"
-    MESH_LOCK = "mesh_lock"
-    PROVIDER_TEST = "provider_test"
-    MODE_CHANGE = "mode_change"
-    PROFILE_SWITCH = "profile_switch"
-    SCHEMA_MIGRATE = "schema_migrate"
-    VECTOR_MIGRATE = "vector_migrate"
-    EVOLVE_SKILL = "evolve_skill"
-    # Operational recovery & admin remediation (V4 resilience slice)
-    OPS_INSPECT = "ops_inspect"    # List failed/stuck/degraded operations (OWNER/ADMIN)
-    OPS_RESOLVE = "ops_resolve"    # Retry/force-reconcile/cancel an operation (OWNER/ADMIN)
-
-
-class OperationStatus(str, Enum):
-    """Lifecycle states for a durable operation."""
-
-    ACCEPTED = "accepted"       # Journaled, not yet committed
-    COMMITTED = "committed"     # Written to canonical store
-    PROJECTING = "projecting"   # Running external projections
-    COMPLETE = "complete"       # All obligations met
-    DEGRADED = "degraded"       # Some projections failed, retryable
-    FAILED = "failed"           # Non-retryable failure
-    ROLLED_BACK = "rolled_back" # Compensation complete
-
-
-def _default_actor() -> ActorContext:
-    """Zero-value ActorContext for the internal Python-API path.
-
-    Used as the default in OperationRequest when a caller does not supply an
-    explicit actor. The principal_id "local-operator" signals an in-process
-    call but is NOT authenticated (no session token). Callers that need a
-    fully-authenticated context must supply one explicitly.
-    """
-    return ActorContext(
-        principal_id="local-operator",
-        roles=frozenset({ActorRole.OWNER}),
-        transport=Transport.INTERNAL,
-        client_host="",
-    )
-
-
-@dataclass(frozen=True, slots=True)
-class OperationRequest:
-    """Immutable admission envelope for every mutation entering the system.
-
-    Construction rules (NON-NEGOTIABLE)
-    ------------------------------------
-    1. ``actor`` is ALWAYS server-derived — session store, RBAC, daemon
-       descriptor. NEVER populated from the HTTP/MCP request body.
-    2. ``operation_id`` is auto-generated when omitted (UUID hex).
-    3. ``idempotency_key`` falls back to ``operation_id`` in __post_init__.
-    4. ``payload_hash`` is the SHA-256 of the raw content before any scrubbing;
-       callers may leave it empty for lightweight envelopes.
-    """
-
-    operation_id: str = field(default_factory=lambda: uuid.uuid4().hex)
-    idempotency_key: str = ""
-    kind: OperationKind = OperationKind.REMEMBER
-    actor: ActorContext = field(default_factory=_default_actor)
-    profile_id: str = ""
-    profile_generation: int = 0
-    resource_ids: tuple[str, ...] = ()
-    scope: str = "personal"
-    deadline_ms: int = 30_000
-    schema_capability: str = ""
-    payload_hash: str = ""
-    trace_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
-    created_at: str = field(
-        default_factory=lambda: datetime.now(timezone.utc).isoformat()
-    )
-
-    def __post_init__(self) -> None:
-        # Guarantee: idempotency_key is never empty after construction.
-        if not self.idempotency_key:
-            object.__setattr__(self, "idempotency_key", self.operation_id)
-
-
-__all__ = [
-    "OperationKind",
-    "OperationRequest",
-    "OperationStatus",
-]