memdebug 0.2.0__py3-none-any.whl

memdebug/viewer/style.py

@@ -0,0 +1,218 @@
+"""The viewer's stylesheet. System fonts only: nothing is fetched from anywhere.
+
+Design rules, so later changes keep the same character:
+
+* Colour means change. The page itself is ink on paper; the only saturated colours are green (added),
+  blue (changed), red (deleted) and signal amber (changed outside the store's own history). Shape says it
+  too, so nothing depends on colour alone.
+* The timeline is a chain. Every entry hangs on one spine; what happened decides the shape of its node.
+* Two type roles. Interface text is a humanist sans close to Open Sans (Segoe UI on Windows; Open Sans or Noto
+  Sans if installed, otherwise the system font). The agent's own words, which are usually markdown, are set in
+  the monospace face of a code editor, the same face used for ids and hashes, so they look like the file they
+  came from. Only fonts already on the computer are used.
+* No cards, pills or shadows. Structure comes from rules, spacing and the chain.
+"""
+
+_DARK = """  --paper:#0d1a23;--sheet:#12232e;--ink:#dce6eb;--muted:#9bb0bc;--faint:#7c919d;--rule:#2a4251;--wash:#193040;
+  --add:#58c995;--add-wash:#133a2a;--chg:#86abff;--chg-wash:#1a2d54;--del:#ff8f7a;--del-wash:#4a211b;
+  --out:#f2b632;--out-ink:#f6d98b;--out-wash:#3d2f0f;--focus:#86abff;--on:#0d1a23;--on-out:#2b1c00;
+"""
+
+CSS = """
+:root{
+  color-scheme:light dark;
+  --paper:#edf0f2;--sheet:#f8f9fa;--ink:#10283a;--muted:#52687a;--faint:#5a6e7e;--rule:#c2cdd4;--wash:#e0e7ec;
+  --add:#17704a;--add-wash:#d8eee2;--chg:#2453b0;--chg-wash:#dce6f7;--del:#b0301d;--del-wash:#f7dfda;
+  --out:#e9a800;--out-ink:#5a3b00;--out-wash:#fbedc2;--focus:#2453b0;--on:#fff;--on-out:#3a2600;
+  --page:1480px;--seq:52px;--rail:46px;--node:28px;--gutter:clamp(16px,3.2vw,56px);
+  --ui:"Open Sans","Segoe UI Variable Text","Segoe UI","Noto Sans",Roboto,system-ui,"Helvetica Neue",Arial,sans-serif;
+  --mono:"Cascadia Mono","Cascadia Code",Consolas,"SF Mono",Menlo,ui-monospace,"DejaVu Sans Mono",monospace;
+}
+@media (prefers-color-scheme:dark){:root:not(.theme-light){@@DARK@@}}
+:root.theme-dark{color-scheme:dark;@@DARK@@}
+:root.theme-light{color-scheme:light}
+*{box-sizing:border-box}
+html{-webkit-text-size-adjust:100%}
+body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.5 var(--ui)}
+a{color:var(--ink);text-decoration-thickness:1px;text-underline-offset:3px}
+a:hover{text-decoration-thickness:2px}
+:focus-visible{outline:3px solid var(--focus);outline-offset:2px}
+code,pre,.mono{font-family:var(--mono);font-size:13px}
+h1,h2,h3{font-family:var(--ui);margin:0;line-height:1.2}
+h1{font-size:30px;font-weight:600;letter-spacing:-.012em;max-width:26ch}
+h2{font-size:18px;font-weight:600;margin:40px 0 12px}
+h3{font-size:15px;font-weight:600;margin:22px 0 6px}
+p{margin:0 0 10px}
+small{font-size:13px;color:var(--muted)}
+.sub{color:var(--muted);margin:10px 0 28px;max-width:62ch}
+
+/* masthead */
+header.top{max-width:var(--page);margin:0 auto;padding:22px var(--gutter) 0;display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 26px}
+.brand{position:relative;display:inline-block;padding-left:34px;font-size:21px;font-weight:600;letter-spacing:-.01em}
+.brand::before,.brand::after{content:"";position:absolute;top:50%;width:17px;height:10px;margin-top:-4px;border:2px solid var(--ink);border-radius:6px}
+.brand::before{left:0}.brand::after{left:9px}
+.where{font:12.5px var(--mono);color:var(--muted)}
+.ro{font-size:13px;color:var(--muted)}
+nav.tabs{margin-left:auto;display:flex;flex-wrap:wrap;gap:0 24px}
+nav.tabs a{padding:10px 0 8px;color:var(--muted);text-decoration:none;border-bottom:2px solid transparent}
+nav.tabs a:hover{color:var(--ink);border-bottom-color:var(--rule)}
+nav.tabs a[aria-current=page]{color:var(--ink);font-weight:600;border-bottom-color:var(--ink)}
+main{max-width:var(--page);margin:0 auto;padding:30px var(--gutter) 60px}
+footer{max-width:var(--page);margin:0 auto;padding:0 var(--gutter) 40px;color:var(--muted);font-size:13px}
+footer::before{content:"";display:block;border-top:1px solid var(--rule);margin-bottom:18px}
+
+/* colour theme switch: three links, the current one filled */
+.theme{display:flex;align-self:center;margin-left:6px;border:1px solid var(--rule);border-radius:4px;overflow:hidden}
+.theme a{padding:5px 12px;font-size:13px;line-height:1.4;color:var(--muted);text-decoration:none}
+.theme a:hover{background:var(--wash);color:var(--ink)}
+.theme a[aria-current=true]{background:var(--ink);color:var(--paper);font-weight:600}
+@media (max-width:860px){.theme{margin-left:0}}
+
+/* filters */
+.filters{display:flex;flex-wrap:wrap;gap:0 22px;margin:0 0 26px}
+.filters a{display:inline-flex;align-items:center;min-height:40px;color:var(--muted);text-decoration:none;border-bottom:2px solid transparent}
+.filters a:hover{color:var(--ink);border-bottom-color:var(--rule)}
+.filters a[aria-current=page]{color:var(--ink);font-weight:600;border-bottom-color:var(--ink)}
+
+/* timeline layout: a list on the left, a wide reading pane on the right */
+.layout{display:grid;grid-template-columns:minmax(380px,500px) minmax(0,1fr);gap:clamp(28px,3vw,48px);align-items:start}
+.sheet{position:sticky;top:16px;max-height:calc(100vh - 32px);overflow:auto;background:var(--sheet);border-top:3px solid var(--ink);padding:20px 26px 26px}
+.sheet-main{min-width:0}
+.sheet-side{margin-top:26px;padding-top:4px;border-top:1px solid var(--rule)}
+.sheet-side h3{margin-top:14px}
+@media (max-width:1100px){.layout{grid-template-columns:minmax(0,1fr);gap:28px}.layout.has-sheet .sheet{order:-1}.sheet{position:static;max-height:78vh}}
+@media (max-width:860px){h1{font-size:25px}nav.tabs{margin-left:0;width:100%}}
+@media (max-width:640px){:root{--seq:38px;--rail:32px;--node:26px}}
+
+/* the chain: one round dot per entry. Its colour and icon say what happened. */
+.chain{list-style:none;margin:0;padding:0;max-width:980px}
+.chain>li{position:relative;display:grid;grid-template-columns:var(--seq) var(--rail) minmax(0,1fr);
+  background:linear-gradient(var(--rule),var(--rule)) calc(var(--seq) + var(--rail)/2 - 1px) 0/2px 100% no-repeat}
+.chain>li:first-child{background-position:calc(var(--seq) + var(--rail)/2 - 1px) 25px;background-size:2px calc(100% - 25px)}
+.chain>li:last-child{background-size:2px 25px}
+.chain.goes-on>li:last-child{background-size:2px 100%}
+.chain>li:first-child:last-child{background:none}
+.chain>li::before{content:"";position:absolute;left:calc(var(--seq) + var(--rail)/2 - var(--node)/2);top:11px;width:var(--node);height:var(--node);
+  border-radius:50%;background-color:var(--disc,var(--ink));background-repeat:no-repeat;transition:none}
+.seq{grid-column:1;justify-self:end;padding-top:14px;font:12px var(--mono);color:var(--faint)}
+.chain>li>a.row{grid-column:3}
+.n-add{--disc:var(--add)}.n-update{--disc:var(--chg)}.n-delete{--disc:var(--del)}
+.n-external{--disc:var(--out);--on:var(--on-out)}
+.n-snapshot,.n-rollback{--disc:var(--ink);--on:var(--paper)}.n-snap-del{--disc:var(--faint);--on:var(--paper)}
+/* icons, drawn with gradients so they need no image files */
+.chain>li.n-add::before{background-image:linear-gradient(var(--on),var(--on)),linear-gradient(var(--on),var(--on));
+  background-position:8px 13px,13px 8px;background-size:12px 2px,2px 12px}
+.chain>li.n-delete::before,.chain>li.n-snap-del::before{
+  background-image:linear-gradient(var(--disc),var(--disc)),linear-gradient(var(--disc),var(--disc)),linear-gradient(var(--on),var(--on)),linear-gradient(var(--on),var(--on)),linear-gradient(var(--on),var(--on));
+  background-position:11px 14px,15px 14px,9px 12px,7px 9px,11px 7px;background-size:2px 5px,2px 5px,10px 9px,14px 2px,6px 2px}
+.chain>li.n-snapshot::before{
+  background-image:radial-gradient(circle at 14px 15.5px,var(--disc) 0 3.4px,transparent 4px),linear-gradient(var(--on),var(--on)),linear-gradient(var(--on),var(--on));
+  background-position:0 0,6px 10px,11px 7px;background-size:100% 100%,16px 11px,6px 3px}
+.chain>li.n-rollback::before{background-image:linear-gradient(var(--on),var(--on));background-position:9px 13px;background-size:11px 2px}
+.chain>li.n-rollback::after{content:"";position:absolute;width:8px;height:8px;left:calc(var(--seq) + var(--rail)/2 - 6px);
+  top:calc(11px + var(--node)/2 - 4px);transform:rotate(45deg);border-left:2px solid var(--on);border-bottom:2px solid var(--on)}
+.chain>li.n-external::before{background-image:linear-gradient(var(--on),var(--on)),linear-gradient(var(--on),var(--on));
+  background-position:13px 7px,13px 19px;background-size:2px 10px,2px 2px}
+.chain>li.n-update::after{content:"";position:absolute;width:5px;height:15px;left:calc(var(--seq) + var(--rail)/2 - 2.5px);top:calc(11px + var(--node)/2 - 7.5px);
+  transform:rotate(45deg);background:linear-gradient(var(--on) 0 18%,transparent 18% 27%,var(--on) 27%);clip-path:polygon(0 0,100% 0,100% 78%,50% 100%,0 78%)}
+.chain>li:has(a[aria-current=true])::before{box-shadow:0 0 0 3px var(--paper),0 0 0 5px var(--ink)}
+
+a.row{display:block;position:relative;padding:10px 14px 12px;margin:0 0 6px;color:var(--ink);text-decoration:none}
+a.row:hover{background:var(--wash)}
+a.row[aria-current=true]{background:var(--wash);box-shadow:inset 3px 0 0 var(--ink)}
+a.row:hover .what{text-decoration:underline}
+.top{display:flex;flex-wrap:wrap;align-items:center;gap:4px 10px}
+.what{font-size:15.5px;font-weight:600;overflow-wrap:anywhere}
+.when{margin-left:auto;font-size:12px;color:var(--muted);white-space:nowrap}
+.mem{margin:5px 0 0;font:13.5px/1.6 var(--mono);overflow-wrap:anywhere;display:-webkit-box;-webkit-line-clamp:4;-webkit-box-orient:vertical;overflow:hidden}
+.n-delete .mem{color:var(--muted);text-decoration:line-through;text-decoration-thickness:1px}
+.meta{margin-top:4px;font-size:13px;color:var(--muted);display:flex;flex-wrap:wrap;gap:0 14px}
+.flag{color:var(--out-ink);background:var(--out-wash);padding:0 6px;box-shadow:inset 0 -2px 0 var(--out)}
+.n-external>a.row{background:var(--out-wash);box-shadow:inset 4px 0 0 var(--out)}
+.n-external>a.row[aria-current=true]{box-shadow:inset 4px 0 0 var(--out-ink)}
+.label{font-size:15px}
+
+/* status badges */
+.badge{display:inline-block;padding:1px 8px;border-radius:4px;font-size:12px;font-weight:600;letter-spacing:.04em;line-height:1.5;white-space:nowrap}
+.op-add{background:var(--add-wash);color:var(--add)}
+.op-update{background:var(--chg-wash);color:var(--chg)}
+.op-delete{background:var(--del-wash);color:var(--del)}
+.op-external{background:var(--out-wash);color:var(--out-ink);box-shadow:inset 0 0 0 1px var(--out)}
+.op-rollback{background:var(--ink);color:var(--paper)}
+.op-snapshot,.op-snap-del{background:var(--wash);color:var(--ink);box-shadow:inset 0 0 0 1px var(--rule)}
+
+/* the open entry */
+ul.hints{list-style:none;margin:6px 0 12px;padding:0}
+ul.hints li{padding:6px 0;border-bottom:1px solid var(--rule);overflow-wrap:anywhere}
+ul.hints code{font-family:var(--mono);font-size:13px;color:var(--muted)}
+.flag.hint{background:var(--wash);box-shadow:inset 0 -2px 0 var(--rule);color:var(--ink)}
+ul.files{list-style:none;margin:6px 0 14px;padding:0;font:14px/1.8 var(--mono)}
+.what-did{display:inline-block;min-width:8ch;color:var(--muted)}
+ul.files small{color:var(--muted);font-family:var(--ui)}
+.sheet h2{margin:0 0 6px;font-size:24px;overflow-wrap:anywhere}
+.sheet .where2{margin:0 0 14px;font:12.5px var(--mono);color:var(--muted)}
+.verdict{font-weight:600;margin:0 0 6px}
+.why{color:var(--muted);margin:0 0 4px}
+.sheet h3{margin-top:22px}
+.redline,.quote{font:14px/1.75 var(--mono);white-space:pre-wrap;overflow-wrap:anywhere;margin:6px 0 4px}
+.ins{background:var(--chg-wash);color:var(--chg);text-decoration:underline;text-decoration-thickness:2px;text-underline-offset:3px;padding:0 1px}
+.rm + .ins{margin-left:.5ch}
+.rm{background:var(--del-wash);color:var(--del);text-decoration:line-through;text-decoration-thickness:2px;padding:0 1px}
+.redline .ln{min-height:1.75em}
+.ln.gone,.ln.added{margin:3px 0;padding:2px 10px 2px calc(10px + 2ch);text-indent:-2ch;border-left:3px solid}
+.ln.gone{border-left-color:var(--del);background:var(--del-wash)}
+.ln.added{border-left-color:var(--chg);background:var(--chg-wash)}
+.ln.gone::before{content:"\\2212\\00a0";color:var(--del)}
+.ln.added::before{content:"+\\00a0";color:var(--chg)}
+.ln.gone .rm,.ln.added .ins{background:none;text-decoration:none;padding:0}
+.ln.gone .rm{color:var(--del)}.ln.added .ins{color:var(--chg)}
+.fold{margin:8px 0;padding:3px 0;font:13px var(--ui);color:var(--muted);text-align:center;border-top:1px dashed var(--rule);border-bottom:1px dashed var(--rule)}
+.quote.gone{color:var(--muted);text-decoration:line-through;text-decoration-thickness:1px}
+.change-key{margin:0 0 8px;font-size:13px;color:var(--muted)}
+.change-key .ins,.change-key .rm{padding:0 4px}
+dl.facts{display:grid;grid-template-columns:96px minmax(0,1fr);gap:7px 14px;margin:0;font-size:14px}
+dl.facts dt{color:var(--muted)}dl.facts dd{margin:0;overflow-wrap:anywhere}
+details{margin:12px 0 0}
+summary{cursor:pointer;color:var(--muted)}summary:hover{color:var(--ink)}
+pre{margin:6px 0;padding:10px 12px;background:var(--wash);white-space:pre-wrap;overflow-wrap:anywhere;max-height:420px;overflow:auto;font:13px/1.5 var(--mono)}
+pre .add{color:var(--add);display:block}pre .del{color:var(--del);display:block}pre .hunk{color:var(--muted);display:block}
+
+/* overview */
+.headline{max-width:24ch}
+.fingerprint{display:block;margin:4px 0 8px;padding:10px 12px;background:var(--sheet);border-left:3px solid var(--ink);overflow-wrap:anywhere}
+.attention{margin-top:34px;padding-top:2px}
+.attention h2{margin-top:0}
+
+/* tables */
+.table-wrap{overflow-x:auto}
+table{border-collapse:collapse;width:100%}
+th,td{text-align:left;padding:10px 14px 10px 0;border-bottom:1px solid var(--rule);vertical-align:top;overflow-wrap:anywhere}
+th{font-weight:600;font-size:13px;color:var(--muted);border-bottom:2px solid var(--ink)}
+td:first-child,th:first-child{padding-left:0}
+tbody tr:hover{background:var(--wash)}
+td .mem{margin:0;font-size:13.5px}
+
+/* compare */
+form.pick{display:flex;flex-wrap:wrap;gap:14px 22px;align-items:end;margin:0 0 30px}
+form.pick label{display:flex;flex-direction:column;gap:5px;color:var(--muted);font-size:13px}
+select{min-height:42px;padding:0 10px;border:0;border-bottom:2px solid var(--ink);border-radius:0;background:var(--sheet);color:var(--ink);font:15px var(--ui)}
+button{min-height:42px;padding:0 20px;border:0;border-radius:2px;background:var(--ink);color:var(--paper);font:600 15px var(--ui);cursor:pointer}
+button:hover{background:var(--chg)}
+input[type=checkbox]{width:18px;height:18px;margin-right:6px;accent-color:var(--ink);vertical-align:-3px}
+.changes{display:flex;flex-direction:column;max-width:1100px}
+.change{display:grid;grid-template-columns:minmax(150px,200px) minmax(0,1fr);gap:4px 28px;padding:16px 0;border-top:1px solid var(--rule)}
+.change:first-child{border-top:2px solid var(--ink)}
+.change .who{display:flex;flex-direction:column;align-items:flex-start;gap:5px}
+@media (max-width:640px){.change{grid-template-columns:minmax(0,1fr)}}
+
+/* notices, pager */
+.notice{max-width:980px;margin:16px 0;padding:11px 16px;border-left:5px solid var(--out);background:var(--out-wash);color:var(--out-ink)}
+.notice.ok{border-left-color:var(--add);background:var(--add-wash);color:var(--add)}
+.notice.bad{border-left-color:var(--del);background:var(--del-wash);color:var(--del)}
+.pager{display:flex;gap:26px;margin:20px 0 0 calc(var(--seq) + var(--rail) + 14px)}
+.pager a{min-height:40px;display:inline-flex;align-items:center}
+.state{font-size:19px;font-weight:600;margin:0 0 14px;max-width:44ch}
+.state.ok{color:var(--add)}.state.bad{color:var(--del)}
+ul.problems{padding-left:20px}
+"""
+CSS = CSS.replace("@@DARK@@", _DARK.strip())

