compartment 2.3__tar.gz → 3.1__tar.gz

{compartment-2.3 → compartment-3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compartment
-Version: 2.3
+Version: 3.1
 Summary: Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)
 Project-URL: Homepage, https://github.com/MaxFreedomPollard/Compartment
 Project-URL: Source, https://github.com/MaxFreedomPollard/Compartment
@@ -33,13 +33,13 @@ Requires-Dist: onnxruntime>=1.17
 Requires-Dist: tokenizers>=0.15
 Requires-Dist: numpy>=1.26
 Requires-Dist: mcp>=1.0
+Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin"
+Requires-Dist: pystray>=0.19; sys_platform == "win32"
+Requires-Dist: pillow>=10; sys_platform == "win32"
 Provides-Extra: hnsw
 Requires-Dist: usearch>=2.9; extra == "hnsw"
 Provides-Extra: menubar
-Requires-Dist: pyobjc-framework-Cocoa>=10.0; sys_platform == "darwin" and extra == "menubar"
 Provides-Extra: tray
-Requires-Dist: pystray>=0.19; sys_platform == "win32" and extra == "tray"
-Requires-Dist: pillow>=10; sys_platform == "win32" and extra == "tray"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: usearch>=2.9; extra == "dev"
@@ -51,7 +51,7 @@ Requires-Dist: usearch>=2.9; extra == "dev"
 Your AI agent forgets you the moment the session ends. Compartment ends
 that. With Compartment, your AI agent gets better with experience: it keeps
 every decision, preference and detail you give it, permanently, encrypted,
-on your own computer. Hermes, Claude,  OpenClaw and other AI Agents can
+on your own computer. Hermes, Claude, OpenClaw and other AI Agents can
 install in one command. One fully-transferable memory store is shared
 simultaneously by all agents on the computer. 100% offline: no network, no
 API key, no cloud account, no telemetry. The embedding model ships inside
@@ -181,7 +181,7 @@ own - Claude Code keeps per-project Markdown files with an auto-loaded
 index. Two memories means facts land in whichever one the model happened to
 think of, and neither is complete. Compartment takes over on install: it imports
 what the file memory already holds, and both the MCP handshake and the
-managed CLAUDE.md block tell the model that compartment supersedes it - write
+managed CLAUDE.md block tell the model that Compartment supersedes it - write
 every new memory here, treat the files as a read-only archive. One vault,
 encrypted, shared by every agent and project on the machine. Nothing is
 deleted; the files stay exactly where they were.
@@ -190,7 +190,7 @@ deleted; the files stay exactly where they were.
 and a host that declares its own memory in its system prompt outranks
 anything a tool says. So `compartment integrate claude` also installs a
 `PostToolUse` hook: when Claude Code writes a memory file, the fact lands in
-the vault whether or not the model ever thought about compartment. The hook is
+the vault whether or not the model ever thought about Compartment. The hook is
 additive and idempotent (your other hooks are untouched, settings.json is
 backed up first), it exits successfully no matter what - a memory tool must
 never break your editor - and it stays quiet when the vault is locked.
@@ -203,14 +203,15 @@ never break your editor - and it stays quiet when the vault is locked.
        alt="The Compartment panel in the Windows notification area.">
 </p>
 
-**A menu bar and system tray app.** Download **Compartment.pkg** from the
-[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest)
-and open it - the installer asks whether you also want the menu bar utility,
-and everything (Python included) is self-contained, so there is nothing to
-install first. From a checkout, `pip install 'compartment[menubar]'`
-then `compartment menubar` does the same thing; on Windows,
-`pip install 'compartment[tray]'` then `compartment tray`. Either way it puts
-Compartment in the status bar: click the icon and a
+**A menu bar and system tray app, from the same one install.** `pip install
+compartment && compartment init` sets it up on macOS and on Windows: the app
+starts straight away and comes back at every login. There is no separate
+package, no extra to remember and no second command. On the Mac you can
+instead open **Compartment.pkg** from the
+[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest),
+which carries Python and every dependency inside it, so there is nothing to
+install first. `compartment init --no-app` skips the app for headless boxes
+and CI. Either way it puts Compartment in the status bar: click the icon and a
 panel shows whether the vault is open, how much it has learned, the three
 settings worth changing day to day (capture hook, whether starter facts join
 searches, auto-lock), and the last five things it remembered. Unlock, lock and
