superlocalmemory 3.4.19 → 3.4.21

package/src/superlocalmemory/storage/migrations/M012_shadow_observations.py

@@ -0,0 +1,72 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21
+
+"""M012 — shadow_observations table (learning.db).
+
+Persists the paired NDCG@10 observations accumulated by
+``ShadowTest`` so a daemon restart during an in-flight shadow test
+does NOT throw away the 6-hour observation window. Without this
+table the candidate_id was re-attached on restart (Stage 9 W4
+H-ARC-01) but the observation list restarted from zero.
+
+Schema (additive only; no existing tables touched):
+
+    shadow_observations(
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      profile_id    TEXT NOT NULL,
+      candidate_id  INTEGER NOT NULL,
+      query_id      TEXT NOT NULL,
+      arm           TEXT NOT NULL CHECK (arm IN ('active','candidate')),
+      ndcg_at_10    REAL NOT NULL,
+      recorded_at   TEXT NOT NULL,
+      UNIQUE(candidate_id, query_id, arm)
+    )
+
+The ``UNIQUE(candidate_id, query_id, arm)`` constraint means a
+query_id is scored at most once per arm per candidate — if the
+daemon crashes mid-write and restarts, re-ingesting the same
+observation is an INSERT-OR-IGNORE no-op.
+
+Author: Varun Pratap Bhardwaj / Qualixar
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M012_shadow_observations"
+DB_TARGET = "learning"
+
+_REQUIRED_TABLES = frozenset({"shadow_observations"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        names = {
+            r[0]
+            for r in conn.execute(
+                "SELECT name FROM sqlite_master WHERE type='table'"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_TABLES.issubset(names)
+
+
+DDL = """
+CREATE TABLE IF NOT EXISTS shadow_observations (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    profile_id    TEXT NOT NULL,
+    candidate_id  INTEGER NOT NULL,
+    query_id      TEXT NOT NULL,
+    arm           TEXT NOT NULL,
+    ndcg_at_10    REAL NOT NULL,
+    recorded_at   TEXT NOT NULL,
+    UNIQUE(candidate_id, query_id, arm)
+);
+CREATE INDEX IF NOT EXISTS idx_shadow_obs_candidate
+    ON shadow_observations(candidate_id, recorded_at);
+CREATE INDEX IF NOT EXISTS idx_shadow_obs_profile
+    ON shadow_observations(profile_id, recorded_at);
+"""

package/src/superlocalmemory/storage/migrations/M013_bi_temporal_columns.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21
+
+"""M013 — bi-temporal columns on ``atomic_facts`` (memory.db, deferred).
+
+Adds two NULLable columns that let SLM capture fact validity windows
+WITHOUT changing the retrieval path today. Wiring the retrieval
+consumer is a later-cycle item; what we ship in v3.4.21 is the
+data-capture surface so existing user memories start accumulating
+temporal metadata on every new fact.
+
+Columns (both nullable, no default so existing rows stay NULL):
+
+    valid_from     TEXT  — ISO-8601 instant from which the fact is
+                           considered valid. NULL ⇒ "valid since
+                           creation" (the current default semantics).
+    valid_until    TEXT  — ISO-8601 instant after which the fact is
+                           considered superseded. NULL ⇒ still valid.
+
+Deferred like M006 and M011 because ``atomic_facts`` is bootstrapped
+at engine init, not at migration time. Daemon lifespan calls
+``apply_deferred`` right after engine init so these columns materialise
+on first boot after upgrade.
+
+Author: Varun Pratap Bhardwaj / Qualixar
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+NAME = "M013_bi_temporal_columns"
+DB_TARGET = "memory"
+
+_REQUIRED_COLS = frozenset({"valid_from", "valid_until"})
+
+
+def verify(conn: sqlite3.Connection) -> bool:
+    try:
+        cols = {
+            r[1]
+            for r in conn.execute(
+                "PRAGMA table_info(atomic_facts)"
+            ).fetchall()
+        }
+    except sqlite3.Error:
+        return False
+    return _REQUIRED_COLS.issubset(cols)
+
+
+DDL = """
+ALTER TABLE atomic_facts ADD COLUMN valid_from TEXT;
+ALTER TABLE atomic_facts ADD COLUMN valid_until TEXT;
+"""