memdebug/witness.py

@@ -0,0 +1,199 @@
+"""A witness: a second copy of the ledger's head hash, kept somewhere else.
+
+The ledger's hash chain proves nothing was edited *inside* it, but whoever can rewrite the whole ledger file can build
+a new valid chain, or cut off its newest entries, and `verify` will still say "intact". A witness closes that gap: each
+time you run `memdebug witness --file PATH` one line is appended to a text file recording the ledger's newest entry and
+its hash. Later, `memdebug verify --witness PATH` checks that the ledger still contains exactly that entry. A ledger that
+was rewritten or truncated can no longer produce it.
+
+The witness file chains its own lines (each line carries the hash of the line before), so editing or deleting a line
+shows up as well. It holds hashes and counts only, never memory text.
+
+It is only as strong as its separation from the ledger: put the file where an attacker who controls the ledger cannot
+also rewrite it (another drive or machine, a synced folder, a USB stick, a repository you push to). A witness on the same
+disk buys little, and memdebug says so.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .adapters.markdown_git import _is_reparse_point
+from .errors import MemdebugError
+from .ledger import Ledger
+from .textsafe import safe_text
+
+MAX_WITNESS_BYTES = 16 * 1024 * 1024
+MAX_LINE_BYTES = 1024
+GENESIS = "0" * 64
+_HASH = re.compile(r"^[0-9a-f]{64}\Z")
+_KEYS = {"v", "seq", "head", "count", "at", "prev"}
+
+
+class WitnessError(MemdebugError):
+    """The witness file cannot be used (not a plain file, corrupt, unreadable)."""
+
+
+@dataclass(frozen=True)
+class WitnessLine:
+    seq: int
+    head: str
+    count: int
+    at: str
+    prev: str
+    text: str  # the exact line, without its line break
+
+    @property
+    def digest(self) -> str:
+        return hashlib.sha256(self.text.encode("utf-8")).hexdigest()
+
+
+@dataclass
+class WitnessCheck:
+    ok: bool
+    problems: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    lines: int = 0
+    last_seq: int = 0
+    unwitnessed: int = 0  # ledger entries newer than the last witnessed one
+
+
+def _line_text(seq: int, head: str, count: int, at: str, prev: str) -> str:
+    return json.dumps({"v": 1, "seq": seq, "head": head, "count": count, "at": at, "prev": prev},
+                      sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+def _check_path(path: Path, *, must_exist: bool) -> None:
+    try:
+        info = os.lstat(path)
+    except FileNotFoundError:
+        if must_exist:
+            raise WitnessError("the witness file does not exist") from None
+        if not path.parent.is_dir():
+            raise WitnessError("the folder for the witness file does not exist") from None
+        return
+    except OSError as exc:
+        raise WitnessError(f"cannot look at the witness file ({exc.strerror})") from exc
+    if stat.S_ISLNK(info.st_mode) or _is_reparse_point(info) or not stat.S_ISREG(info.st_mode):
+        raise WitnessError("the witness file must be a plain file, not a link or a folder")
+
+
+def read_witness(path: Path) -> tuple[list[WitnessLine], list[str]]:
+    """The lines of a witness file and any problems with the file itself (chain, format, order)."""
+    _check_path(path, must_exist=True)
+    try:
+        raw = path.read_bytes() if path.stat().st_size <= MAX_WITNESS_BYTES else None
+    except OSError as exc:
+        raise WitnessError(f"cannot read the witness file ({exc.strerror})") from exc
+    if raw is None:
+        raise WitnessError("the witness file is unexpectedly large")
+    problems: list[str] = []
+    lines: list[WitnessLine] = []
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return [], ["the witness file is not valid text"]
+    # Line-ending style and a leading byte-order mark carry no meaning (the chain hashes each line's text), and they change
+    # when the file passes through git's autocrlf or an editor, so they must not look like tampering.
+    text = text.removeprefix("\ufeff").replace("\r\n", "\n")
+    previous = GENESIS
+    parts = text.split("\n")
+    if parts and parts[-1] == "":
+        parts.pop()  # the final line break
+    for number, line in enumerate(parts, 1):
+        if len(line.encode("utf-8")) > MAX_LINE_BYTES:
+            problems.append(f"witness line {number} is too long")
+            break
+        try:
+            data = json.loads(line)
+        except ValueError:
+            problems.append(f"witness line {number} is not valid")
+            break
+        if (not isinstance(data, dict) or set(data) != _KEYS or data["v"] != 1 or not isinstance(data["seq"], int)
+                or isinstance(data["seq"], bool) or data["seq"] < 1 or not isinstance(data["count"], int)
+                or isinstance(data["count"], bool) or data["count"] < data["seq"] or not isinstance(data["head"], str)
+                or not _HASH.match(data["head"]) or not isinstance(data["prev"], str) or not isinstance(data["at"], str)
+                or not _HASH.match(data["prev"])):
+            problems.append(f"witness line {number} has unexpected contents")
+            break
+        canonical = _line_text(data["seq"], data["head"], data["count"], data["at"], data["prev"])
+        if canonical != line:
+            problems.append(f"witness line {number} was not written by memdebug (its form differs)")
+            break
+        entry = WitnessLine(data["seq"], data["head"], data["count"], data["at"], data["prev"], line)
+        if entry.prev != previous:
+            problems.append(f"witness line {number} does not follow the line before it: a line was changed or removed")
+        if lines and entry.seq < lines[-1].seq:
+            problems.append(f"witness line {number} goes back in time")
+        lines.append(entry)
+        previous = entry.digest
+    return lines, problems
+
+
+def append_witness(ledger: Ledger, path: Path, *, now: datetime | None = None) -> tuple[WitnessLine, bool]:
+    """Record the ledger's newest entry in the witness file. Returns the line and whether it was newly written."""
+    _check_path(path, must_exist=False)
+    existing: list[WitnessLine] = []
+    if os.path.lexists(path):
+        existing, problems = read_witness(path)
+        if problems:
+            raise WitnessError("the witness file is damaged (" + problems[0] + "), so it will not be extended")
+    entries = ledger.entries()
+    if not entries:
+        raise WitnessError("the ledger is empty; there is nothing to witness yet")
+    newest = entries[-1]
+    if existing and existing[-1].seq == newest.seq and existing[-1].head == newest.hash:
+        return existing[-1], False
+    at = (now or datetime.now(timezone.utc)).astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    prev = existing[-1].digest if existing else GENESIS
+    text = _line_text(newest.seq, newest.hash, len(entries), at, prev)
+    fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0), 0o644)
+    try:
+        os.write(fd, (text + "\n").encode("utf-8"))
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    return WitnessLine(newest.seq, newest.hash, len(entries), at, prev, text), True
+
+
+def same_disk(ledger_path: Path, witness_path: Path) -> bool:
+    try:
+        return os.stat(ledger_path).st_dev == os.stat(witness_path.parent).st_dev
+    except OSError:
+        return False
+
+
+SAME_DISK_WARNING = ("the witness is on the same disk as the ledger, so it gives little protection if that disk is "
+                     "compromised; keep it on another drive, machine or synced folder")
+
+
+def verify_witness(ledger: Ledger, path: Path, *, ledger_path: Path | None = None) -> WitnessCheck:
+    """Does the ledger still contain every entry the witness recorded?"""
+    lines, problems = read_witness(path)
+    check = WitnessCheck(ok=False, problems=list(problems), lines=len(lines))
+    if not lines and not problems:
+        check.problems.append("the witness file is empty")
+    total = ledger.counts()["events"]
+    for line in lines:
+        entry = ledger.get_entry(f"e{line.seq}") if line.seq <= total else None
+        if entry is None:
+            check.problems.append(f"the witness recorded entry {line.seq}, but the ledger has only {total} entries: "
+                                  "the newest entries were removed")
+            break
+        if entry.hash != line.head:
+            check.problems.append(f"entry {line.seq} is not what the witness recorded on {safe_text(line.at, 25)}: "
+                                  "the ledger was rewritten")
+            break
+    if lines:
+        check.last_seq = lines[-1].seq
+        check.unwitnessed = max(0, total - lines[-1].seq)
+    if ledger_path is not None and same_disk(ledger_path, path):
+        check.warnings.append(SAME_DISK_WARNING)
+    check.ok = not check.problems
+    return check

