clsplusplus 7.3.2__tar.gz → 7.4.0__tar.gz

{clsplusplus-7.3.2 → clsplusplus-7.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clsplusplus
-Version: 7.3.2
+Version: 7.4.0
 Summary: Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama.
 Author-email: AlphaForge AI Labs <contact@alphaforge.ai>
 Maintainer-email: Rajamohan Jabbala <contact@alphaforge.ai>

{clsplusplus-7.3.2 → clsplusplus-7.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clsplusplus"
-version = "7.3.2"
+version = "7.4.0"
 description = "Brain-inspired, model-agnostic persistent memory for LLMs. Learn, recall, forget — like a brain. Works with OpenAI, Claude, Gemini, Llama."
 readme = "README.md"
 requires-python = ">=3.9"

{clsplusplus-7.3.2 → clsplusplus-7.4.0}/src/clsplusplus/api.py

@@ -1248,12 +1248,21 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
                 "error": "Add CLS_REDIS_URL and CLS_DATABASE_URL in Render Dashboard.",
             }
         wm = write_metrics.snapshot()
+        wal = None
+        _dl = getattr(memory_service, "_durable_log", None)
+        if _dl is not None:
+            wal = {
+                "pending_reconcile": _dl.pending_reconcile(),
+                "appended": _dl.appended,
+                "sinks": {s.name: {"healthy": s.healthy, "lag": s.lag} for s in _dl.states()},
+            }
         return HealthResponse(
             status=h["status"],
             stores=stores,
             writes=wm["total_writes"],
             degraded_writes=wm["degraded_writes"],
             degraded_write_rate=wm["degraded_write_rate"],
+            wal=wal,
         )
 
     @app.get("/v1/health/score", response_model=HealthResponse)
@@ -1619,6 +1628,14 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
                 )
             logger.error("Login error: %s: %s", type(e).__name__, e)
             raise HTTPException(status_code=500, detail="Login service unavailable")
+        # Real login telemetry for the admin activity dashboard (best-effort).
+        from clsplusplus.login_activity import record_login
+        await record_login(
+            settings,
+            user_id=user.get("id"),
+            email=user.get("email"),
+            method="password",
+        )
         response = JSONResponse(content=user)
         return _set_session_cookie(response, token)
 
@@ -1806,6 +1823,13 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
         _target = (settings.frontend_url.rstrip("/") + _safe_redirect) if settings.frontend_url else _safe_redirect
         response = RedirectResponse(_target)
         _set_session_cookie(response, token)
+        from clsplusplus.login_activity import record_login
+        await record_login(
+            settings,
+            user_id=user.get("id"),
+            email=user.get("email"),
+            method="google",
+        )
         return response
 
     # ------------------------------------------------------------------
@@ -1927,6 +1951,13 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
         _target = (settings.frontend_url.rstrip("/") + safe_redirect) if settings.frontend_url else safe_redirect
         response = RedirectResponse(_target)
         _set_session_cookie(response, token)
+        from clsplusplus.login_activity import record_login
+        await record_login(
+            settings,
+            user_id=user.get("id"),
+            email=user.get("email"),
+            method="github",
+        )
         return response
 
     # =========================================================================
@@ -2687,6 +2718,344 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
                 "error": "integration data degraded",
             }
 