package/src/superlocalmemory/storage/migrations/__init__.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory v3.4.21 — LLD-07
+
+"""v3.4.21 migration definitions.
+
+One module per migration. Each exposes:
+  - ``NAME``: canonical migration name (used in ``migration_log``)
+  - ``DB_TARGET``: either ``"learning"`` or ``"memory"``
+  - ``DDL``: the full DDL string including ``BEGIN IMMEDIATE`` / ``COMMIT``
+    (where the migration warrants a transaction; see each module).
+
+The ordered list here is the authoritative order for ``migration_runner``.
+M003 must run first (bootstraps the log table); the others follow in the
+order LLD-07 §4 specifies.
+"""
+
+from __future__ import annotations
+
+from . import (
+    M001_add_signal_features_columns,
+    M002_model_state_history,
+    M003_migration_log,
+    M004_cross_platform_sync_log,
+    M005_bandit_tables,
+)
+
+# ---------------------------------------------------------------------------
+# Backward-compat shim: the legacy flat module
+# ``superlocalmemory/storage/migrations.py`` shipped in v3.4.20 carried
+# ``CURRENT_SCHEMA_VERSION`` / ``get_schema_version`` / ``set_schema_version``
+# / ``is_v1_database`` / ``needs_migration`` / ``backup_database``. Creating
+# the ``migrations/`` package in Wave 1 shadowed that flat module, so any
+# caller that did ``from superlocalmemory.storage.migrations import X``
+# broke. We re-load the legacy module under a distinct name and re-export
+# the symbols here so pre-3.4.21 callers (and the pre-existing tests at
+# ``tests/test_storage/test_migrations.py``) keep working unchanged.
+# ---------------------------------------------------------------------------
+
+
+def _load_legacy_module():  # pragma: no cover — trivial file loader
+    import importlib.util
+    from pathlib import Path as _Path
+
+    legacy_path = _Path(__file__).resolve().parents[1] / "migrations.py"
+    if not legacy_path.is_file():
+        return None
+    spec = importlib.util.spec_from_file_location(
+        "superlocalmemory.storage._legacy_migrations_flat",
+        str(legacy_path),
+    )
+    if spec is None or spec.loader is None:
+        return None
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_legacy = _load_legacy_module()
+if _legacy is not None:
+    CURRENT_SCHEMA_VERSION = getattr(_legacy, "CURRENT_SCHEMA_VERSION", 1)
+    get_schema_version = getattr(_legacy, "get_schema_version", None)
+    set_schema_version = getattr(_legacy, "set_schema_version", None)
+    is_v1_database = getattr(_legacy, "is_v1_database", None)
+    needs_migration = getattr(_legacy, "needs_migration", None)
+    backup_database = getattr(_legacy, "backup_database", None)
+
+__all__ = (
+    "M001_add_signal_features_columns",
+    "M002_model_state_history",
+    "M003_migration_log",
+    "M004_cross_platform_sync_log",
+    "M005_bandit_tables",
+    # Legacy re-exports (backward compat):
+    "CURRENT_SCHEMA_VERSION",
+    "get_schema_version",
+    "set_schema_version",
+    "is_v1_database",
+    "needs_migration",
+    "backup_database",
+)

package/src/superlocalmemory/storage/models.py

@@ -391,6 +391,10 @@ class RetrievalResult:
     confidence: float = 0.0
     evidence_chain: list[str] = field(default_factory=list)
     trust_score: float = 0.5
+    # LLD-00 §3 + P0.4: HMAC marker emitted during recall so post-tool hooks
+    # can validate that a fact_id observed in tool output really came from
+    # this install. Empty string by default preserves backward-compat.
+    marker: str = ""
 
 
 @dataclass

package/src/superlocalmemory/ui/css/brain.css

