superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/compliance/scheduler.py

@@ -1,217 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Background scheduler that periodically enforces retention rules.
-
-Runs on a configurable interval (default: 1 hour) using daemon threads
-so the scheduler does not prevent process exit.
-"""
-
-from __future__ import annotations
-
-import logging
-import sqlite3
-import threading
-from pathlib import Path
-from typing import Any, Optional
-
-from .retention import RetentionEngine
-
-logger = logging.getLogger(__name__)
-
-# Default: run every hour
-DEFAULT_INTERVAL_SECONDS = 3600
-
-
-class RetentionScheduler:
-    """Background scheduler that periodically enforces retention rules.
-
-    Uses daemon threading — does not prevent process exit. The scheduler
-    runs RetentionEngine.enforce() on all profiles at each interval.
-    """
-
-    def __init__(
-        self,
-        retention_engine: RetentionEngine | None = None,
-        interval_seconds: int = DEFAULT_INTERVAL_SECONDS,
-        *,
-        db_path: str | Path | None = None,
-    ) -> None:
-        if retention_engine is None and db_path is None:
-            raise ValueError("retention_engine or db_path is required")
-        self._engine = retention_engine
-        self._db_path = Path(db_path) if db_path is not None else None
-        self._interval = interval_seconds
-        self._timer: Optional[threading.Timer] = None
-        self._running = False
-        self._lock = threading.Lock()
-        self._stop_event = threading.Event()
-
-    @property
-    def is_running(self) -> bool:
-        """Whether the scheduler is currently running."""
-        return self._running
-
-    # ------------------------------------------------------------------
-    # Start / Stop
-    # ------------------------------------------------------------------
-
-    def start(self) -> None:
-        """Start the background scheduler.
-
-        Does nothing if already running. Schedules the first enforcement
-        cycle after interval_seconds.
-        """
-        with self._lock:
-            if self._running:
-                return
-            self._stop_event.clear()
-            self._running = True
-            self._schedule_next()
-            logger.info(
-                "Retention scheduler started (interval=%ds)",
-                self._interval,
-            )
-
-    def stop(self) -> bool:
-        """Stop the background scheduler.
-
-        Cancels the pending timer and waits briefly for an active cycle. Safe
-        to call even if not running. Returns False only when an active cycle
-        does not exit within the bounded shutdown window.
-        """
-        timer: threading.Timer | None
-        with self._lock:
-            self._running = False
-            self._stop_event.set()
-            timer = self._timer
-            self._timer = None
-            if timer is not None:
-                timer.cancel()
-        stopped = True
-        if timer is not None and timer is not threading.current_thread():
-            timer.join(timeout=10.0)
-            if timer.is_alive():
-                stopped = False
-                logger.warning("Retention scheduler did not stop within 10 seconds")
-        if stopped:
-            logger.info("Retention scheduler stopped")
-        return stopped
-
-    # ------------------------------------------------------------------
-    # Execution
-    # ------------------------------------------------------------------
-
-    def run_once(self) -> dict[str, Any]:
-        """Run retention enforcement once (for testing / manual trigger).
-
-        Returns:
-            Dict with enforcement results across all profiles.
-        """
-        return self._execute_cycle()
-
-    # ------------------------------------------------------------------
-    # Internal scheduling
-    # ------------------------------------------------------------------
-
-    def _schedule_next(self) -> None:
-        """Schedule the next enforcement cycle."""
-        self._timer = threading.Timer(self._interval, self._run_cycle)
-        self._timer.daemon = True
-        self._timer.start()
-
-    def _run_cycle(self) -> None:
-        """Run one enforcement cycle, then schedule the next."""
-        try:
-            if not self._stop_event.is_set():
-                self._execute_cycle()
-        except Exception as exc:
-            # Scheduler must not crash — log and continue
-            logger.error("Retention scheduler cycle failed: %s", exc)
-        finally:
-            with self._lock:
-                if self._running:
-                    self._schedule_next()
-
-    def _execute_cycle(self) -> dict[str, Any]:
-        """Core retention enforcement logic.
-
-        Discovers all profiles with retention rules and enforces each.
-        """
-        if self._db_path is not None:
-            return self._execute_db_path_cycle()
-        if self._engine is None:  # pragma: no cover - constructor invariant
-            raise RuntimeError("retention scheduler has no engine")
-        return self._execute_with_engine(self._engine)
-
-    def _execute_db_path_cycle(self) -> dict[str, Any]:
-        """Discover read-only, then enforce each profile in its own write transaction."""
-        from superlocalmemory.storage.memory_write import memory_read, memory_write
-
-        try:
-            with memory_read(self._db_path) as connection:
-                rows = connection.execute(
-                    "SELECT DISTINCT profile_id FROM retention_rules"
-                ).fetchall()
-                profile_ids = [str(row[0]) for row in rows]
-        except sqlite3.OperationalError:
-            profile_ids = []
-
-        results: list[dict[str, Any]] = []
-        for profile_id in profile_ids:
-            if self._stop_event.is_set():
-                break
-            try:
-                with memory_write(self._db_path) as connection:
-                    result = RetentionEngine(
-                        connection, autocommit=False
-                    ).enforce(profile_id)
-                results.append(result)
-            except Exception as exc:
-                logger.error(
-                    "Retention enforcement failed for profile '%s': %s",
-                    profile_id,
-                    exc,
-                )
-                results.append({"profile_id": profile_id, "error": str(exc)})
-        return {"profiles_processed": len(results), "results": results}
-
-    @staticmethod
-    def _execute_with_engine(engine: RetentionEngine) -> dict[str, Any]:
-        """Enforce one cycle through the supplied short-lived engine."""
-        results: list[dict[str, Any]] = []
-
-        try:
-            db = engine._db
-            rows = db.execute(
-                "SELECT DISTINCT profile_id FROM retention_rules"
-            ).fetchall()
-            profile_ids = [r[0] for r in rows]
-        except sqlite3.OperationalError:
-            profile_ids = []
-
-        for profile_id in profile_ids:
-            try:
-                result = engine.enforce(profile_id)
-                results.append(result)
-            except Exception as exc:
-                try:
-                    engine._db.rollback()
-                except sqlite3.Error:
-                    logger.exception(
-                        "Retention rollback failed for profile '%s'", profile_id
-                    )
-                logger.error(
-                    "Retention enforcement failed for profile '%s': %s",
-                    profile_id, exc,
-                )
-                results.append({
-                    "profile_id": profile_id,
-                    "error": str(exc),
-                })
-
-        return {
-            "profiles_processed": len(profile_ids),
-            "results": results,
-        }

package/src/superlocalmemory/contracts/__init__.py

@@ -1 +0,0 @@
-"""Versioned public contracts for cross-SLM integration surfaces."""

package/src/superlocalmemory/contracts/schemas/agent-experience-v1.schema.json

@@ -1,92 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://superlocalmemory.com/schemas/agent-experience-v1.schema.json",
-  "title": "SLM Agent Experience v1",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "experience_id",
-    "profile_id",
-    "occurred_at",
-    "task_class",
-    "project_scope",
-    "route",
-    "verification",
-    "producer_claim",
-    "terminal_status"
-  ],
-  "properties": {
-    "experience_id": {"type": "string", "minLength": 1},
-    "profile_id": {"type": "string", "minLength": 1},
-    "occurred_at": {"type": "string", "format": "date-time"},
-    "task_class": {"type": "string", "minLength": 1},
-    "project_scope": {"type": "string", "minLength": 1},
-    "complexity_band": {"type": "string"},
-    "risk": {"type": "string"},
-    "route": {"$ref": "#/$defs/route_identity"},
-    "bounds": {"$ref": "#/$defs/bounds"},
-    "usage": {"$ref": "#/$defs/usage"},
-    "verification": {"$ref": "#/$defs/verification"},
-    "producer_claim": {"enum": ["success", "failure", "partial", "unknown"]},
-    "terminal_status": {"enum": ["succeeded", "failed", "cancelled", "timed_out"]},
-    "failure_class": {"type": "string"},
-    "human_intervention": {"type": "boolean"},
-    "lessons": {"type": "string", "maxLength": 2000},
-    "receipt_digest": {"$ref": "#/$defs/sha256"},
-    "artifact_digests": {
-      "type": "array",
-      "items": {"$ref": "#/$defs/sha256"},
-      "uniqueItems": true
-    }
-  },
-  "$defs": {
-    "sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-    "route_identity": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["harness", "provider", "model", "effort", "machine"],
-      "properties": {
-        "harness": {"type": "string", "minLength": 1},
-        "provider": {"type": "string", "minLength": 1},
-        "model": {"type": "string", "minLength": 1},
-        "effort": {"type": "string", "minLength": 1},
-        "machine": {"type": "string", "minLength": 1}
-      }
-    },
-    "bounds": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "max_steps": {"type": "integer", "minimum": 1},
-        "max_wallclock_ms": {"type": "integer", "minimum": 1},
-        "max_cost_usd_micros": {"type": "integer", "minimum": 0}
-      }
-    },
-    "usage": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "input_tokens": {"type": "integer", "minimum": 0},
-        "output_tokens": {"type": "integer", "minimum": 0},
-        "wallclock_ms": {"type": "integer", "minimum": 0}
-      }
-    },
-    "verification": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["authority", "evidence_digest"],
-      "properties": {
-        "authority": {
-          "enum": [
-            "deterministic_gate",
-            "bounded_loop_receipt",
-            "human_approval",
-            "independent_model_audit"
-          ]
-        },
-        "evidence_digest": {"$ref": "#/$defs/sha256"},
-        "reference": {"type": "string", "maxLength": 1024}
-      }
-    }
-  }
-}

package/src/superlocalmemory/contracts/schemas/agent-integration-contract-v2.schema.json

@@ -1,46 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://superlocalmemory.com/schemas/agent-integration-contract-v2.schema.json",
-  "title": "SLM Agent Integration Contract v2",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["schema_version", "host", "stage", "lifecycle", "artifact_digest", "evidence"],
-  "properties": {
-    "schema_version": {"const": "v2"},
-    "host": {"type": "string", "minLength": 1},
-    "stage": {"$ref": "#/$defs/certification_stage"},
-    "lifecycle": {
-      "type": "array",
-      "items": {
-        "enum": [
-          "INSTALL", "CONFIG_PARSE", "PROCESS_START", "MCP_DISCOVERY", "SESSION_OPEN",
-          "TARGETED_RECALL", "CONTEXT_INJECTION", "MEMORY_WRITE", "OUTCOME_CAPTURE",
-          "RECONNECT", "SESSION_CLOSE", "UNINSTALL", "CONFIG_PRESERVATION", "SECRET_BOUNDARY"
-        ]
-      },
-      "uniqueItems": true,
-      "minItems": 14,
-      "maxItems": 14
-    },
-    "artifact_digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-    "evidence": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "additionalProperties": false,
-        "required": ["kind", "digest", "reference"],
-        "properties": {
-          "kind": {"enum": ["test_run", "artifact", "receipt", "manual_check"]},
-          "digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-          "reference": {"type": "string", "minLength": 1, "maxLength": 1024}
-        }
-      }
-    }
-  },
-  "$defs": {
-    "certification_stage": {
-      "enum": ["STATIC", "CONFIG_PROVEN", "LOCAL_RUNTIME", "END_TO_END", "RELEASE_GATED"]
-    }
-  }
-}

package/src/superlocalmemory/contracts/schemas/cognitive-turn-receipt-v1.schema.json

@@ -1,59 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://superlocalmemory.com/schemas/cognitive-turn-receipt-v1.schema.json",
-  "title": "SLM Cognitive Turn Receipt v1",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "receipt_id",
-    "task_id",
-    "profile_id",
-    "project_scope",
-    "query_digest",
-    "fact_decisions",
-    "state"
-  ],
-  "properties": {
-    "receipt_id": {"type": "string", "minLength": 1},
-    "task_id": {"type": "string", "minLength": 1},
-    "profile_id": {"type": "string", "minLength": 1},
-    "project_scope": {"type": "string", "minLength": 1},
-    "query_digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-    "fact_decisions": {
-      "description": "One decision per opaque fact identifier. An object, rather than an array, makes conflicting duplicate decisions structurally impossible for every schema consumer.",
-      "type": "object",
-      "minProperties": 1,
-      "additionalProperties": false,
-      "patternProperties": {
-        ".+": {"enum": ["considered", "used", "rejected", "corrected"]}
-      }
-    },
-    "outcome": {"$ref": "#/$defs/outcome"},
-    "state": {"enum": ["open", "finalized", "abandoned", "reconciled"]}
-  },
-  "allOf": [
-    {
-      "if": {"properties": {"state": {"const": "finalized"}}, "required": ["state"]},
-      "then": {"required": ["outcome"]}
-    }
-  ],
-  "$defs": {
-    "outcome": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["authority", "receipt_digest", "reference"],
-      "properties": {
-        "authority": {
-          "enum": [
-            "deterministic_gate",
-            "bounded_loop_receipt",
-            "human_approval",
-            "independent_model_audit"
-          ]
-        },
-        "receipt_digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-        "reference": {"type": "string", "minLength": 1, "maxLength": 1024}
-      }
-    }
-  }
-}

package/src/superlocalmemory/contracts/v402.py

@@ -1,62 +0,0 @@
-"""Validated SLM 4.0.2 contract boundaries.
-
-These validators are the required pre-persistence boundary for forthcoming
-Agent Experience and host-certificate writers. They prevent host/self-reported
-telemetry from masquerading as independently verified learning evidence.
-"""
-
-from __future__ import annotations
-
-import json
-from datetime import datetime
-from importlib import resources
-from typing import Any
-
-from jsonschema import Draft202012Validator, FormatChecker  # type: ignore[import-untyped]
-
-
-class ContractValidationError(ValueError):
-    """Raised when a cross-lane public contract is invalid."""
-
-
-_FORMAT_CHECKER = FormatChecker()
-
-
-@_FORMAT_CHECKER.checks("date-time")
-def _is_rfc3339_datetime(value: object) -> bool:
-    """Accept only timezone-aware ISO/RFC3339 timestamps."""
-    if not isinstance(value, str):
-        return False
-    try:
-        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
-    except ValueError:
-        return False
-    return parsed.tzinfo is not None
-
-
-def _validate(schema_name: str, payload: dict[str, Any]) -> None:
-    schema_path = resources.files(__package__).joinpath("schemas", schema_name)
-    schema = json.loads(schema_path.read_text(encoding="utf-8"))
-    errors = sorted(
-        Draft202012Validator(schema, format_checker=_FORMAT_CHECKER).iter_errors(payload),
-        key=lambda error: list(error.absolute_path),
-    )
-    if errors:
-        error = errors[0]
-        path = ".".join(str(part) for part in error.absolute_path) or "payload"
-        raise ContractValidationError(f"{path}: {error.message}")
-
-
-def validate_agent_experience(payload: dict[str, Any]) -> None:
-    """Validate independent outcome evidence before an experience is stored."""
-    _validate("agent-experience-v1.schema.json", payload)
-
-
-def validate_cognitive_turn(payload: dict[str, Any]) -> None:
-    """Validate the language-neutral fact-keyed receipt structure."""
-    _validate("cognitive-turn-receipt-v1.schema.json", payload)
-
-
-def validate_integration_certificate(payload: dict[str, Any]) -> None:
-    """Validate a hash-bound host lifecycle certificate."""
-    _validate("agent-integration-contract-v2.schema.json", payload)

package/src/superlocalmemory/core/actor_context.py

@@ -1,166 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-
-"""Server-derived actor identity for the V4 admission / policy layer.
-
-INVARIANT: ActorContext is ALWAYS constructed from server-authenticated state —
-session tokens, daemon descriptors, profile runtime, RBAC result — NEVER from
-the request body. This constraint is enforced by construction convention and
-audited in OperationPolicyRegistry.evaluate().
-
-Part of SuperLocalMemory V4 | Phase 4: Admission/Policy Layer
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import FrozenSet
-
-# Hosts that indicate a local-machine origin (loopback or in-process).
-_LOCAL_HOSTS: frozenset[str] = frozenset({"127.0.0.1", "::1", "localhost", ""})
-
-
-class ActorRole(str, Enum):
-    """Coarse role for an authenticated principal.
-
-    Roles form a permission lattice: OWNER ≥ ADMIN ≥ MEMBER ≥ VIEWER.
-    SYSTEM is for internal daemon operations; ANONYMOUS marks unauthenticated.
-    """
-
-    OWNER = "owner"
-    ADMIN = "admin"
-    MEMBER = "member"
-    VIEWER = "viewer"
-    SYSTEM = "system"
-    ANONYMOUS = "anonymous"
-
-
-class Transport(str, Enum):
-    """Physical transport through which the operation arrived.
-
-    Used by OperationPolicy.allowed_transports to restrict sensitive operations
-    to known-safe channels (e.g. SCHEMA_MIGRATE only via CLI or INTERNAL).
-    """
-
-    HTTP = "http"
-    MCP = "mcp"
-    CLI = "cli"
-    MESH = "mesh"
-    HOOK = "hook"
-    ADAPTER = "adapter"
-    DASHBOARD = "dashboard"
-    INTERNAL = "internal"  # In-process Python API path
-
-
-@dataclass(frozen=True, slots=True)
-class ActorContext:
-    """Immutable, server-derived actor identity for a single operation.
-
-    All fields come from server-side resolution (session store, RBAC, daemon
-    descriptor). None may originate from the request body. Callers that build
-    an ActorContext from untrusted input violate this contract — the registry
-    evaluator cannot detect this, so the constraint must be audited at the
-    construction site.
-
-    Field semantics
-    ---------------
-    principal_id        Stable user/operator identifier (never a raw token).
-    roles               Coarse permission set; OWNER means unrestricted writes.
-    allowed_profiles    Empty frozenset ≡ unrestricted (all profiles allowed).
-                        Non-empty ≡ explicit allowlist; any other profile is
-                        denied at the coordinator level, not here.
-    active_profile_id   Profile this operation targets.
-    scopes              Scope labels this actor may write to.
-    delegations         Signed capability tokens (future use).
-    transport           Channel through which the call arrived.
-    client_host         Resolved remote address; empty string ≡ in-process.
-    session_token_hash  First 16 hex chars of SHA-256 of session token.
-                        The raw token is NEVER stored here.
-    """
-
-    principal_id: str = ""
-    roles: FrozenSet[ActorRole] = field(
-        default_factory=lambda: frozenset({ActorRole.OWNER})
-    )
-    # empty = all profiles allowed; non-empty = explicit allowlist
-    allowed_profiles: FrozenSet[str] = field(default_factory=frozenset)
-    active_profile_id: str = ""
-    active_profile_generation: int = 0
-    scopes: FrozenSet[str] = field(
-        default_factory=lambda: frozenset({"personal", "project", "shared", "global"})
-    )
-    delegations: tuple[str, ...] = ()
-    transport: Transport = Transport.HTTP
-    client_host: str = ""
-    session_token_hash: str = ""  # SHA-256[:16] of session token — NEVER raw
-
-    # ------------------------------------------------------------------
-    # Derived predicates (pure, no I/O)
-    # ------------------------------------------------------------------
-
-    @property
-    def is_local(self) -> bool:
-        """True when the request originates from the local machine (loopback)."""
-        return self.client_host in _LOCAL_HOSTS
-
-    @property
-    def is_authenticated(self) -> bool:
-        """True when principal_id is non-empty and not an anonymous role."""
-        return self.principal_id != "" and ActorRole.ANONYMOUS not in self.roles
-
-
-# ---------------------------------------------------------------------------
-# Convenience constructors (server-side only — never call from request parsers)
-# ---------------------------------------------------------------------------
-
-def make_internal_owner_context(
-    *,
-    principal_id: str,
-    profile_id: str = "",
-) -> ActorContext:
-    """Build the standard ActorContext for the in-process Python API path.
-
-    Use this when the caller is the daemon itself or an authenticated local
-    operator using the Python SDK directly. The transport is INTERNAL and the
-    client_host is empty (treated as local).
-    """
-    return ActorContext(
-        principal_id=principal_id,
-        roles=frozenset({ActorRole.OWNER}),
-        active_profile_id=profile_id,
-        transport=Transport.INTERNAL,
-        client_host="",
-    )
-
-
-def make_http_actor_context(
-    *,
-    principal_id: str,
-    profile_id: str = "",
-    client_host: str = "",
-    session_token_hash: str = "",
-    roles: FrozenSet[ActorRole] | None = None,
-) -> ActorContext:
-    """Build the standard ActorContext for the HTTP /remember endpoint.
-
-    ``principal_id`` comes from ``_require_write_actor`` (server-side); it is
-    never the raw session token and never from the request body.
-    """
-    return ActorContext(
-        principal_id=principal_id,
-        roles=roles if roles is not None else frozenset({ActorRole.OWNER}),
-        active_profile_id=profile_id,
-        transport=Transport.HTTP,
-        client_host=client_host,
-        session_token_hash=session_token_hash,
-    )
-
-
-__all__ = [
-    "ActorContext",
-    "ActorRole",
-    "Transport",
-    "make_internal_owner_context",
-    "make_http_actor_context",
-]