seren-margin 2.2.0__tar.gz → 2.3.0__tar.gz

{seren_margin-2.2.0/seren_margin.egg-info → seren_margin-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seren-margin
-Version: 2.2.0
+Version: 2.3.0
 Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
 Author: Chad Roesler
 License-Expression: AGPL-3.0-or-later
@@ -16,6 +16,7 @@ Requires-Dist: uvicorn[standard]>=0.27
 Requires-Dist: pydantic>=2.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: seren-meninges<3,>=2.4.0
+Requires-Dist: seren-sinew<2,>=1.8.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: httpx>=0.26; extra == "test"

{seren_margin-2.2.0 → seren_margin-2.3.0}/pyproject.toml

@@ -25,6 +25,8 @@ dependencies = [
     # SERVICES required" (no Workbench, no cluster head), not "no shared
     # library". Margin still runs alone on localhost with nothing else deployed.
     "seren-meninges>=2.4.0,<3",
+    # seren_sinew.stores: snapshots of the notes database (1.8.0: the archive gate).
+    "seren-sinew>=1.8.0,<2",
 ]
 
 [project.optional-dependencies]

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.0'
-__version_tuple__ = version_tuple = (2, 2, 0)
+__version__ = version = '2.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)
 
-__commit_id__ = commit_id = 'g77bceb68b'
+__commit_id__ = commit_id = 'g3339c1e00'

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin/app.py

@@ -97,6 +97,13 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
         app.state.store = store
         app.state.cfg = cfg
 
+        # Snapshots of the notes database on Margin's own schedule.
+        _snap_task = None
+        if app.state.stores is not None and cfg.backup.every_hours > 0:
+            import asyncio
+            from seren_sinew.stores import snapshot_loop
+            _snap_task = asyncio.create_task(snapshot_loop(lambda: app.state.stores, cfg.backup.every_hours))
+
         # -- Optional MCP server --
         # Mounted ONLY if the [mcp] extra is installed. A missing package falls
         # back to pure-HTTP mode without crashing - the HTTP API and the
@@ -141,6 +148,8 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
                 await _mcp_stack.enter_async_context(session_manager.run())
                 diag("[seren-margin] MCP session manager running")
             yield
+        if _snap_task is not None:
+            _snap_task.cancel()
 
     app = FastAPI(
         title="SerenMargin",
@@ -208,6 +217,31 @@ def create_app(config: Optional[MarginConfig] = None) -> FastAPI:
 
         return Response(content=content, media_type="application/yaml")
 
+    # -- What Margin keeps, and snapshots of it (seren_sinew.stores) --
+    # The database, copied whole; no export. Counts only in the manifest: a
+    # snapshot's listing must not say what the notes say. The archive (the
+    # diary itself) is handed over HTTP only with backup.allow_pull.
+    from seren_sinew.stores import Store, StoreKeeper, add_store_routes
+
+    def _margin_extra() -> dict:
+        try:
+            notes = len(store.list_all(limit=1_000_000))
+        except Exception:  # noqa: BLE001
+            notes = None
+        return {"version": APP_VERSION, "counts": {"notes": notes}}
+
+    app.state.stores = StoreKeeper(
+        "seren-margin",
+        lambda: [Store("notes", "sqlite", str(cfg.resolved_db_path()),
+                       "the margin: private notes, letters and the dedication")],
+        cfg.resolved_backup_dir(), extra=_margin_extra,
+        keep_daily=cfg.backup.keep_daily, keep_weekly=cfg.backup.keep_weekly,
+        log=lambda m: diag(f"[seren-margin] {m}")) if cfg.backup.enabled else None
+    add_store_routes(
+        app, lambda: app.state.stores, archive_allowed=lambda: cfg.backup.allow_pull,
+        archive_refusal="the margin's snapshots stay on this box: an archive is the whole diary. "
+                        "backup.allow_pull: true lets a Lodestar stash them elsewhere.")
+
     @app.get("/health")
     async def health():
         return {"ok": True, "service": "seren-margin", "version": APP_VERSION}

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin/config.py

@@ -63,6 +63,25 @@ class UpdatesConfig(BaseModel):
     allow_prerelease: bool = False
 
 
+class BackupConfig(BaseModel):
+    """Snapshots of the notes database (seren_sinew.stores), on Margin's own
+    schedule, kept beside it. The snapshot is the database itself - there is
+    no plain-text export of a diary lying in a folder.
+
+    allow_pull: whether a snapshot may be handed over HTTP (GET
+    /stores/snapshots/{id}/archive), which is how a Lodestar stashes it on
+    another box. OFF by default, for the reason http_reads is: an archive is
+    the whole diary. Taking a snapshot and listing them say nothing of what
+    is inside and are always there. Whoever the margin belongs to turns this
+    on, knowing the copy then lives wherever the cluster head keeps it."""
+    enabled: bool = True
+    dir: str = ""                 # blank = `backups` beside the database
+    every_hours: float = 24.0     # 0 = never on its own
+    keep_daily: int = 14
+    keep_weekly: int = 8
+    allow_pull: bool = False
+
+
 class MarginConfig(BaseModel):
     """SerenMargin service config. Defaults are the Nano-floor: per-user,
     localhost-only, sqlite under the user's home directory.
@@ -105,6 +124,7 @@ class MarginConfig(BaseModel):
     # tools to these routes - and give it a bearer when you do.
     http_reads: bool = False
     updates: UpdatesConfig = Field(default_factory=UpdatesConfig)
+    backup: BackupConfig = Field(default_factory=BackupConfig)
 
     # REMOVED: notes_days. It configured an auto-expiry sweep that was taken
     # out when the lifecycle was (no pin, no expiry, no done - notes live until
@@ -117,6 +137,11 @@ class MarginConfig(BaseModel):
     def resolved_db_path(self) -> Path:
         return Path(self.db_path).expanduser()
 
+    def resolved_backup_dir(self) -> Path:
+        if self.backup.dir.strip():
+            return Path(self.backup.dir).expanduser().resolve()
+        return self.resolved_db_path().resolve().parent / "backups"
+
     def resolve_bearer(self) -> str:
         """The token callers must present, or "" for open. Same resolver
         every Seren service uses: inline > keyring > env var."""
@@ -223,6 +248,17 @@ def load_config(path: Optional[str] = None) -> MarginConfig:
             _apply_server_overrides(cfg, server, source=str(yaml_path))
         elif server is not None:
             diag(f"[seren-margin] config: 'server' in {yaml_path} must be a mapping; ignoring")
+        backup = data.get("backup")
+        if isinstance(backup, dict):
+            try:
+                cfg.backup = BackupConfig(**{k: v for k, v in backup.items() if k in BackupConfig.model_fields})
+                for k in backup:
+                    if k not in BackupConfig.model_fields:
+                        diag(f"[seren-margin] config: ignoring unknown backup key '{k}' from {yaml_path}")
+            except Exception as e:  # noqa: BLE001 - a bad value keeps the defaults, like every other key
+                diag(f"[seren-margin] config: ignored bad 'backup' block from {yaml_path}: {e}")
+        elif backup is not None:
+            diag(f"[seren-margin] config: 'backup' in {yaml_path} must be a mapping; ignoring")
         # NOTE: data.get('tools') is intentionally NOT read here. That section
         # is reserved for a future plug-and-play MCP tool layer, which has its
         # own loader. Same file, different reader, by design.

{seren_margin-2.2.0 → seren_margin-2.3.0/seren_margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seren-margin
-Version: 2.2.0
+Version: 2.3.0
 Summary: Private notes-to-self for an AI assistant. Standalone, opt-in, opinionated.
 Author: Chad Roesler
 License-Expression: AGPL-3.0-or-later
@@ -16,6 +16,7 @@ Requires-Dist: uvicorn[standard]>=0.27
 Requires-Dist: pydantic>=2.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: seren-meninges<3,>=2.4.0
+Requires-Dist: seren-sinew<2,>=1.8.0
 Provides-Extra: test
 Requires-Dist: pytest>=8.0; extra == "test"
 Requires-Dist: httpx>=0.26; extra == "test"

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin.egg-info/SOURCES.txt

@@ -39,4 +39,5 @@ tests/test_reads_stay_private.py
 tests/test_search.py
 tests/test_smoke.py
 tests/test_stats_content_blind.py
+tests/test_stores_snapshot.py
 tests/test_updates_contract.py

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin.egg-info/requires.txt

@@ -3,6 +3,7 @@ uvicorn[standard]>=0.27
 pydantic>=2.5
 pyyaml>=6.0
 seren-meninges<3,>=2.4.0
+seren-sinew<2,>=1.8.0
 
 [mcp]
 mcp<2,>=1.0

{seren_margin-2.2.0 → seren_margin-2.3.0}/seren_margin.egg-info/scm_file_list.json

@@ -32,6 +32,7 @@
     "tests/test_search.py",
     "tests/test_smoke.py",
     "tests/test_stats_content_blind.py",
+    "tests/test_stores_snapshot.py",
     "tests/test_updates_contract.py"
   ]
 }

seren_margin-2.3.0/seren_margin.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.3.0",
+  "distance": 0,
+  "node": "g3339c1e00691cab41191c0b5903aa93cb1df799b",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-03"
+}

seren_margin-2.3.0/tests/test_stores_snapshot.py

@@ -0,0 +1,83 @@
+"""
+Margin snapshots its own database, and keeps the snapshots to itself.
+
+The margin is private (http_reads is off: 'its your diary... i dont want to
+see them unless you tell me them'). A backup must not become a way round
+that. Pinned here:
+
+- GET /stores and a snapshot's listing say nothing of what a note says
+- the snapshot is the database copied whole; there is no plain-text export
+- the archive - the diary itself - is refused over HTTP unless
+  backup.allow_pull is on, and the yaml key is honoured
+- backup.enabled: false turns it off; no route restores or deletes
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+from seren_margin.app import create_app
+from seren_margin.config import BackupConfig, MarginConfig, load_config
+
+SECRET = "the thing I have not told Chad yet"
+
+
+def _client(tmp_path, **backup):
+    cfg = MarginConfig(db_path=str(tmp_path / "store" / "notes.db"), backup=BackupConfig(every_hours=0, **backup))
+    (tmp_path / "store").mkdir(exist_ok=True)
+    return TestClient(create_app(cfg))
+
+
+def test_listing_and_taking_a_snapshot_say_nothing_of_the_notes(tmp_path):
+    with _client(tmp_path) as c:
+        c.post("/notes", json={"content": SECRET, "topic": "private"})
+        d = c.get("/stores")
+        assert d.status_code == 200 and SECRET not in d.text and "private" not in d.text.replace("private notes", "")
+        assert d.json()["stores"][0]["kind"] == "sqlite"
+        assert Path(d.json()["snapshots"]["dir"]) == (tmp_path / "store" / "backups" / "seren-margin").resolve()
+        r = c.post("/stores/snapshot", json={"reason": "by hand"})
+        assert r.status_code == 200 and SECRET not in r.text
+        snap = r.json()["snapshot"]
+        assert snap["counts"] == {"notes": 1}
+        root = Path(snap["path"])
+        man = (root / "manifest.json").read_text(encoding="utf-8")
+        assert SECRET not in man and json.loads(man)["exports"] == {}, "no plain-text export of a diary"
+        assert not (root / "export").exists()
+        con = sqlite3.connect(root / "raw" / "notes" / "notes.db")
+        assert con.execute("SELECT content FROM notes").fetchone()[0] == SECRET, "the database, whole"
+        con.close()
+        assert SECRET not in c.get("/stores/snapshots").text
+
+
+def test_the_archive_stays_on_the_box_unless_asked_to_travel(tmp_path):
+    with _client(tmp_path) as c:
+        c.post("/notes", json={"content": SECRET})
+        sid = c.post("/stores/snapshot").json()["snapshot"]["id"]
+        r = c.get(f"/stores/snapshots/{sid}/archive")
+        assert r.status_code == 403 and "whole diary" in r.json()["error"] and "allow_pull" in r.json()["error"]
+        assert SECRET.encode() not in r.content
+    with _client(tmp_path, allow_pull=True) as c:
+        sid = c.post("/stores/snapshot").json()["snapshot"]["id"]
+        r = c.get(f"/stores/snapshots/{sid}/archive")
+        assert r.status_code == 200 and r.headers["content-type"] == "application/gzip"
+
+
+def test_the_yaml_block_is_honoured(tmp_path):
+    y = tmp_path / "m.yaml"
+    y.write_text("server:\n  db_path: '%s'\nbackup:\n  allow_pull: true\n  every_hours: 6\n  keep_daily: 3\n"
+                 % str(tmp_path / "notes.db").replace("\\", "/"), encoding="utf-8")
+    cfg = load_config(str(y))
+    assert cfg.backup.allow_pull is True and cfg.backup.every_hours == 6 and cfg.backup.keep_daily == 3
+    assert MarginConfig().backup.allow_pull is False, "off unless someone turns it on"
+
+
+def test_off_and_no_restore_or_delete(tmp_path):
+    with _client(tmp_path, enabled=False) as c:
+        assert c.get("/stores").status_code == 404
+    with _client(tmp_path) as c:
+        sid = c.post("/stores/snapshot").json()["snapshot"]["id"]
+        for path in ("/stores/restore", f"/stores/snapshots/{sid}"):
+            assert c.post(path).status_code in (404, 405) and c.delete(path).status_code in (404, 405)

seren_margin-2.2.0/seren_margin.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.2.0",
-  "distance": 0,
-  "node": "g77bceb68b538cab8ef07fa4d356711b2d2181733",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-09-30"
-}