@@ -0,0 +1,409 @@
+/*
+ * Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+ * Licensed under AGPL-3.0-or-later - see LICENSE file
+ * Part of SuperLocalMemory v3.4.21 — LLD-04 §4.5
+ *
+ * Brain tab styles. Pure design-system variables — no inline styles
+ * anywhere in the UI, so CSP `style-src 'self'` can stay strict.
+ */
+
+.brain-section {
+  background: var(--ng-glass-bg, rgba(255, 255, 255, 0.04));
+  border-radius: 12px;
+  padding: 20px;
+  margin-bottom: 16px;
+}
+
+.brain-section h4 {
+  font-size: 0.875rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.9));
+  margin-bottom: 0.75rem;
+}
+
+.brain-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.brain-list li {
+  padding: 4px 0;
+  border-bottom: 1px solid var(--ng-border-subtle, rgba(148, 163, 184, 0.08));
+}
+
+.brain-list li.brain-empty {
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.7));
+  font-style: italic;
+}
+
+.brain-notice {
+  margin-top: 8px;
+  font-size: 0.8125rem;
+  color: var(--ng-warn, rgb(202, 138, 4));
+}
+
+.brain-honesty-badge {
+  display: inline-block;
+  font-size: 0.6875rem;
+  padding: 2px 8px;
+  border-radius: 10px;
+  margin-top: 6px;
+}
+
+.brain-honesty-badge.real {
+  background: rgba(34, 197, 94, 0.12);
+  color: rgb(22, 163, 74);
+}
+
+.brain-honesty-badge.counter {
+  background: rgba(234, 179, 8, 0.12);
+  color: rgb(202, 138, 4);
+}
+
+.brain-honesty-badge.soon {
+  background: rgba(148, 163, 184, 0.15);
+  color: rgb(100, 116, 139);
+}
+
+.brain-phase-pill {
+  display: inline-block;
+  padding: 4px 12px;
+  border-radius: 999px;
+  background: rgba(148, 163, 184, 0.15);
+  font-size: 0.8125rem;
+}
+
+.brain-phase-pill.active {
+  background: var(--ng-accent, rgb(59, 130, 246));
+  color: #fff;
+}
+
+.brain-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 16px;
+}
+
+.brain-error {
+  padding: 16px;
+  background: rgba(239, 68, 68, 0.08);
+  color: rgb(220, 38, 38);
+  border-radius: 8px;
+  margin-bottom: 12px;
+}
+
+.brain-subhead {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.85));
+  margin: 16px 0 8px 0;
+}
+
+.brain-help {
+  font-size: 0.8125rem;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.9));
+  margin-bottom: 12px;
+}
+
+/* Key-value stat grid (Learning, Bandit, Cache) */
+.brain-stat-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 8px 24px;
+  margin-top: 12px;
+}
+
+.brain-stat-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  padding: 6px 0;
+  border-bottom: 1px solid var(--ng-border-subtle, rgba(148, 163, 184, 0.08));
+  gap: 12px;
+}
+
+.brain-stat-label {
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.85));
+  font-size: 0.8125rem;
+}
+
+.brain-stat-value {
+  font-weight: 590;
+  font-size: 0.9375rem;
+  text-align: right;
+  word-break: break-word;
+}
+
+/* Preferences — three columns (Topics / Entities / Tech) */
+.brain-pref-cols {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 20px;
+  margin-top: 8px;
+}
+
+@media (max-width: 900px) {
+  .brain-pref-cols { grid-template-columns: 1fr; }
+  .brain-stat-grid { grid-template-columns: 1fr; }
+}
+
+.brain-pref-col {
+  min-width: 0;
+}
+
+/* Outcome tiles */
+.brain-outcome-tiles {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 12px;
+  margin: 12px 0;
+}
+
+.brain-outcome-tile {
+  padding: 14px 12px;
+  border-radius: 10px;
+  text-align: center;
+  background: var(--ng-glass-bg, rgba(255, 255, 255, 0.03));
+  border: 1px solid var(--ng-border-subtle, rgba(148, 163, 184, 0.12));
+}
+
+.brain-outcome-count {
+  font-size: 1.5rem;
+  font-weight: 700;
+  line-height: 1;
+}
+
+.brain-outcome-label {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.85));
+  margin-top: 6px;
+}
+
+.brain-outcome-tile.success .brain-outcome-count { color: rgb(22, 163, 74); }
+.brain-outcome-tile.failure .brain-outcome-count { color: rgb(220, 38, 38); }
+.brain-outcome-tile.warn    .brain-outcome-count { color: rgb(202, 138, 4); }
+
+/* Adapter tiles (Cross-platform) */
+.brain-adapter-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 12px;
+  margin-top: 8px;
+}
+
+@media (max-width: 900px) {
+  .brain-adapter-grid { grid-template-columns: repeat(2, 1fr); }
+  .brain-outcome-tiles { grid-template-columns: repeat(2, 1fr); }
+}
+
+.brain-adapter-tile {
+  padding: 12px;
+  border-radius: 10px;
+  background: var(--ng-glass-bg, rgba(255, 255, 255, 0.03));
+  border: 1px solid var(--ng-border-subtle, rgba(148, 163, 184, 0.12));
+  position: relative;
+}
+
+.brain-adapter-tile.on {
+  border-color: rgba(34, 197, 94, 0.35);
+}
+
+.brain-adapter-name {
+  font-weight: 590;
+  font-size: 0.9375rem;
+  margin-right: 18px;
+}
+
+.brain-adapter-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 999px;
+  position: absolute;
+  top: 14px;
+  right: 14px;
+}
+
+.brain-adapter-dot.dot-on  { background: rgb(34, 197, 94); }
+.brain-adapter-dot.dot-off { background: rgba(148, 163, 184, 0.45); }
+
+.brain-adapter-detail {
+  font-size: 0.8125rem;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.9));
+  margin-top: 6px;
+}
+
+/* Report-outcome form */
+.brain-form {
+  display: grid;
+  grid-template-columns: 1.4fr 1fr 1.2fr 1.4fr auto;
+  gap: 8px;
+  align-items: center;
+}
+
+@media (max-width: 900px) {
+  .brain-form { grid-template-columns: 1fr; }
+}
+
+.brain-input {
+  padding: 6px 10px;
+  border-radius: 6px;
+  border: 1px solid var(--ng-border-subtle, rgba(148, 163, 184, 0.18));
+  background: var(--ng-glass-bg, rgba(255, 255, 255, 0.04));
+  color: inherit;
+  font: inherit;
+  font-size: 0.875rem;
+}
+
+.brain-form-submit { white-space: nowrap; }
+
+.brain-form-status {
+  grid-column: 1 / -1;
+  font-size: 0.8125rem;
+  color: var(--ng-text-tertiary, rgba(148, 163, 184, 0.9));
+  margin-top: 4px;
+  min-height: 1.2em;
+}
+
+/* Danger zone */
+.brain-section.brain-danger {
+  border: 1px solid rgba(239, 68, 68, 0.25);
+}
+
+.brain-danger-btn { margin-right: 10px; }
+
+/* Evolution trend chart (v3.4.21) */
+.brain-chart-wrap {
+  width: 100%;
+  margin: 8px 0 10px;
+  overflow: hidden;
+}
+.brain-evolution-chart {
+  width: 100%;
+  height: auto;
+  display: block;
+  max-height: 200px;
+}
+
+/* S9-DASH-05: closed-loop tile key-value grid */
+.brain-kv-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 8px;
+  margin: 6px 0 8px;
+}
+.brain-kv {
+  background: rgba(255, 255, 255, 0.03);
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 6px;
+  padding: 6px 10px;
+  transition: background 0.15s ease, transform 0.15s ease;
+}
+.brain-kv:hover {
+  background: rgba(255, 255, 255, 0.06);
+  transform: translateY(-1px);
+}
+.brain-kv-label {
+  font-size: 10px;
+  color: #888;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 2px;
+}
+.brain-kv-value {
+  font-size: 15px;
+  font-weight: 500;
+  color: #eee;
+}
+
+/* S9-DASH animations — click + async feedback */
+@keyframes slm-pulse {
+  0% { transform: scale(1); }
+  50% { transform: scale(0.96); }
+  100% { transform: scale(1); }
+}
+@keyframes slm-flash-success {
+  0%   { background: rgba(40, 167, 69, 0); }
+  50%  { background: rgba(40, 167, 69, 0.35); }
+  100% { background: rgba(40, 167, 69, 0); }
+}
+@keyframes slm-flash-fail {
+  0%   { background: rgba(220, 53, 69, 0); }
+  50%  { background: rgba(220, 53, 69, 0.35); }
+  100% { background: rgba(220, 53, 69, 0); }
+}
+@keyframes slm-shake {
+  0%, 100% { transform: translateX(0); }
+  25%  { transform: translateX(-3px); }
+  75%  { transform: translateX(3px); }
+}
+@keyframes slm-spin {
+  from { transform: rotate(0deg); }
+  to   { transform: rotate(360deg); }
+}
+
+.slm-anim-click {
+  animation: slm-pulse 0.18s ease-out;
+}
+.slm-anim-success {
+  animation: slm-flash-success 0.8s ease-out;
+}
+.slm-anim-fail {
+  animation: slm-flash-fail 0.6s ease-out, slm-shake 0.35s ease-out;
+}
+.slm-anim-spin::after {
+  content: '';
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  margin-left: 6px;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  animation: slm-spin 0.6s linear infinite;
+  vertical-align: -2px;
+}
+
+/* S9-DASH-04: auto-detected pattern rows hover */
+.brain-list li {
+  padding: 3px 0;
+  transition: background 0.15s ease;
+  border-radius: 3px;
+}
+.brain-list li:hover {
+  background: rgba(255, 255, 255, 0.04);
+}
+.brain-pattern-del {
+  transition: transform 0.12s ease, background 0.15s ease;
+}
+.brain-pattern-del:hover:not([disabled]) {
+  transform: scale(1.15);
+  background: rgba(220, 53, 69, 0.15) !important;
+}
+
+/* S9-DASH-07: memory filter pills */
+.mem-filter-pill {
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+.mem-filter-pill:hover {
+  transform: translateY(-1px);
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+}
+.mem-filter-pill.active {
+  transform: scale(0.98);
+  box-shadow: inset 0 2px 4px rgba(0, 0, 0, 0.2);
+}
+
+/* S9-DASH-06: inline feedback thumbs */
+.inline-feedback button {
+  transition: transform 0.12s ease, background 0.15s ease,
+    border-color 0.15s ease, color 0.15s ease;
+}
+.inline-feedback button:hover:not([disabled]) {
+  transform: scale(1.2);
+}