+    @app.get("/admin/integrations/activity")
+    async def admin_integrations_activity(request: Request):
+        """Real per-integration ACTIVITY for the admin dashboard.
+
+        Every metric is computed from a real backing store; nothing is
+        fabricated. A source with no attributable data returns null fields and
+        an honest telemetry classification ("partial" or "none") rather than a
+        made-up number. The handler is fully resilient — each backing store is
+        isolated and any failure degrades that section to null/empty instead of
+        returning 500.
+
+        Telemetry honesty contract per integration:
+          - "tracked": the integration writes a dedicated L1 `source` (the
+            framework adapters: crewai/langgraph/llamaindex/autogen) or has its
+            own Redis counters (chrome-extension) or its own table (api-key).
+          - "partial": the integration shares the generic `source="mcp"` bucket
+            so volume is real but NOT separable per-integration
+            (claude-remote-mcp, codex, cursor, n8n).
+          - "none": no attributable signal exists for it yet.
+        """
+        _require_admin(request)
+
+        from datetime import timezone as _tz
+        now = datetime.now(_tz.utc)
+        _empty_window = {
+            "active_users_24h": 0, "active_users_7d": 0, "logins_24h": 0,
+            "total_memories": 0, "writes_24h": 0, "reads_24h": 0,
+            "api_error_rate_60m": 0.0,
+        }
+
+        def _iso(dt) -> Optional[str]:
+            if dt is None:
+                return None
+            try:
+                return dt.isoformat()
+            except Exception:
+                return None
+
+        # --- Static catalogue: ids/names MUST match the frontend dashboard. ---
+        # `bucket` says where this integration's REAL write volume comes from.
+        #   "adapter:<source>"  -> dedicated L1 source     -> telemetry tracked
+        #   "mcp"               -> shared mcp source bucket -> telemetry partial
+        #   "ext"               -> chrome-ext redis counters-> telemetry tracked
+        #   "api"               -> api_credentials table    -> telemetry tracked
+        #   None                -> nothing attributable      -> telemetry none
+        catalogue = [
+            {"id": "claude-remote-mcp", "name": "Claude (Remote MCP)", "category": "mcp", "bucket": "mcp"},
+            {"id": "codex", "name": "Codex", "category": "mcp", "bucket": "mcp"},
+            {"id": "cursor", "name": "Cursor", "category": "mcp", "bucket": "mcp"},
+            {"id": "n8n", "name": "n8n", "category": "mcp", "bucket": "mcp"},
+            {"id": "crewai", "name": "CrewAI", "category": "framework", "bucket": "adapter:crewai"},
+            {"id": "langgraph", "name": "LangGraph", "category": "framework", "bucket": "adapter:langgraph"},
+            {"id": "llamaindex", "name": "LlamaIndex", "category": "framework", "bucket": "adapter:llamaindex"},
+            {"id": "autogen", "name": "AutoGen", "category": "framework", "bucket": "adapter:autogen"},
+            {"id": "chrome-extension", "name": "Chrome Extension", "category": "browser", "bucket": "ext"},
+            {"id": "api-key", "name": "API Key", "category": "api", "bucket": "api"},
+        ]
+
+        # --- Source 1: L1 writes grouped by source (real attribution). ------
+        by_source: dict[str, dict] = {}
+        recent_l1_writes: list[dict] = []
+        total_memories: Optional[int] = None
+        try:
+            rows = await memory_service.l1.writes_by_source(since_days=7)
+            by_source = {r["source"]: r for r in rows}
+        except Exception as e:
+            logger.warning("activity: l1 writes_by_source failed: %s", e)
+        try:
+            recent_l1_writes = await memory_service.l1.recent_writes(limit=20)
+        except Exception as e:
+            logger.warning("activity: l1 recent_writes failed: %s", e)
+        try:
+            total_memories = await memory_service.l1.count_all()
+        except Exception as e:
+            logger.warning("activity: l1 count_all failed: %s", e)
+
+        # --- Source 2: chrome-extension Redis analytics. --------------------
+        ext_analytics: dict = {}
+        try:
+            ext_analytics = await _metrics.get_extension_analytics()
+        except Exception as e:
+            logger.warning("activity: extension analytics failed: %s", e)
+
+        # --- Source 3: api-key usage from api_credentials. -----------------
+        api_activity: dict = {}
+        try:
+            api_activity = await _integration_store.api_key_activity(since_days=7)
+        except Exception as e:
+            logger.warning("activity: api_key_activity failed: %s", e)
+
+        # --- Source 4: aggregate usage + active counts (Redis metrics). -----
+        agg: dict = {}
+        active_now = 0
+        dau = 0
+        try:
+            agg = await _metrics.get_aggregate_metrics()
+        except Exception as e:
+            logger.warning("activity: aggregate metrics failed: %s", e)
+        try:
+            active_now = await _metrics.get_active_now(window_seconds=86400)
+        except Exception:
+            active_now = 0
+        try:
+            dau = await _metrics.get_dau()
+        except Exception:
+            dau = 0
+        active_7d = 0
+        try:
+            from datetime import timedelta as _td
+            from clsplusplus.metrics import _redis_client as _mredis
+            client = _mredis(settings.redis_url)
+            seen = set()
+            for d in range(7):
+                day = (now - _td(days=d)).strftime("%Y-%m-%d")
+                try:
+                    members = await client.smembers(f"cls:dau:global:{day}")
+                    seen.update(members or [])
+                except Exception:
+                    continue
+            active_7d = len(seen)
+        except Exception:
+            active_7d = 0
+
+        # --- Source 5: api error rate (health metrics, last 60m). ----------
+        api_error_rate_60m = 0.0
+        try:
+            from clsplusplus.health_metrics import aggregate_health
+            health = await aggregate_health(settings.redis_url, 60)
+            api_error_rate_60m = float(health.get("error_rate") or 0.0)
+        except Exception as e:
+            logger.warning("activity: health aggregate failed: %s", e)
+
+        # --- Source 6: login activity (new instrumentation). ---------------
+        logins_24h = 0
+        recent_logins: list[dict] = []
+        try:
+            from clsplusplus.login_activity import logins_since, recent_logins as _recent_logins
+            logins_24h = await logins_since(settings, 86400)
+            recent_logins = await _recent_logins(settings, limit=20)
+        except Exception as e:
+            logger.warning("activity: login activity failed: %s", e)
+
+        # --- Build per-integration rows honestly. --------------------------
+        # The shared "mcp" bucket covers all four MCP clients at once, so its
+        # write volume cannot be split between them — mark each "partial" and
+        # surface the SHARED bucket totals (clearly partial, not per-client).
+        mcp_bucket = by_source.get("mcp")
+
+        def _health_from(writes, reads, last_at) -> str:
+            if writes is None and reads is None:
+                return "no_data"
+            if (writes or 0) > 0 or (reads or 0) > 0:
+                return "healthy"
+            return "degraded"
+
+        integrations_out = []
+        for c in catalogue:
+            bucket = c["bucket"]
+            telemetry = "none"
+            unique_users = writes = reads = None
+            last_activity = None
+            error_rate = None
+
+            if bucket and bucket.startswith("adapter:"):
+                src = bucket.split(":", 1)[1]
+                row = by_source.get(src)
+                if row:
+                    telemetry = "tracked"
+                    writes = row["writes"]
+                    unique_users = row["unique_namespaces"]
+                    reads = None  # reads are not attributed per-source in L1
+                    last_activity = _iso(row["last_at"])
+                else:
+                    telemetry = "tracked"  # we DO track this source; just no rows
+            elif bucket == "mcp":
+                # Shared bucket — real volume, but not separable per client.
+                telemetry = "partial"
+                if mcp_bucket:
+                    writes = mcp_bucket["writes"]
+                    unique_users = mcp_bucket["unique_namespaces"]
+                    last_activity = _iso(mcp_bucket["last_at"])
+            elif bucket == "ext":
+                telemetry = "tracked"
+                wau = ext_analytics.get("wau")
+                msgs = ext_analytics.get("messages_captured") or {}
+                if ext_analytics:
+                    unique_users = int(wau) if wau is not None else None
+                    # Captured messages are the extension's real write signal.
+                    writes = sum(int(v) for v in msgs.values()) if msgs else 0
+                    sites = ext_analytics.get("site_usage") or {}
+                    reads = sum(int(v) for v in sites.values()) if sites else 0
+            elif bucket == "api":
+                telemetry = "tracked"
+                if api_activity:
+                    unique_users = api_activity.get("active_integrations")
+                    last_activity = _iso(api_activity.get("last_used_at"))
+
+            health = _health_from(writes, reads, last_activity)
+            if telemetry == "none":
+                health = "no_data"
+
+            integrations_out.append({
+                "id": c["id"],
+                "name": c["name"],
+                "category": c["category"],
+                "telemetry": telemetry,
+                "unique_users_7d": unique_users,
+                "writes_7d": writes,
+                "reads_7d": reads,
+                "last_activity": last_activity,
+                "health": health,
+                "error_rate": error_rate,
+            })
+
+        # --- Totals. -------------------------------------------------------
+        totals = {
+            "active_users_24h": int(active_now or dau or 0),
+            "active_users_7d": int(active_7d or 0),
+            "logins_24h": int(logins_24h or 0),
+            "total_memories": int(total_memories) if total_memories is not None else 0,
+            "writes_24h": int(agg.get("write", 0) or 0),
+            "reads_24h": int(agg.get("read", 0) or 0),
+            "api_error_rate_60m": round(float(api_error_rate_60m), 2),
+        }
+
+        # --- Issues: feedback + frustrated pulse (+ best-effort github). ----
+        issues_recent: list[dict] = []
+        try:
+            fb_rows = await user_service.store.get_recent_feedback(limit=15)
+            for f in fb_rows:
+                score = f.get("score") or 0
+                sentiment = f.get("sentiment")
+                if sentiment == "down" or score <= 2:
+                    severity = "high"
+                elif score == 3:
+                    severity = "med"
+                else:
+                    severity = "low"
+                issues_recent.append({
+                    "kind": "feedback",
+                    "title": (f.get("comment") or f.get("context") or "Feedback").strip()[:120],
+                    "who": f.get("email"),
+                    "severity": severity,
+                    "at": f.get("created_at"),
+                    "url": None,
+                })
+        except Exception as e:
+            logger.warning("activity: recent feedback failed: %s", e)
+
+        try:
+            from clsplusplus.user_pulse import list_frustrated_users
+            frustrated = await list_frustrated_users(settings, limit=10)
+            for p in frustrated:
+                issues_recent.append({
+                    "kind": "pulse",
+                    "title": "User frustration detected",
+                    "who": p.get("user_id"),
+                    "severity": "high" if p.get("score", 0) >= 75 else "med",
+                    "at": _iso(now),
+                    "url": None,
+                })
+        except Exception as e:
+            logger.warning("activity: pulse failed: %s", e)
+
+        # Best-effort open GitHub bug count (skip silently when no token).
+        open_issues = len([i for i in issues_recent if i["severity"] == "high"])
+        try:
+            gh_token = getattr(settings, "github_issue_token", "")
+            gh_repo = getattr(settings, "github_issue_repo", "")
+            if gh_token and gh_repo:
+                import httpx as _httpx
+                async with _httpx.AsyncClient(timeout=5.0) as _c:
+                    r = await _c.get(
+                        f"https://api.github.com/repos/{gh_repo}/issues",
+                        params={"state": "open", "labels": "bug", "per_page": 5},
+                        headers={
+                            "Authorization": f"Bearer {gh_token}",
+                            "Accept": "application/vnd.github+json",
+                        },
+                    )
+                    if r.status_code == 200:
+                        for gi in r.json()[:5]:
+                            issues_recent.append({
+                                "kind": "github",
+                                "title": (gi.get("title") or "")[:120],
+                                "who": (gi.get("user") or {}).get("login"),
+                                "severity": "high",
+                                "at": gi.get("created_at"),
+                                "url": gi.get("html_url"),
+                            })
+        except Exception as e:
+            logger.warning("activity: github issues probe failed: %s", e)
+
+        issues_recent = issues_recent[:15]
+        issues = {"open": open_issues, "recent": issues_recent}
+
+        # --- Activity feed: recent logins + recent memory writes. ----------
+        activity: list[tuple] = []
+        for lg in recent_logins:
+            activity.append((
+                lg.get("ts", 0),
+                {
+                    "at": lg.get("at"),
+                    "user": lg.get("email") or lg.get("user_id"),
+                    "integration": None,
+                    "action": "login",
+                },
+            ))
+        for w in recent_l1_writes:
+            at_iso = _iso(w.get("at"))
+            ts = 0
+            try:
+                ts = int(w["at"].timestamp()) if w.get("at") else 0
+            except Exception:
+                ts = 0
+            src = w.get("source")
+            integ = src if src and src != "user" else None
+            activity.append((
+                ts,
+                {
+                    "at": at_iso,
+                    "user": w.get("namespace"),
+                    "integration": integ,
+                    "action": "write",
+                },
+            ))
+        activity.sort(key=lambda t: t[0], reverse=True)
+        activity_out = [a[1] for a in activity[:20]]
+
+        return {
+            "generated_at": _iso(now),
+            "window": "7d",
+            "totals": totals,
+            "integrations": integrations_out,
+            "issues": issues,
+            "activity": activity_out,
+        }
+
     def _require_admin(request: Request):
         """Helper to enforce admin access on endpoints."""
         if not getattr(request.state, "is_admin", False):
