topos-node 1.3.2__tar.gz → 1.3.3__tar.gz

{topos_node-1.3.2/topos_node.egg-info → topos_node-1.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.3.2
+Version: 1.3.3
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai

{topos_node-1.3.2 → topos_node-1.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.3.2"
+version = "1.3.3"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"

{topos_node-1.3.2 → topos_node-1.3.3}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.3.2"
-__version_info__ = (1, 3, 2)
+__version__ = "1.3.3"
+__version_info__ = (1, 3, 3)
 
 __all__ = ["__version__", "__version_info__"]

{topos_node-1.3.2 → topos_node-1.3.3}/topos/core/handlers/signal_features.py

@@ -993,3 +993,43 @@ async def handle_signal_set_worn_badge(message: Dict[str, Any]) -> Optional[Dict
         return {"id": req_id, "status": "ok", "payload": {"worn": worn_badge(conn)}}
     except Exception as exc:  # noqa: BLE001
         return {"id": req_id, "status": "error", "error": str(exc)}
+
+
+@handles("signal_pin_intent")
+async def handle_signal_pin_intent(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    req_id = message.get("id")
+    if not req_id:
+        return None
+    payload = message.get("payload") or {}
+    try:
+        from ...features.triage.intents import active_intents, pin_intent
+
+        intent_text = str(payload.get("intent_text") or "").strip()
+        if not intent_text:
+            raise ValueError("intent_text is required")
+        conn = hub.get_db_connection()
+        pin_intent(
+            conn,
+            intent_text,
+            horizon=payload.get("horizon") or "quarter",
+            links=payload.get("links") or [],
+        )
+        return {"id": req_id, "status": "ok", "payload": {"intents": active_intents(conn)}}
+    except Exception as exc:  # noqa: BLE001
+        return {"id": req_id, "status": "error", "error": str(exc)}
+
+
+@handles("signal_retire_intent")
+async def handle_signal_retire_intent(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    req_id = message.get("id")
+    if not req_id:
+        return None
+    payload = message.get("payload") or {}
+    try:
+        from ...features.triage.intents import active_intents, retire_intent
+
+        conn = hub.get_db_connection()
+        retire_intent(conn, payload.get("object_key") or "")
+        return {"id": req_id, "status": "ok", "payload": {"intents": active_intents(conn)}}
+    except Exception as exc:  # noqa: BLE001
+        return {"id": req_id, "status": "error", "error": str(exc)}

{topos_node-1.3.2 → topos_node-1.3.3}/topos/core/state.py

@@ -293,11 +293,37 @@ def get_db_connection() -> Optional[sqlite3.Connection]:
         except Exception as tuning_exc:  # noqa: BLE001
             logger.warning("Connection tuning skipped: %s", tuning_exc)
         try:
-            from ..storage.db.migrations import ensure_migrations_applied
+            from ..storage.db.migrations import (
+                DowngradeGuardError,
+                MigrationError,
+                ensure_migrations_applied,
+            )
 
             ensure_migrations_applied(db_conn)
+        except (MigrationError, DowngradeGuardError) as migration_exc:
+            # Shape migrations must fail loud — serving a half-migrated DB corrupts data.
+            logger.error("Schema migration failed; refusing to open database: %s", migration_exc)
+            try:
+                db_conn.close()
+            except Exception:  # noqa: BLE001
+                pass
+            db_conn = None
+            _db_conn_path = None
+            raise
         except Exception as migration_exc:  # noqa: BLE001
-            logger.warning("Wiki MVP migrations skipped on startup: %s", migration_exc)
+            from ..storage.db.migrations import MigrationError as _MigrationError
+
+            logger.error(
+                "Unexpected schema migration failure; refusing to open database: %s",
+                migration_exc,
+            )
+            try:
+                db_conn.close()
+            except Exception:  # noqa: BLE001
+                pass
+            db_conn = None
+            _db_conn_path = None
+            raise _MigrationError(str(migration_exc)) from migration_exc
         try:
             from ..storage.raw.browser_flat_tables import backfill_browser_visits_from_raw_retention
 
@@ -306,6 +332,12 @@ def get_db_connection() -> Optional[sqlite3.Connection]:
             logger.debug("browser_visits raw→flat backfill skipped: %s", backfill_exc)
         return db_conn
     except Exception as e:
+        # Shape-migration failures must propagate (fail loud). Only soft-fail
+        # unrelated connection errors so callers can treat conn=None as "no DB".
+        from ..storage.db.migrations import DowngradeGuardError, MigrationError
+
+        if isinstance(e, (MigrationError, DowngradeGuardError)):
+            raise
         logger.warning("Failed to create database connection: %s", e)
         db_conn = None
         _db_conn_path = None

{topos_node-1.3.2 → topos_node-1.3.3}/topos/features/triage/dashboard.py

@@ -61,6 +61,8 @@ def attention_dashboard_data(conn: sqlite3.Connection, *, days: int = 14,
         for v in verdicts:
             v["title"] = (titles.get(v["record_id"]) or v["table"] or "")[:90]
 
+    from .intents import intent_status
+
     intents = []
     for row in conn.execute(
         "SELECT payload_json, valid_from FROM signal_objects WHERE object_type='declared_intent' "
@@ -72,12 +74,18 @@ def attention_dashboard_data(conn: sqlite3.Connection, *, days: int = 14,
             continue
         # Pin instant lives on the row — surface it so pin days are plottable.
         intent.setdefault("pinned_at", row[1])
+        intent["status"] = intent_status(intent)
         intents.append(intent)
+    # Faded pins are not live steering, but the app shows what elapsed rather
+    # than letting an intent vanish silently.
+    faded = sorted((i for i in intents if i["status"] == "faded"),
+                   key=lambda i: str(i.get("origin_timeframe") or ""), reverse=True)[:5]
     return {
         "days": days,
         "verdicts": verdicts,
         "summaries": summaries,
-        "active_intents": [i for i in intents if i.get("status", "active") == "active"],
+        "active_intents": [i for i in intents if i["status"] == "active"],
+        "faded_intents": faded,
         "badges": earned_badges(conn),
         "current_badge": current_badge(conn),
         "rank": rank(conn),

{topos_node-1.3.2 → topos_node-1.3.3}/topos/features/triage/intents.py

@@ -14,10 +14,17 @@ from __future__ import annotations
 import json
 import re
 import sqlite3
+from datetime import date, timedelta
 from typing import Any, Dict, List, Optional, Tuple
 
 from ..signal.signal_object_store import SignalObjectStore
 
+# A pin is a bet with a shelf life. The horizon is coarse on purpose — owners
+# think in "weeks / months / this quarter", not in target dates — and it is the
+# only thing that decides when the pin stops steering.
+HORIZON_DAYS = {"weeks": 21, "months": 60, "quarter": 90}
+DEFAULT_HORIZON = "quarter"
+
 _STOP = {"the", "a", "an", "and", "or", "of", "to", "in", "for", "on", "with",
          "my", "our", "their", "this", "that", "is", "are", "be", "see",
          "more", "new", "build", "collect", "evidence", "people", "things"}
@@ -28,15 +35,46 @@ def _keywords(text: str) -> List[str]:
     return [w for w in words if w not in _STOP]
 
 
+def _parse_day(value: Any) -> Optional[date]:
+    try:
+        return date.fromisoformat(str(value)[:10])
+    except (TypeError, ValueError):
+        return None
+
+
+def intent_faded(intent: Dict[str, Any], *, today: Optional[date] = None) -> bool:
+    """Has this pin's horizon elapsed since it was declared?
+
+    Read-time only — nothing is ever rewritten. An intent with no parseable
+    origin never fades (we cannot date it, so we keep steering by it).
+    """
+    origin = _parse_day(intent.get("origin_timeframe"))
+    if origin is None:
+        return False
+    days = HORIZON_DAYS.get(str(intent.get("horizon") or DEFAULT_HORIZON),
+                            HORIZON_DAYS[DEFAULT_HORIZON])
+    return origin + timedelta(days=days) < (today or date.today())
+
+
+def intent_status(intent: Dict[str, Any], *, today: Optional[date] = None) -> str:
+    """Reported status: an explicit retire wins, otherwise the horizon decides."""
+    stored = str(intent.get("status") or "active")
+    if stored != "active":
+        return stored
+    return "faded" if intent_faded(intent, today=today) else "active"
+
+
 def pin_intent(conn: sqlite3.Connection, intent_text: str, *,
-               horizon: str = "quarter", links: Optional[List[str]] = None,
+               horizon: str = DEFAULT_HORIZON, links: Optional[List[str]] = None,
                origin_timeframe: Optional[str] = None) -> Dict[str, Any]:
     """F1: create (or refresh) a declared_intent signal object."""
     key = "intent:" + re.sub(r"[^a-z0-9]+", "-", intent_text.lower())[:60].strip("-")
     payload = {
         "intent_text": intent_text,
         "horizon": horizon,
-        "origin_timeframe": origin_timeframe,
+        # The fade clock starts the moment the pin is made unless the owner
+        # backdates it — an undated pin would otherwise steer forever.
+        "origin_timeframe": origin_timeframe or date.today().isoformat(),
         "status": "active",
         "links": links or [],
         "keywords": _keywords(intent_text),
@@ -49,7 +87,7 @@ def pin_intent(conn: sqlite3.Connection, intent_text: str, *,
         confidence=1.0, extractor_version="owner_declared", created_by="owner")
 
 
-def active_intents(conn: sqlite3.Connection) -> List[Dict[str, Any]]:
+def _all_intents(conn: sqlite3.Connection) -> List[Dict[str, Any]]:
     try:
         rows = conn.execute(
             "SELECT object_key, payload_json FROM signal_objects "
@@ -62,12 +100,51 @@ def active_intents(conn: sqlite3.Connection) -> List[Dict[str, Any]]:
             p = json.loads(pj)
         except (TypeError, ValueError):
             continue
-        if p.get("status", "active") == "active":
-            p["_key"] = key
-            out.append(p)
+        p["_key"] = key
+        out.append(p)
     return out
 
 
+def active_intents(conn: sqlite3.Connection,
+                   *, today: Optional[date] = None) -> List[Dict[str, Any]]:
+    """The live pins: neither retired by hand nor faded by their horizon."""
+    return [p for p in _all_intents(conn) if intent_status(p, today=today) == "active"]
+
+
+def faded_intents(conn: sqlite3.Connection, *, limit: int = 5,
+                  today: Optional[date] = None) -> List[Dict[str, Any]]:
+    """Pins whose horizon has elapsed, most recently declared first."""
+    out = []
+    for p in _all_intents(conn):
+        if intent_status(p, today=today) != "faded":
+            continue
+        p["status"] = "faded"
+        out.append(p)
+    out.sort(key=lambda p: str(p.get("origin_timeframe") or ""), reverse=True)
+    return out[:limit]
+
+
+def retire_intent(conn: sqlite3.Connection, object_key: str) -> Optional[Dict[str, Any]]:
+    """Manual retire — the owner calling it before the horizon does."""
+    key = str(object_key or "").strip()
+    row = conn.execute(
+        "SELECT payload_json FROM signal_objects WHERE object_type='declared_intent' "
+        "AND object_key=? AND valid_to IS NULL", (key,)).fetchone()
+    if not row:
+        return None
+    try:
+        payload = json.loads(row[0])
+    except (TypeError, ValueError):
+        return None
+    payload["status"] = "retired"
+    payload.pop("_key", None)
+    store = SignalObjectStore(conn)
+    return store.upsert_object(
+        "intentions", "declared_intent", key, payload,
+        source_refs=[{"declared_by": "owner"}],
+        confidence=1.0, extractor_version="owner_declared", created_by="owner")
+
+
 def intent_match(text: str, intents: List[Dict[str, Any]],
                  item_vec=None, intent_vecs=None) -> Tuple[float, Optional[str]]:
     """F2 semantic term: max proximity of an item to any active intent.

{topos_node-1.3.2 → topos_node-1.3.3}/topos/protocol/handled_message_types.json

@@ -172,7 +172,9 @@
     "signal_list_topic_clusters",
     "signal_list_vectors",
     "signal_owner_override_object",
+    "signal_pin_intent",
     "signal_refresh_brief",
+    "signal_retire_intent",
     "signal_search_vectors",
     "signal_set_worn_badge",
     "signal_timeline_daily",

topos_node-1.3.3/topos/storage/db/migrations/__init__.py

@@ -0,0 +1,190 @@
+"""Wiki MVP storage migration runner — single registry (PLAN §4a)."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import List, Optional
+
+from .backup import (
+    InsufficientDiskForBackup,
+    backup_database_before_migrations,
+    connection_db_path,
+)
+# Re-export migration IDs + registry used by tests/tools.
+from .registry import *  # noqa: F403
+from .registry import MIGRATIONS, MigrationSpec, max_migration_order  # noqa: F401
+from .canonical_disclosure_v1 import apply_canonical_disclosure_v1_up  # noqa: F401
+from .canonical_nsfw_v1 import apply_canonical_nsfw_v1_up  # noqa: F401
+from .complexity_v1 import apply_complexity_v1_up  # noqa: F401
+from .activity_events_content_v1 import apply_activity_events_content_v1_up  # noqa: F401
+from .actor_role_v1 import apply_actor_role_v1_up  # noqa: F401
+from .entity_blackhole_v1 import apply_entity_blackhole_v1_up  # noqa: F401
+from .attention_triage_v1 import apply_attention_triage_v1_up  # noqa: F401
+from .attention_triage_v2 import apply_attention_triage_v2_up  # noqa: F401
+from .documents_v1 import apply_documents_v1_up  # noqa: F401
+from .canonical_address_book_v1 import apply_canonical_address_book_v1_up  # noqa: F401
+
+logger = logging.getLogger("topos.storage.db.migrations")
+
+__all__ = [
+    "MigrationError",
+    "DowngradeGuardError",
+    "MigrationSpec",
+    "MIGRATIONS",
+    "apply_all_migrations",
+    "ensure_migrations_applied",
+    "pending_ledger_migrations",
+    "read_user_version",
+    "max_migration_order",
+]
+
+
+class MigrationError(RuntimeError):
+    """Schema migration failed; the database must not be served half-migrated."""
+
+
+class DowngradeGuardError(MigrationError):
+    """Database ``user_version`` is newer than this build knows how to open."""
+
+
+def _migration_applied(conn: sqlite3.Connection, migration_id: str) -> bool:
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM wiki_schema_migrations WHERE migration_id=?",
+            (migration_id,),
+        ).fetchone()
+        return row is not None
+    except sqlite3.OperationalError:
+        return False
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    try:
+        row = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (table,),
+        ).fetchone()
+        return row is not None
+    except sqlite3.OperationalError:
+        return False
+
+
+def read_user_version(conn: sqlite3.Connection) -> int:
+    row = conn.execute("PRAGMA user_version").fetchone()
+    if row is None:
+        return 0
+    return int(row[0])
+
+
+def _stamp_user_version(conn: sqlite3.Connection, order: int) -> None:
+    conn.execute(f"PRAGMA user_version = {int(order)}")
+
+
+def _shipped_version() -> str:
+    try:
+        from ....__version__ import __version__
+
+        return str(__version__)
+    except Exception:  # noqa: BLE001
+        return "unknown"
+
+
+def _needs_apply(conn: sqlite3.Connection, spec: MigrationSpec) -> bool:
+    if spec.always_run:
+        return True
+    if not _migration_applied(conn, spec.id):
+        return True
+    if spec.also_if_missing_table and not _table_exists(conn, spec.also_if_missing_table):
+        return True
+    return False
+
+
+def pending_ledger_migrations(conn: sqlite3.Connection) -> List[MigrationSpec]:
+    """Ledger-guarded migrations that have not yet been recorded as applied.
+
+    Used to decide whether a pre-migration backup is required. ``always_run``
+    steps alone do not trigger a backup.
+    """
+    pending: List[MigrationSpec] = []
+    for spec in MIGRATIONS:
+        if spec.always_run:
+            continue
+        if not _migration_applied(conn, spec.id):
+            pending.append(spec)
+            continue
+        if spec.also_if_missing_table and not _table_exists(
+            conn, spec.also_if_missing_table
+        ):
+            pending.append(spec)
+    return pending
+
+
+def apply_all_migrations(conn: sqlite3.Connection) -> None:
+    """Apply every migration unconditionally (tests / offline tools)."""
+    for spec in MIGRATIONS:
+        spec.fn(conn)
+    _stamp_user_version(conn, max_migration_order())
+
+
+def ensure_migrations_applied(
+    conn: sqlite3.Connection,
+    *,
+    skip_backup: bool = False,
+) -> Optional[str]:
+    """Apply pending schema migrations; fail loud on error.
+
+    Returns the backup path string when a pre-migration backup was written,
+    otherwise None. Raises ``DowngradeGuardError`` / ``MigrationError`` on
+    failure — callers must not serve a half-migrated database.
+    """
+    max_order = max_migration_order()
+    current = read_user_version(conn)
+    if current > max_order:
+        raise DowngradeGuardError(
+            f"database was upgraded by a newer topos-node "
+            f"(PRAGMA user_version={current} > {max_order} known to this build); "
+            f"upgrade the package or restore the pre-upgrade backup under "
+            f"~/.topos/backups/"
+        )
+
+    pending = pending_ledger_migrations(conn)
+    backup_path: Optional[str] = None
+
+    # Fast path: fully stamped DB with nothing pending — only always_run steps.
+    if current >= max_order and not pending:
+        for spec in MIGRATIONS:
+            if not spec.always_run:
+                continue
+            try:
+                spec.fn(conn)
+            except Exception as exc:  # noqa: BLE001
+                raise MigrationError(
+                    f"always-run migration {spec.id!r} failed: {exc}"
+                ) from exc
+        return None
+
+    if pending and not skip_backup and connection_db_path(conn) is not None:
+        try:
+            path = backup_database_before_migrations(
+                conn, shipped_version=_shipped_version()
+            )
+            if path is not None:
+                backup_path = str(path)
+        except InsufficientDiskForBackup as exc:
+            logger.error("%s", exc)
+            raise MigrationError(str(exc)) from exc
+
+    for spec in MIGRATIONS:
+        if not _needs_apply(conn, spec):
+            continue
+        try:
+            spec.fn(conn)
+        except Exception as exc:  # noqa: BLE001
+            hint = f" Restore from {backup_path}." if backup_path else ""
+            raise MigrationError(
+                f"schema migration {spec.id!r} (order={spec.order}) failed: {exc}.{hint}"
+            ) from exc
+
+    _stamp_user_version(conn, max_order)
+    return backup_path

topos_node-1.3.3/topos/storage/db/migrations/backup.py

@@ -0,0 +1,125 @@
+"""Pre-migration SQLite backup (PLAN_NODE_RELEASE_MIGRATIONS §4a.5)."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional
+
+logger = logging.getLogger("topos.storage.db.migrations.backup")
+
+BACKUP_RETENTION = 2
+_BACKUP_DIR_ENV = "TOPOS_BACKUP_DIR"
+
+
+class InsufficientDiskForBackup(RuntimeError):
+    """Raised when free disk is below 2× DB size and backup cannot proceed safely."""
+
+
+def backup_dir_for(db_path: Path) -> Path:
+    override = os.environ.get(_BACKUP_DIR_ENV)
+    if override:
+        return Path(override)
+    return db_path.expanduser().resolve().parent / "backups"
+
+
+def connection_db_path(conn: sqlite3.Connection) -> Optional[Path]:
+    """Return the on-disk path for the main DB, or None for :memory:/temp."""
+    try:
+        rows = conn.execute("PRAGMA database_list").fetchall()
+    except sqlite3.Error:
+        return None
+    for row in rows:
+        # row: (seq, name, file)
+        name = row[1] if not hasattr(row, "keys") else row["name"]
+        file_path = row[2] if not hasattr(row, "keys") else row["file"]
+        if str(name) != "main":
+            continue
+        if not file_path:
+            return None
+        path = Path(str(file_path))
+        if not path.is_file():
+            return None
+        return path
+    return None
+
+
+def _free_bytes(path: Path) -> Optional[int]:
+    try:
+        usage = shutil.disk_usage(path if path.is_dir() else path.parent)
+        return int(usage.free)
+    except OSError:
+        return None
+
+
+def prune_old_backups(directory: Path, *, keep: int = BACKUP_RETENTION) -> List[Path]:
+    """Keep the newest ``keep`` ``database-pre-v*.db`` files; delete older ones."""
+    if not directory.is_dir():
+        return []
+    candidates = sorted(
+        directory.glob("database-pre-v*.db"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    removed: List[Path] = []
+    for stale in candidates[keep:]:
+        try:
+            stale.unlink()
+            removed.append(stale)
+        except OSError as exc:
+            logger.warning("Failed to prune backup %s: %s", stale, exc)
+    return removed
+
+
+def backup_database_before_migrations(
+    conn: sqlite3.Connection,
+    *,
+    shipped_version: str,
+    keep: int = BACKUP_RETENTION,
+) -> Optional[Path]:
+    """Copy the live DB to ``~/.topos/backups/database-pre-v{ver}-{ts}.db``.
+
+    Returns the backup path, or None when there is no on-disk DB (in-memory /
+    test fixtures). Raises ``InsufficientDiskForBackup`` when free space is
+    below 2× the DB size (skip-with-loud-warning is the caller's choice — we
+    raise so boot can decide fail-loud vs warn).
+    """
+    db_path = connection_db_path(conn)
+    if db_path is None:
+        return None
+
+    dest_dir = backup_dir_for(db_path)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    size = db_path.stat().st_size
+    free = _free_bytes(dest_dir)
+    if free is not None and size > 0 and free < 2 * size:
+        raise InsufficientDiskForBackup(
+            f"free disk {free} bytes < 2× database size {size} bytes; "
+            f"refusing to migrate without a pre-upgrade backup under {dest_dir}"
+        )
+
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    safe_ver = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in shipped_version)
+    dest = dest_dir / f"database-pre-v{safe_ver}-{stamp}.db"
+    if dest.exists():
+        dest.unlink()
+
+    src = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+    try:
+        dst = sqlite3.connect(str(dest))
+        try:
+            with dst:
+                src.backup(dst)
+        finally:
+            dst.close()
+    finally:
+        src.close()
+
+    prune_old_backups(dest_dir, keep=keep)
+    logger.info("Pre-migration backup written to %s (%.1f MB)", dest, dest.stat().st_size / 1e6)
+    return dest