memdebug-0.2.0.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: memdebug
+Version: 0.2.0
+Summary: Inspect, compare and roll back what an AI agent's memory holds. Local-first and agent-neutral.
+Project-URL: Homepage, https://github.com/juraj-jumic/memdebug
+Project-URL: Source, https://github.com/juraj-jumic/memdebug
+Project-URL: Issues, https://github.com/juraj-jumic/memdebug/issues
+Project-URL: Changelog, https://github.com/juraj-jumic/memdebug/blob/main/CHANGELOG.md
+Author: Juraj Jumić
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-agents,forensics,memory,prompt-injection,security,tamper-evident
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-xdist>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mem0
+Requires-Dist: mem0ai>=2; extra == 'mem0'
+Provides-Extra: test-mem0
+Requires-Dist: mem0ai>=2; extra == 'test-mem0'
+Requires-Dist: pytest>=8; extra == 'test-mem0'
+Description-Content-Type: text/markdown
+
+# memdebug
+
+**See what your AI agent's memory holds, what changed, and put it back.** A local, agent-neutral tool for people who run
+agents whose memory they can reach: notes in a folder or git repository, Open WebUI's memory, or a self-hosted Mem0.
+
+An agent's memory is built from text it read at runtime, and text can be planted: an email, a web page, a document.
+Nobody reviews all of it. memdebug records what the memory holds in a tamper-evident ledger, shows what changed and when,
+catches edits that bypassed the store's own history, compares snapshots, flags wording worth a second look, and rolls markdown memory
+back safely.
+
+It is an **observer**: it never sits between the agent and its memory, never talks to the agent, and runs entirely on your
+computer. It does not block attacks as they happen (run it next to runtime guards), and it does not yet say *which
+conversation* wrote a memory. See [docs/threat-model.md](docs/threat-model.md) for exactly what it does and does not do.
+
+> **Status: alpha (0.2).** The parts described here work. The tests run on every push on Linux, Windows and macOS (Python 3.10, 3.12 and 3.14), and
+> the author also runs them on Windows 11, but expect rough edges. [ROADMAP.md](ROADMAP.md) lists what is built and what is next.
+
+## Try it in a minute
+
+    pip install .                 # needs Python 3.10+ and git 2.31+
+    memdebug demo                 # made-up agent, made-up attack, the real tools; nothing of yours is touched
+    memdebug demo --serve         # ...and then look at it in the browser viewer
+
+The demo plants an instruction into a note behind git's back, shows memdebug catching it, rolls the file back without losing
+the planted text, and shows the ledger noticing a tampered copy. It works in a throwaway folder and removes it afterwards.
+
+## Watch your own agent's memory
+
+You point memdebug at the memory; it does not hook into the agent. The easy way is the guided setup:
+
+    memdebug agents      # which AI agents are on this computer, and what each keeps (looks at folder names only)
+    memdebug setup       # finds that memory, asks before adding anything, saves a first snapshot of each
+    memdebug check       # looks for changes once; exit code 1 means something needs a look
+    memdebug watch       # keeps looking and says so when something changes (Ctrl+C to stop)
+    memdebug serve       # the same story in your browser, read-only
+
+Or register stores yourself (this is what a script would do):
+
+    memdebug add ~/agent/notes                    # a folder of markdown notes
+    memdebug add ~/agent/memory-repo              # markdown notes in a git repository (also reads its history)
+    memdebug add --docker open-webui              # Open WebUI running in Docker (memdebug copies its database itself)
+    memdebug add ~/copies/webui-copy.db           # Open WebUI's memory, from a copy of webui.db you made yourself
+    memdebug add ~/.mem0/history.db --user-id me  # self-hosted Mem0 (needs: pip install "mem0ai>=2")
+    memdebug stores | status | remove NAME
+
+| Store | What it is | Change history | "Changed outside the history" | Rollback |
+| --- | --- | --- | --- | --- |
+| markdown (git) | markdown notes in a git repository | git history | an uncommitted edit | yes |
+| folder | markdown notes in a plain folder (for example Claude Code's per-project memory folder) | none: changes are noticed between looks | not applicable | not yet |
+| openwebui | the `memory` table of Open WebUI's `webui.db`, copied from its Docker container (or from a copy you made) | none | not applicable | no |
+| mem0 | self-hosted Mem0 | Mem0's `history.db` | a change made directly in storage | no |
+
+Which agents does it know? Claude Code, OpenClaw, Gemini CLI, Codex CLI, Windsurf and Open WebUI (in Docker): see [docs/agents.md](docs/agents.md)
+for where each keeps its memory and where that was verified. Where memory sits in one file beside credentials (`~/.gemini`, `~/.codex`,
+`~/.claude`), memdebug watches only that file. If Open WebUI runs in Docker, `memdebug setup` finds it and takes a read-only copy of its database before every look; there is nothing to
+set up by hand (`windows-tools/copy-webui-db.ps1` is only a fallback for other setups). A store with no history can still be watched, but memdebug cannot tell an
+attacker's edit from your own: it records what changed and when. ChatGPT, Claude's apps, Gemini and Copilot keep memory in the
+provider's cloud: there is nothing local to watch, and memdebug says so rather than claiming to have found them.
+
+## Tools for people who want more
+
+    memdebug timeline | verify | diff s1 s2 --full | snapshot ... | rollback markdown --path REPO --to s1   # a dry run; add --apply
+    memdebug report --format markdown|json|sarif [--out FILE] [--fail-on findings|hints]    # for people, programs and CI
+    memdebug witness --file E:\memdebug-witness.txt      # a second copy of the ledger's fingerprint, kept somewhere else
+    memdebug verify --witness E:\memdebug-witness.txt    # catches a rewritten or cut-short ledger
+    memdebug check --strict                                # also exit 1 when changed wording looks worth a second look
+
+Where a store records it, memdebug also notes where a memory came from. For Open WebUI that is the app's own label (for example `created_by: manual`)
+and whether a chat was active at the time ("consistent with being added by hand" or "a chat was active"). It is evidence, never proof, and it never
+makes anything "trusted".
+
+Hints ("worth a second look") are guesses from the wording of what was added: instructions to send something to an address, to
+stop asking for confirmation, to weaken a safeguard, hidden characters, secret-looking strings. They miss things (paraphrases,
+many languages) and can flag harmless text, so they never count as a verdict. A secret-looking string is never repeated in a hint.
+
+Without `--db` the ledger and the list of stores go to a per-user folder (`%LOCALAPPDATA%\memdebug` on Windows,
+`~/.local/share/memdebug` elsewhere), never the current folder, which could be inside the repository being watched. Use
+`python -m memdebug ...` if the `memdebug` command is not on PATH. Treat the ledger as sensitive: it contains your agent's memory
+text. Then run `memdebug selftest` once on any new machine: it proves the platform-dependent protections hold there, and says SKIP
+(never PASS) for anything it could not prove.
+
+Keeping `watch` running: on Windows, create a shortcut to `memdebug watch` in the Startup folder; on Linux or macOS use a systemd
+user service or a login item. memdebug does not install anything that starts by itself.
+
+## Documentation
+
+* [docs/threat-model.md](docs/threat-model.md): what is defended, against whom, and the known limits.
+* [ROADMAP.md](ROADMAP.md): built, next, and not planned. [CHANGELOG.md](CHANGELOG.md): what changed. [docs/releasing.md](docs/releasing.md): how releases are made.
+* [SECURITY.md](SECURITY.md): how to report a problem. [CONTRIBUTING.md](CONTRIBUTING.md): how to help.
+
+## The viewer
+
+`memdebug serve` starts a read-only web page (timeline with an inspector, snapshots, compare,
+integrity) on **127.0.0.1 only**, and prints a link that contains a random secret. Open that link;
+the secret moves into a cookie and disappears from the address bar. It uses only Python's standard
+library and sends no JavaScript at all. Run `memdebug verify` once first if the ledger is from an
+older version (the viewer itself never upgrades or creates anything).
+
+Security of the viewer, threat by threat: [docs/threat-model.md](docs/threat-model.md#the-viewer). Its limits: it is plain HTTP on your own
+machine, the first link (with the secret) stays in your browser history, and processes running as you can read the secret.
+Choose Auto, Light or Dark at the top right.
+
+## Windows
+
+Written for Windows as well, with Windows-specific code paths. The test suite and `memdebug selftest` have been run on Windows 11, and the CI workflow covers `windows-latest`, but run `memdebug selftest` on your own machine anyway; it says SKIP, with a reason, for anything
+it cannot prove (for example symlinks need Developer Mode).
+
+- Needs Git for Windows 2.31+ (a real `git.exe`; shims and scripts are refused). `core.autocrlf=true` (the installer default)
+  is handled: line endings are normalised before comparing.
+- git is found through PATH entries that are absolute paths only; the current folder is never searched.
+- Names that mean something special on Windows (`NUL.md`, `con.md`, `file:stream.md`, trailing dots or spaces, `GIT~1`, `.GIT`)
+  are rejected on every platform, so the history and the files always agree.
+- Directory junctions and symlinks are never followed, including by rollback. A hung git is stopped with `taskkill /T`.
+- Ledger file permissions are not enforced by this tool on Windows; the default location is private to your user account.
+- If git reports "dubious ownership" for a repository on another drive, fix the ownership; this tool deliberately ignores your
+  global `safe.directory` setting.
+
+## How it is built
+
+The core (model, ledger, sync, reconcile) imports no backend. Each store type is a read-only adapter: `markdown-git` and `folder`
+(markdown files), `openwebui` and `mem0` (databases). Mem0 is imported lazily in one function; the whole suite passes with Mem0 not
+installed. Adding a store type is described in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+    pip install -e ".[dev]"
+    pytest -n auto
+    memdebug selftest
+    ruff check src tests && mypy
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the ground rules (everything read from a store is untrusted; adapters only read).
+
+## Rolling back (markdown/git)
+
+`memdebug rollback markdown` puts a memory folder back to what a snapshot held. It is the only command that changes
+your files, so it is cautious by design.
+
+```
+memdebug rollback markdown --path C:\path\to\memory --to s1            # shows what would change; writes nothing
+memdebug rollback markdown --path C:\path\to\memory --to s1 --apply    # does it, after you type the snapshot id
+```
+
+Options: `--only FILE` (repeatable) restores just those files; `--remove-added` also removes files added since the
+snapshot (by default they are left alone); `--full` shows the line changes; `--yes` skips the typed confirmation.
+
+What it guarantees:
+
+* **Nothing is rewritten.** Files that must change in git become one new commit, written by `memdebug`, on top of
+  your branch. Your history stays exactly as it was.
+* **Nothing is lost.** Anything git does not already hold that the rollback would replace or delete (an uncommitted
+  edit, a file that was never committed) is saved first under `refs/memdebug/backups/...`. Get a file back with
+  `git checkout <that name> -- <file>`.
+* **Exact bytes.** Files come back byte for byte from the matching version in git history, line endings included. A
+  snapshot's normalised text is used only when git never held that version, and never if it was cut, too large or
+  not valid text.
+* **No programs run.** Hooks, filters, fsmonitor and other helpers named in the repository are never executed.
+* **It refuses unsafe states:** a detached HEAD, staged changes, a merge or rebase in progress, a git lock, links,
+  junctions, device names, or paths that differ only by letter case.
+* **It undoes itself** if any step fails, and says so.
+* **It can be undone.** It takes a snapshot just before and just after, and records a `ROLLBACK` entry in the ledger.
+  To undo a rollback, roll back to the "before" snapshot it printed.
+
+`memdebug selftest` proves the "no programs run" and "exact bytes" claims on your computer.
+
+## Fonts
+
+The viewer uses only fonts already on your computer: Open Sans or Noto Sans if you have them, otherwise Segoe UI
+(Windows) or the system font. Memory text, which is usually markdown, is shown in the monospace font a code editor
+would use (Cascadia Mono or Consolas on Windows). Nothing is downloaded or bundled.
+
+## License
+
+Copyright 2026 Juraj Jumić. Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).