@@ -4017,6 +4386,17 @@ def create_app(settings: Optional[Settings] = None) -> FastAPI:
         # ── 1. Warm up all persisted namespaces from L1 ────────────────────
         await memory_service.startup_preload()
 
+        # ── 1b. Start the durable WAL (file fsync anchor + Postgres/Redis ──
+        #        replicas). With it active, writes ack only after fsync and are
+        #        replicated off the hot path; on restart, replay re-ships any
+        #        records past the durable checkpoint. No-op if CLS_WAL_ENABLED
+        #        is false. Redis client attaches when available.
+        try:
+            _wal_redis = getattr(memory_service, "_redis_client", None) or getattr(app.state, "redis", None)
+            memory_service.init_durable_log(redis_client=_wal_redis)
+        except Exception as e:
+            _api_logger.error("Durable WAL startup failed: %s", e)
+
         # ── 2. Periodic hippocampal replay (consolidation / sleep cycle) ───
         async def _periodic_replay():
             while True:

{clsplusplus-7.3.2 → clsplusplus-7.4.0}/src/clsplusplus/config.py

@@ -150,6 +150,19 @@ class Settings(BaseSettings):
     # current write behavior is unchanged.
     belief_revision_on_write: bool = False  # CLS_BELIEF_REVISION_ON_WRITE
 