@@ -327,7 +328,7 @@ and `compartment bench`.
 | Peak RSS, model + vault + index resident | 319 MB |
 | Store one memory (embed + encrypt + fsync journal) | ~40 ms |
 | Wheel size, model included | ~30 MB |
-| Test suite (crypto, tamper, crash, offline, concurrency, 2FA, graph, dash) | 199 tests, ~60 s |
+| Test suite (crypto, tamper, crash, offline, concurrency, 2FA, graph, dash) | 249 tests, ~60 s |
 
 A single network round-trip to a cloud memory API costs more than this
 entire pipeline. The property that makes Compartment secure (no plaintext
@@ -397,10 +398,12 @@ The default unlock mode is convenience, not a cage: after a normal
 unlock, the vault stays usable across processes, logouts, and logins -
 for weeks or months if you leave it that way - until the next restart or
 power loss, or until you lock it yourself. Restart/power loss always
-locks it: the stored credential is the master key wrapped by a key
-derived from the kernel's boot timestamp plus the stable machine id; a
-new boot can never open the old wrap. That is arithmetic, not a policy
-check.
+locks it: the stored credential is the master key wrapped under a random
+32-byte per-boot secret, held in a volatile kernel object that is never
+written to any filesystem, so a restart destroys it and a new boot can
+never open the old wrap. A copy of the credential file on its own is
+useless, because the key it needs was never on the disk. That is
+arithmetic, not a policy check.
 
 If you prefer reboot-surviving unlock on macOS, that is an explicit
 opt-in (`compartment unlock --keychain`), with the tradeoff documented. At any

{compartment-2.3 → compartment-3.1}/README.md

@@ -5,7 +5,7 @@
 Your AI agent forgets you the moment the session ends. Compartment ends
 that. With Compartment, your AI agent gets better with experience: it keeps
 every decision, preference and detail you give it, permanently, encrypted,
-on your own computer. Hermes, Claude,  OpenClaw and other AI Agents can
+on your own computer. Hermes, Claude, OpenClaw and other AI Agents can
 install in one command. One fully-transferable memory store is shared
 simultaneously by all agents on the computer. 100% offline: no network, no
 API key, no cloud account, no telemetry. The embedding model ships inside
@@ -135,7 +135,7 @@ own - Claude Code keeps per-project Markdown files with an auto-loaded
 index. Two memories means facts land in whichever one the model happened to
 think of, and neither is complete. Compartment takes over on install: it imports
 what the file memory already holds, and both the MCP handshake and the
-managed CLAUDE.md block tell the model that compartment supersedes it - write
+managed CLAUDE.md block tell the model that Compartment supersedes it - write
 every new memory here, treat the files as a read-only archive. One vault,
 encrypted, shared by every agent and project on the machine. Nothing is
 deleted; the files stay exactly where they were.
@@ -144,7 +144,7 @@ deleted; the files stay exactly where they were.
 and a host that declares its own memory in its system prompt outranks
 anything a tool says. So `compartment integrate claude` also installs a
 `PostToolUse` hook: when Claude Code writes a memory file, the fact lands in
-the vault whether or not the model ever thought about compartment. The hook is
+the vault whether or not the model ever thought about Compartment. The hook is
 additive and idempotent (your other hooks are untouched, settings.json is
 backed up first), it exits successfully no matter what - a memory tool must
 never break your editor - and it stays quiet when the vault is locked.
@@ -157,14 +157,15 @@ never break your editor - and it stays quiet when the vault is locked.
        alt="The Compartment panel in the Windows notification area.">
 </p>
 
-**A menu bar and system tray app.** Download **Compartment.pkg** from the
-[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest)
-and open it - the installer asks whether you also want the menu bar utility,
-and everything (Python included) is self-contained, so there is nothing to
-install first. From a checkout, `pip install 'compartment[menubar]'`
-then `compartment menubar` does the same thing; on Windows,
-`pip install 'compartment[tray]'` then `compartment tray`. Either way it puts
-Compartment in the status bar: click the icon and a
+**A menu bar and system tray app, from the same one install.** `pip install
+compartment && compartment init` sets it up on macOS and on Windows: the app
+starts straight away and comes back at every login. There is no separate
+package, no extra to remember and no second command. On the Mac you can
+instead open **Compartment.pkg** from the
+[latest release](https://github.com/MaxFreedomPollard/Compartment/releases/latest),
+which carries Python and every dependency inside it, so there is nothing to
+install first. `compartment init --no-app` skips the app for headless boxes
+and CI. Either way it puts Compartment in the status bar: click the icon and a
 panel shows whether the vault is open, how much it has learned, the three
 settings worth changing day to day (capture hook, whether starter facts join
 searches, auto-lock), and the last five things it remembered. Unlock, lock and
@@ -281,7 +282,7 @@ and `compartment bench`.
 | Peak RSS, model + vault + index resident | 319 MB |
 | Store one memory (embed + encrypt + fsync journal) | ~40 ms |
 | Wheel size, model included | ~30 MB |
-| Test suite (crypto, tamper, crash, offline, concurrency, 2FA, graph, dash) | 199 tests, ~60 s |
+| Test suite (crypto, tamper, crash, offline, concurrency, 2FA, graph, dash) | 249 tests, ~60 s |
 
 A single network round-trip to a cloud memory API costs more than this
 entire pipeline. The property that makes Compartment secure (no plaintext
@@ -351,10 +352,12 @@ The default unlock mode is convenience, not a cage: after a normal
 unlock, the vault stays usable across processes, logouts, and logins -
 for weeks or months if you leave it that way - until the next restart or
 power loss, or until you lock it yourself. Restart/power loss always
-locks it: the stored credential is the master key wrapped by a key
-derived from the kernel's boot timestamp plus the stable machine id; a
-new boot can never open the old wrap. That is arithmetic, not a policy
-check.
+locks it: the stored credential is the master key wrapped under a random
+32-byte per-boot secret, held in a volatile kernel object that is never
+written to any filesystem, so a restart destroys it and a new boot can
+never open the old wrap. A copy of the credential file on its own is
+useless, because the key it needs was never on the disk. That is
+arithmetic, not a policy check.
 
 If you prefer reboot-surviving unlock on macOS, that is an explicit
 opt-in (`compartment unlock --keychain`), with the tradeoff documented. At any

{compartment-2.3 → compartment-3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "compartment"
-version = "2.3"
+version = "3.1"
 description = "Compartment - high-security, fully offline, encrypted vector memory for AI agents (MCP)"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -36,6 +36,16 @@ dependencies = [
     "tokenizers>=0.15",
     "numpy>=1.26",
     "mcp>=1.0",
+    # The status bar app ships with every install, on the platforms that have
+    # one. It is not an add-on: unlocking, locking and changing the passphrase
+    # are things people do through the icon, not through a terminal, so an
+    # install that only lays down a CLI is an incomplete install. The markers
+    # keep it honest - nothing macOS-only is fetched on Windows, nothing
+    # Windows-only on macOS, and Linux (which has no status bar app here)
+    # installs neither and compiles nothing.
+    "pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'",
+    "pystray>=0.19; sys_platform == 'win32'",
+    "pillow>=10; sys_platform == 'win32'",
 ]
 
 # PyPI is the repo's declared homepage, so it is a real front door - and
@@ -64,16 +74,12 @@ engram = "compartment.cli:main"
 # `pip install` compiles nothing and installs cleanly everywhere; large
 # corpora add it with `pip install compartment[hnsw]`.
 hnsw = ["usearch>=2.9"]
-# The macOS menu bar app. PyObjC is macOS-only and irrelevant to the CLI and
-# MCP server, so it stays out of the default install: `pip install
-# compartment[menubar]`, then `compartment menubar`.
-menubar = ["pyobjc-framework-Cocoa>=10.0; sys_platform == 'darwin'"]
-# The Windows tray app. tkinter draws the panel and comes with Python itself;
-# pystray owns the notification-area icon and is pure Python, so a Windows
-# install still compiles nothing: `pip install compartment[tray]`, then
-# `compartment tray`.
-tray = ["pystray>=0.19; sys_platform == 'win32'",
-        "pillow>=10; sys_platform == 'win32'"]
+# The status bar app is part of the base install now, so these two are kept
+# only so that an existing `pip install compartment[menubar]` or
+# `compartment[tray]` in someone's notes or script keeps resolving instead of
+# failing on an unknown extra. They add nothing.
+menubar = []
+tray = []
 dev = ["pytest>=8", "usearch>=2.9"]
 
 [tool.setuptools.packages.find]

{compartment-2.3 → compartment-3.1}/src/compartment/__init__.py

@@ -1,6 +1,6 @@
 """Compartment - high-security, fully offline, encrypted vector memory for AI agents."""
 
-__version__ = "2.3"
+__version__ = "3.1"
 
 from . import offline_guard as _og
 

compartment-3.1/src/compartment/acl.py

@@ -0,0 +1,140 @@
+"""Per-caller namespace access control + vault-adjacent settings.
+
+Config lives NEXT to the vault as `<vault>.config.json` (it contains no
+secrets - only ACLs and preferences). `packs/*` namespaces are ALWAYS
+read-only for every caller, including "*". Violations are hard errors.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+from dataclasses import dataclass, field
+
+from .crypto import CryptoError
+
+# The whole grant vocabulary. Anything outside it is not a grant at all, so it
+# denies both reads and writes rather than being waved through as "not rw".
+ALLOWED_GRANTS = ("rw", "ro", "none")
+PERMITTED_GRANTS = ("rw", "ro")
+
+DEFAULT_CONFIG = {
+    "callers": {
+        "*": {"default_namespace": "main", "grants": {"*": "rw"}},
+    },
+    "settings": {
+        "auto_lock_minutes": 30,
+        "include_packs_in_search": True,
+        "unlock_tool_enabled": False,
+        "duplicate_threshold": 0.97,
+        "index_precision": "f32",
+    },
+}
+
+
+class AclError(CryptoError):
+    pass
+
+
+@dataclass
+class VaultConfig:
+    # Deep copies: a shallow copy would hand every VaultConfig in the process
+    # the same inner grants dict, so editing one vault's ACLs would silently
+    # edit the module default and every other open vault.
+    callers: dict = field(
+        default_factory=lambda: copy.deepcopy(DEFAULT_CONFIG["callers"]))
+    settings: dict = field(
+        default_factory=lambda: copy.deepcopy(DEFAULT_CONFIG["settings"]))
+
+    @staticmethod
+    def path_for(vault_path: str) -> str:
+        return vault_path + ".config.json"
+
+    @classmethod
+    def load(cls, vault_path: str) -> "VaultConfig":
+        p = cls.path_for(vault_path)
+        if not os.path.exists(p):
+            return cls()
+        with open(p, encoding="utf-8") as f:
+            data = json.load(f)
+        cfg = cls()
+        cfg.callers = data.get("callers", cfg.callers)
+        cfg.settings = {**cfg.settings, **data.get("settings", {})}
+        return cfg
+
+    def save(self, vault_path: str) -> None:
+        with open(self.path_for(vault_path), "w", encoding="utf-8") as f:
+            json.dump({"callers": self.callers, "settings": self.settings}, f, indent=2)
+
+    # -- ACL ---------------------------------------------------------------
+
+    def _caller_entry(self, caller: str) -> dict:
+        # An entry that EXISTS is used as written, even when it is empty. Only
+        # a missing caller falls back to "*". Writing {"evil": {}} is how a
+        # caller gets locked down, so it must never inherit the wildcard.
+        if caller in self.callers:
+            entry = self.callers[caller]
+        else:
+            entry = self.callers.get("*")
+        if not isinstance(entry, dict):
+            raise AclError(f"Caller {caller!r} has no access to this vault")
+        return entry
+
+    def default_namespace(self, caller: str) -> str:
+        return self._caller_entry(caller).get("default_namespace", "main")
+
+    @staticmethod
+    def _match(grants: dict, namespace: str):
+        """The most specific grant for `namespace`, or None if nothing matches.
+
+        Specificity, not dict order, decides. An exact namespace key beats
+        every wildcard, and among wildcards the longest matching prefix wins,
+        so "secret/*" beats "*" and "a/b/*" beats "a/*". Note that "*" is
+        itself a wildcard whose prefix is empty: it is the weakest possible
+        match, never the first one taken.
+        """
+        if not isinstance(grants, dict):
+            return None
+        if namespace in grants:
+            return grants[namespace]
+        best_len = -1
+        best = None
+        for pattern, g in grants.items():
+            if not isinstance(pattern, str) or not pattern.endswith("*"):
+                continue
+            prefix = pattern[:-1]
+            if namespace.startswith(prefix) and len(prefix) > best_len:
+                best_len, best = len(prefix), g
+        return best
+
+    def grant_for(self, caller: str, namespace: str) -> str:
+        """Returns 'rw' or 'ro'. Anything else raises AclError.
+
+        'none' and any value outside the documented rw/ro/none vocabulary deny
+        the namespace outright - reads included. packs/* is always ro.
+        """
+        entry = self._caller_entry(caller)
+        grant = self._match(entry.get("grants", {}), namespace)
+        if grant is None:
+            raise AclError(
+                f"Caller {caller!r} is not granted access to namespace {namespace!r}")
+        if grant not in PERMITTED_GRANTS:
+            if grant in ALLOWED_GRANTS:                  # explicit "none"
+                raise AclError(
+                    f"Caller {caller!r} is denied access to namespace "
+                    f"{namespace!r}")
+            raise AclError(
+                f"Caller {caller!r} has an unrecognized grant {grant!r} for "
+                f"namespace {namespace!r}; expected one of "
+                f"{', '.join(ALLOWED_GRANTS)}")
+        if namespace.startswith("packs/"):
+            return "ro"  # pack namespaces are immutable for everyone
+        return grant
+
+    def check(self, caller: str, namespace: str, write: bool) -> None:
+        # grant_for already denies reads for 'none' and for unknown values, so
+        # this only has to police the read-only case on writes.
+        grant = self.grant_for(caller, namespace)
+        if write and grant != "rw":
+            raise AclError(
+                f"Caller {caller!r} has read-only access to namespace {namespace!r}")

compartment-3.1/src/compartment/audit.py

@@ -0,0 +1,223 @@
+"""Hash-chained, tamper-evident audit log (stored inside the sealed payload).
+
+Each entry's hash covers the previous entry's hash, so an edit or a reordering
+in the MIDDLE of the log breaks the chain at a detectable point.
+
+A forward-only chain cannot catch a truncation of its own tail: lop the last
+three entries off and what remains still verifies, just shorter. So the head
+and the length are anchored outside the chain, in the meta table, every time
+the vault is saved. verify() then requires the chain to EXTEND that anchor:
+fewer entries than were anchored, or a different hash at the anchored
+position, is reported as removal rather than passing as a clean shorter log.
+
+The anchor is written on save and is absent in vaults written by older
+builds. A missing anchor is not a failure - it is an unanchored log, reported
+as such, and the next save anchors it.
+
+A failure to write the audit entry fails the operation (fail-fast), never
+the other way around.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+
+GENESIS = "GENESIS"
+
+# meta keys holding the anchor. Additive: a vault without them predates
+# anchoring and still opens.
+ANCHOR_HEAD = "audit_anchor_head"
+ANCHOR_COUNT = "audit_anchor_count"
+RELINK_LOG = "audit_relink_log"
+
+
+def _meta_get(conn, k: str) -> str | None:
+    row = conn.execute("SELECT v FROM meta WHERE k = ?", (k,)).fetchone()
+    return row["v"] if row else None
+
+
+def _meta_set(conn, k: str, v: str) -> None:
+    conn.execute(
+        "INSERT INTO meta (k, v) VALUES (?, ?) "
+        "ON CONFLICT(k) DO UPDATE SET v = excluded.v", (k, v))
+
+
+def count(conn) -> int:
+    return conn.execute("SELECT COUNT(*) c FROM audit").fetchone()["c"]
+
+
+def anchor(conn) -> None:
+    """Pin the current head and length. Called on every save."""
+    _meta_set(conn, ANCHOR_HEAD, head(conn))
+    _meta_set(conn, ANCHOR_COUNT, str(count(conn)))
+
+
+def read_anchor(conn) -> tuple[str, int] | None:
+    """The pinned (head, count), or None for a vault written before anchoring."""
+    h = _meta_get(conn, ANCHOR_HEAD)
+    c = _meta_get(conn, ANCHOR_COUNT)
+    if h is None or c is None:
+        return None
+    try:
+        return h, int(c)
+    except ValueError:
+        return None
+
+
+def _entry_hash(prev_hash: str, ts: float, caller: str, op: str, detail: str) -> str:
+    body = json.dumps(
+        {"prev": prev_hash, "ts": ts, "caller": caller, "op": op, "detail": detail},
+        sort_keys=True, separators=(",", ":"),
+    ).encode()
+    return hashlib.sha256(body).hexdigest()
+
+
+def append(conn, caller: str, op: str, detail: str, ts: float | None = None) -> str:
+    """Add an entry, linked to whatever is currently at the head.
+
+    `ts` is only passed when replaying a journalled operation, so the entry
+    keeps the time it actually happened. It is still linked to the head as it
+    stands at replay time, never to the head the original writer saw: that
+    head may never have reached disk (read operations are audited in RAM and
+    persist only on save), and chaining to an entry nobody else has is what
+    leaves a dangling link no future verify can resolve."""
+    row = conn.execute("SELECT hash FROM audit ORDER BY seq DESC LIMIT 1").fetchone()
+    prev = row["hash"] if row else GENESIS
+    ts = time.time() if ts is None else ts
+    h = _entry_hash(prev, ts, caller, op, detail)
+    conn.execute(
+        "INSERT INTO audit (ts, caller, op, detail, prev_hash, hash) VALUES (?,?,?,?,?,?)",
+        (ts, caller, op, detail, prev, h),
+    )
+    return h
+
+
+def head(conn) -> str:
+    row = conn.execute("SELECT hash FROM audit ORDER BY seq DESC LIMIT 1").fetchone()
+    return row["hash"] if row else GENESIS
+
+
+def verify(conn) -> tuple[bool, int, str]:
+    """Walk the chain, then check it against the anchor.
+
+    Returns (ok, entries_checked, message). The walk catches edits and
+    reorderings; the anchor catches a truncated tail, which the walk alone
+    cannot see because a shortened chain is still internally consistent."""
+    prev = GENESIS
+    n = 0
+    hashes: list[str] = []
+    for row in conn.execute("SELECT * FROM audit ORDER BY seq"):
+        if row["prev_hash"] != prev:
+            return False, n, f"chain break at seq {row['seq']}: prev_hash mismatch"
+        want = _entry_hash(prev, row["ts"], row["caller"], row["op"], row["detail"])
+        if row["hash"] != want:
+            return False, n, f"chain break at seq {row['seq']}: entry hash mismatch"
+        prev = row["hash"]
+        hashes.append(prev)
+        n += 1
+
+    anc = read_anchor(conn)
+    if anc is None:
+        # Every vault is anchored at creation and re-anchored on every save.
+        # A missing anchor means the meta rows were removed, which is exactly
+        # the move someone makes to hide a truncation, so it is a failure and
+        # not a tolerated older shape.
+        return False, n, (
+            "audit log has no anchor. Every vault is anchored when it is "
+            "created and on every save, so an absent anchor means the meta "
+            "rows were removed. A truncated log cannot be detected without "
+            "it, so this is reported as tampering.")
+    a_head, a_count = anc
+    if n < a_count:
+        return False, n, (
+            f"audit log is SHORTER than its anchor: {n} entries present, "
+            f"{a_count} anchored at the last save. {a_count - n} entries were "
+            "removed from the end. A forward walk cannot see this, which is "
+            "why the length is pinned.")
+    if a_count == 0:
+        pinned_ok = True
+    else:
+        pinned_ok = len(hashes) >= a_count and hashes[a_count - 1] == a_head
+    if not pinned_ok:
+        return False, n, (
+            f"audit entry {a_count} does not match the anchored head: history "
+            "was rewritten at or before the last save, not merely appended to.")
+    return True, n, f"audit chain intact ({n} entries, anchored at {a_count})"
+
+
+def relink(conn) -> tuple[int, int | None]:
+    """Re-link entries whose prev_hash points at something not in the log.
+
+    Only for repairing damage done by builds before this one, which replayed a
+    journalled entry with the head its original writer saw rather than the head
+    the log actually has. The result was a permanent dangling link: verify
+    stopped at it and never reported anything after it again.
+
+    What this does NOT do is paper over an edit. Every entry's own hash covers
+    its content, so content tampering is caught by the self-hash check and this
+    refuses to touch a log that fails it. Only the links are rebuilt, and only
+    forward from the first break. Nothing is deleted, reordered or reworded:
+    ts, caller, op and detail are exactly what they were.
+
+    Returns (entries relinked, seq of the first break) - (0, None) if intact."""
+    rows = conn.execute("SELECT * FROM audit ORDER BY seq").fetchall()
+    for row in rows:
+        want = _entry_hash(row["prev_hash"], row["ts"], row["caller"], row["op"],
+                           row["detail"])
+        if row["hash"] != want:
+            raise ValueError(
+                f"audit entry seq {row['seq']} does not hash to its own content. "
+                "That is content tampering, not a dangling link, and relinking "
+                "would destroy the evidence. Refusing.")
+
+    # A dangling link is damage worth repairing. A missing entry is not: the
+    # self-hash check above passes for a log with rows deleted, because every
+    # surviving row still hashes to its own content, and relinking would then
+    # rewrite the chain around the hole and report it as intact. The anchor is
+    # the only thing that knows how long the log used to be.
+    anc = read_anchor(conn)
+    if anc is not None and len(rows) < anc[1]:
+        raise ValueError(
+            f"audit log has {len(rows)} entries but {anc[1]} were anchored at "
+            "the last save. Entries were deleted, not merely unlinked, and "
+            "relinking would rewrite the chain around the gap and call it "
+            "intact. Refusing.")
+
+    prev, first, changed = GENESIS, None, 0
+    for row in rows:
+        if row["prev_hash"] != prev:
+            if first is None:
+                first = row["seq"]
+        if first is not None:                    # rewrite everything after it
+            h = _entry_hash(prev, row["ts"], row["caller"], row["op"], row["detail"])
+            conn.execute("UPDATE audit SET prev_hash = ?, hash = ? WHERE seq = ?",
+                         (prev, h, row["seq"]))
+            changed += 1
+            prev = h
+        else:
+            prev = row["hash"]
+
+    if changed:
+        # Leave a permanent, non-erasable record that the chain was rebuilt.
+        # It goes in meta rather than in the log itself: appending an entry
+        # would change the log's length, and the repair must not look like
+        # ordinary activity. Anyone auditing later can see that a repair
+        # happened, when, where it started, and what the head was before.
+        try:
+            prior = json.loads(_meta_get(conn, RELINK_LOG) or "[]")
+        except (ValueError, TypeError):
+            prior = []
+        prior.append({"when": time.time(), "first_break_seq": first,
+                      "entries_relinked": changed,
+                      "head_before": rows[-1]["hash"], "head_after": prev})
+        _meta_set(conn, RELINK_LOG, json.dumps(prior))
+    return changed, first
+
+
+def relink_history(conn) -> list[dict]:
+    """Every repair ever performed on this log. Empty is the normal case."""
+    try:
+        return json.loads(_meta_get(conn, RELINK_LOG) or "[]")
+    except (ValueError, TypeError):
+        return []