+    # ---- Durable write-ahead log (WAL) --------------------------------------
+    # Durability contract: a write is acked ONLY after it is fsync'd to the
+    # local WAL. Redis + Postgres are async replicas fed from the WAL; if either
+    # is unreachable the record is already durable on disk and the background
+    # reconciler retries until both confirm, then the record is checkpointed.
+    wal_enabled: bool = True                    # CLS_WAL_ENABLED
+    wal_dir: str = "./cls_wal"                  # CLS_WAL_DIR (mount a persistent disk here in prod)
+    wal_fsync: str = "always"                   # CLS_WAL_FSYNC: "always" (zero-loss) | "everysec"
+    wal_segment_max_bytes: int = 64 * 1024 * 1024   # CLS_WAL_SEGMENT_MAX_BYTES (rotate at 64MB)
+    wal_redis_stream: str = "cls:wal"          # CLS_WAL_REDIS_STREAM
+    wal_reconcile_interval_seconds: float = 1.0     # CLS_WAL_RECONCILE_INTERVAL_SECONDS
+    wal_reconcile_batch: int = 256             # CLS_WAL_RECONCILE_BATCH
+
     # Working buffer
     l0_capacity_tokens: int = 4096
     l0_ttl_seconds: int = 300

clsplusplus-7.4.0/src/clsplusplus/durable_log/__init__.py

@@ -0,0 +1,21 @@
+"""Durable write-ahead log for CLS++.
+
+Durability contract: a memory write is acknowledged ONLY after its record has
+been fsync'd to the local WAL. Redis and Postgres are asynchronous replicas fed
+from the WAL — if either is unreachable the record is already durable on disk and
+the background reconciler retries replication until both confirm, after which the
+record is checkpointed and its segment can be truncated.
+
+Components:
+  - WalRecord            the serialized unit of durability (length-prefixed + CRC32)
+  - FileWal              append + fsync, segmented, crash-safe replay, checkpoint
+  - Replica (protocol)   an async sink (Redis stream, Postgres outbox) fed from the WAL
+  - DurableLog           orchestrator: hot-path append/ack + concurrent replication
+                         + background reconciler + startup replay
+"""
+
+from clsplusplus.durable_log.record import WalRecord
+from clsplusplus.durable_log.file_wal import FileWal
+from clsplusplus.durable_log.manager import DurableLog, Replica, ReplicaState
+
+__all__ = ["WalRecord", "FileWal", "DurableLog", "Replica", "ReplicaState"]

clsplusplus-7.4.0/src/clsplusplus/durable_log/file_wal.py

@@ -0,0 +1,181 @@
+"""Local file write-ahead log — the durability anchor.
+
+A write is durable the instant ``append()`` returns with ``fsync="always"``:
+the framed record is written and ``os.fsync`` forces it to stable storage before
+we ack the caller. Segments rotate at a size cap; a monotonic ``seq`` fixes apply
+order; a checkpoint records the highest seq confirmed by all replicas so fully
+drained segments can be deleted.
+
+This file knows nothing about Redis or Postgres — it is the on-disk source of
+truth they replicate from.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Iterator, Optional
+
+from clsplusplus.durable_log.record import WalRecord, iter_frames
+
+_SEG_PREFIX = "wal-"
+_SEG_SUFFIX = ".log"
+_CHECKPOINT = "checkpoint"
+
+
+def _seg_name(start_seq: int) -> str:
+    return f"{_SEG_PREFIX}{start_seq:020d}{_SEG_SUFFIX}"
+
+
+def _seg_start(name: str) -> int:
+    return int(name[len(_SEG_PREFIX): -len(_SEG_SUFFIX)])
+
+
+class FileWal:
+    def __init__(self, directory: str, *, fsync: str = "always",
+                 segment_max_bytes: int = 64 * 1024 * 1024):
+        self.dir = directory
+        self.fsync_mode = fsync
+        self.segment_max_bytes = segment_max_bytes
+        self._lock = threading.Lock()
+        self._fh = None                       # current segment file handle (ab)
+        self._cur_start = 0                    # start seq of current segment
+        self._cur_bytes = 0
+        self._next_seq = 1
+        self._last_fsync = 0.0
+        os.makedirs(self.dir, exist_ok=True)
+        self._open_tail()
+
+    # -- lifecycle ----------------------------------------------------------
+    def _segments(self) -> list[str]:
+        names = [f for f in os.listdir(self.dir)
+                 if f.startswith(_SEG_PREFIX) and f.endswith(_SEG_SUFFIX)]
+        return sorted(names, key=_seg_start)
+
+    def _open_tail(self) -> None:
+        segs = self._segments()
+        if not segs:
+            self._cur_start = 1
+            self._next_seq = 1
+            path = os.path.join(self.dir, _seg_name(self._cur_start))
+            self._fh = open(path, "ab", buffering=0)
+            self._cur_bytes = 0
+            return
+        # Resume the last segment; recover next_seq by scanning intact frames.
+        last = segs[-1]
+        self._cur_start = _seg_start(last)
+        path = os.path.join(self.dir, last)
+        with open(path, "rb") as f:
+            buf = f.read()
+        max_seq = self._cur_start - 1
+        good_bytes = 0
+        for rec, size in iter_frames(buf):
+            max_seq = rec.seq
+            good_bytes += size
+        # Truncate any torn tail so future appends are frame-aligned.
+        if good_bytes != len(buf):
+            with open(path, "r+b") as f:
+                f.truncate(good_bytes)
+        self._next_seq = max_seq + 1
+        self._cur_bytes = good_bytes
+        self._fh = open(path, "ab", buffering=0)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._fh is not None:
+                self._fh.flush()
+                os.fsync(self._fh.fileno())
+                self._fh.close()
+                self._fh = None
+
+    # -- append (the ack gate) ---------------------------------------------
+    def append(self, record: WalRecord) -> WalRecord:
+        """Assign seq, frame, write, and fsync. Returns the stamped record.
+
+        When this returns under fsync="always", the record is on stable storage.
+        Blocking; callers on the event loop should use ``asyncio.to_thread``.
+        """
+        with self._lock:
+            record.seq = self._next_seq
+            frame = record.encode()
+            if self._cur_bytes and self._cur_bytes + len(frame) > self.segment_max_bytes:
+                self._rotate()
+            self._fh.write(frame)
+            self._cur_bytes += len(frame)
+            self._next_seq += 1
+            self._maybe_fsync()
+            return record
+
+    def _rotate(self) -> None:
+        self._fh.flush()
+        os.fsync(self._fh.fileno())
+        self._fh.close()
+        self._cur_start = self._next_seq
+        path = os.path.join(self.dir, _seg_name(self._cur_start))
+        self._fh = open(path, "ab", buffering=0)
+        self._cur_bytes = 0
+
+    def _maybe_fsync(self) -> None:
+        if self.fsync_mode == "always":
+            self._fh.flush()
+            os.fsync(self._fh.fileno())
+            return
+        # "everysec": flush now, fsync at most once per second.
+        self._fh.flush()
+        now = time.time()
+        if now - self._last_fsync >= 1.0:
+            os.fsync(self._fh.fileno())
+            self._last_fsync = now
+
+    # -- replay -------------------------------------------------------------
+    def read_from(self, after_seq: int = 0) -> Iterator[WalRecord]:
+        """Yield every intact record with seq > after_seq, in seq order."""
+        for name in self._segments():
+            path = os.path.join(self.dir, name)
+            with open(path, "rb") as f:
+                buf = f.read()
+            for rec, _ in iter_frames(buf):
+                if rec.seq > after_seq:
+                    yield rec
+
+    @property
+    def next_seq(self) -> int:
+        return self._next_seq
+
+    # -- checkpoint / truncation -------------------------------------------
+    def read_checkpoint(self) -> int:
+        path = os.path.join(self.dir, _CHECKPOINT)
+        try:
+            with open(path, "r") as f:
+                return int(f.read().strip() or "0")
+        except (FileNotFoundError, ValueError):
+            return 0
+
+    def checkpoint(self, confirmed_seq: int) -> None:
+        """Persist the highest seq confirmed by ALL replicas, then delete any
+        segment whose records are entirely <= confirmed_seq (keep the tail).
+        """
+        with self._lock:
+            path = os.path.join(self.dir, _CHECKPOINT)
+            tmp = path + ".tmp"
+            with open(tmp, "w") as f:
+                f.write(str(confirmed_seq))
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, path)
+            self._truncate_below(confirmed_seq)
+
+    def _truncate_below(self, confirmed_seq: int) -> None:
+        segs = self._segments()
+        # A segment is fully drained if the NEXT segment starts at or below
+        # confirmed_seq+1. Never delete the current (tail) segment.
+        for i in range(len(segs) - 1):
+            nxt_start = _seg_start(segs[i + 1])
+            if nxt_start <= confirmed_seq + 1:
+                try:
+                    os.remove(os.path.join(self.dir, segs[i]))
+                except FileNotFoundError:
+                    pass
+            else:
+                break