aichivist 0.1.0__py3-none-any.whl

aichivist/__init__.py

@@ -0,0 +1,3 @@
+"""aichivist – archival-grade file operations for AI filing agents."""
+
+__version__ = "0.1.0"

aichivist/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

aichivist/agent_tools.py

@@ -0,0 +1,184 @@
+"""Tools for agents without file access of their own (e.g. Claude Desktop via MCP).
+
+Every path must lie inside the folders the person shared when starting the server (--root). Paths are resolved
+first, so `..` and symlinks cannot escape. Moving files is only possible through filing plans.
+"""
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from . import (
+    apps,
+    catalog,
+    config,
+    describe,
+    duplicates,
+    fulltext,
+    inventory,
+    lifecycle,
+    photos,
+    plan,
+    retention,
+    review,
+    similar,
+    storage,
+    structure,
+    style,
+    survey,
+)
+from .config import full_path
+from .fileops import FilingError
+
+PLAN_NAME = re.compile(r"^[\w .-]{1,60}$")
+DEFAULT_MAX_CHARS = 20_000
+LIST_LIMIT = 300
+
+
+class Workspace:
+    def __init__(self, roots: List, rules=None, exclude: Optional[List] = None):
+        self.roots = [full_path(r).resolve() for r in roots]
+        self.rules = full_path(rules) if rules else None
+        self.exclude = [full_path(e).resolve() for e in exclude or []]
+
+    def excluded(self, path: Path) -> bool:
+        return any(path == e or e in path.parents for e in self.exclude)
+
+    def check(self, path) -> Path:
+        resolved = full_path(path).resolve()
+        if not any(resolved == r or r in resolved.parents for r in self.roots):
+            raise FilingError(f"{path} is outside the folders shared with aichivist")
+        if self.excluded(resolved):
+            raise FilingError(f"{path} is in an excluded folder; aichivist does not open it")
+        return resolved
+
+    def _plan_file(self, name: str) -> Path:
+        if not PLAN_NAME.match(name):
+            raise FilingError("plan names may contain letters, digits, spaces, dots, dashes and underscores")
+        folder = config.home_dir() / "plans"
+        folder.mkdir(parents=True, exist_ok=True)
+        return folder / f"{name}.md"
+
+    # ---- reading -------------------------------------------------------------
+    def get_rules(self) -> Dict[str, Any]:
+        if not self.rules or not self.rules.exists():
+            return {"rules": None, "note": "No rules file configured – ask the person where things belong before "
+                                           "proposing a plan, and suggest writing rules (templates/RULES.md)."}
+        return {"rules": self.rules.read_text(encoding="utf-8"), "path": str(self.rules)}
+
+    def survey(self, paths: List[str], stale_years: int = 3) -> Dict[str, Any]:
+        report = survey.run([self.check(p) for p in paths], stale_years=stale_years, exclude=self.exclude)
+        return survey.as_dict(report)
+
+    def list_folder(self, path: str) -> Dict[str, Any]:
+        folder = self.check(path)
+        entries = [{"name": p.name, "kind": "folder" if p.is_dir() else "file",
+                    "size": p.stat().st_size if p.is_file() else None}
+                   for p in sorted(folder.iterdir()) if not p.name.startswith(".") and not self.excluded(p.resolve())]
+        return {"path": str(folder), "entries": entries[:LIST_LIMIT], "truncated": len(entries) > LIST_LIMIT}
+
+    def read_document(self, path: str, max_chars: int = DEFAULT_MAX_CHARS) -> Dict[str, Any]:
+        file = self.check(path)
+        if not file.is_file():
+            raise FilingError(f"not a file: {path}")
+        text, method = fulltext.extract(file)
+        return {"path": str(file), "method": method, "text": text[:max_chars], "characters": len(text),
+                "truncated": len(text) > max_chars}
+
+    def inventory(self, path: str) -> Dict[str, Any]:
+        folder = self.check(path)
+        changes = inventory.diff(folder)
+        by_hand = inventory.manual_moves(folder, changes)
+
+        def visible(rel: str) -> bool:
+            return not self.excluded((folder / rel.rstrip("/")).resolve())
+        return {"entries": [e for e in changes.entries if visible(e)], "first_run": changes.first_run,
+                "new": [e for e in changes.new if visible(e)],
+                "moved": [{"from": o, "to": n, "by_hand": (o, n) in by_hand} for o, n in changes.moved
+                          if visible(o) and visible(n)]}
+
+    def find_duplicates(self, paths: List[str], area: str) -> List[Dict[str, str]]:
+        found = duplicates.find([self.check(p) for p in paths], self.check(area))
+        return [{"source": str(d.source), "match": str(d.match)} for d in found
+                if not self.excluded(d.source.resolve()) and not self.excluded(d.match.resolve())]
+
+    def find_similar(self, paths: List[str], area: Optional[str] = None, threshold: float = 0.8) -> List[Dict]:
+        hits = similar.find([self.check(p) for p in paths], self.check(area) if area else None, threshold)
+        return [h._asdict() for h in hits]
+
+    def suggest_name(self, path: str) -> Dict[str, Any]:
+        return describe.suggest(self.check(path))
+
+    def naming_examples(self, area: str) -> Dict[str, Any]:
+        return style.examples(self.check(area))
+
+    def structure_advice(self, area: str) -> Dict[str, Any]:
+        report = structure.analyse(self.check(area))
+        return {"findings": [f._asdict() for f in report.findings], "summary": structure.render(report)}
+
+    def retention_due(self, area: str, years: float) -> List[Dict[str, Any]]:
+        return [d._asdict() for d in retention.due(self.check(area), years)]
+
+    # ---- filing plans --------------------------------------------------------
+    def plan_add(self, source: str, target: str, reason: str, plan_name: str = "current") -> Dict[str, str]:
+        checked_target = target if target == plan.TRASH else str(self.check(target))
+        return plan.add(self._plan_file(plan_name), self.check(source), checked_target, reason)._asdict()
+
+    def plan_show(self, plan_name: str = "current") -> Dict[str, Any]:
+        file = self._plan_file(plan_name)
+        rows = [r._asdict() for r in plan.read(file)] if file.exists() else []
+        return {"plan": str(file), "rows": rows}
+
+    def plan_check(self, plan_name: str = "current", create_folders: bool = False) -> Dict[str, Any]:
+        results = plan.check(self._plan_file(plan_name), create_folders)
+        return {"problems": [{"row": i, "source": r.source, "problem": p}
+                             for i, (r, p) in enumerate(results, 1) if p]}
+
+    def plan_approve(self, plan_name: str = "current", rows: Optional[List[int]] = None,
+                     leave_link: bool = False) -> Dict[str, int]:
+        return {"approved": plan.approve(self._plan_file(plan_name), rows, leave_link)}
+
+    def storage_check(self, table_file: str) -> Dict[str, Any]:
+        table = self.check(table_file)
+        if not table.exists():
+            return {"error": "table missing", "example": storage.EXAMPLE}
+        return storage.as_dict(storage.check(table))
+
+    def program_check(self, paths: List[str]) -> Dict[str, List[str]]:
+        ctx = apps.context()
+        return {p: apps.risks(self.check(p), ctx) for p in paths}
+
+    def plan_review(self, plan_name: str = "current") -> Dict[str, str]:
+        url = review.serve(self._plan_file(plan_name), open_browser=True, block=False)
+        return {"url": url, "note": "The person reviews the plan in the browser and approves rows there."}
+
+    def plan_apply(self, plan_name: str = "current", create_folders: bool = False) -> Dict[str, object]:
+        file = self._plan_file(plan_name)
+        for row in plan.read(file):  # a plan file could have been edited – re-check every approved row
+            if row.mark in ("x", "link"):
+                self.check(row.source)
+                if row.target != plan.TRASH:
+                    self.check(row.target)
+        return plan.apply(file, create_folders)._asdict()
+
+    def plan_photos(self, inbox: str, photos_root: str, plan_name: str = "current") -> Dict[str, Any]:
+        rows = photos.propose(self.check(inbox), self.check(photos_root), self._plan_file(plan_name))
+        return {"proposed": len(rows), "rows": [r._asdict() for r in rows]}
+
+    # ---- catalogs and collections ---------------------------------------------
+    def catalog_check(self, catalog_file: str, add_missing: bool = False, prefill: bool = True) -> Dict[str, Any]:
+        file = self.check(catalog_file)
+        added = catalog.add_missing(file, prefill=prefill) if add_missing else []
+        return {"added": added, **catalog.check(file)._asdict()}
+
+    def catalog_describe(self, catalog_file: str, file: str, content: str, search_terms: str,
+                         date: str) -> Dict[str, str]:
+        return {"row": catalog.describe(self.check(catalog_file), file, content, search_terms, date)}
+
+    def status(self, path: str) -> Dict[str, Any]:
+        return {k: str(v) if v is not None else None for k, v in lifecycle.status(self.check(path))._asdict().items()}
+
+    def verify(self, path: str) -> Dict[str, List[str]]:
+        return lifecycle.verify(self.check(path))
+
+    def search(self, path: str, query: str) -> List[Dict[str, Any]]:
+        return [h._asdict() for h in fulltext.search(self.check(path), query)]

aichivist/apps.py

@@ -0,0 +1,243 @@
+"""Program data: notice before a move that a program depends on a path, so programs keep working afterwards.
+
+A file is program data when it lies in a place programs manage (Library, AppData, Program Files, ~/.config …),
+belongs to a program library or project (Photos library, Lightroom catalog, Obsidian vault, Steam, code project …),
+is the target of a link or shortcut, or is open in a running program. aichivist then refuses to move it: the person
+either adjusts the program first (`--app-data`), or moves it with `--leave-link` (plan mark `link`) – a link at the
+old place points to the new one, so the program finds its files as before.
+"""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Dict, Iterable, List, NamedTuple, Optional, Tuple
+
+from .config import full_path
+from .i18n import t
+from .inventory import PROJECT_MARKERS
+
+LIBRARY_SUFFIXES = {
+    ".app": "program", ".photoslibrary": "Photos library", ".musiclibrary": "Music library",
+    ".tvlibrary": "TV library", ".lrcat": "Lightroom catalog", ".lrdata": "Lightroom catalog",
+    ".fcpbundle": "Final Cut library", ".logicx": "Logic project", ".band": "GarageBand project",
+    ".aplibrary": "Aperture library", ".vmwarevm": "virtual machine", ".pvm": "virtual machine",
+    ".vbox": "virtual machine", ".utm": "virtual machine",
+}
+FOLDER_MARKERS = {
+    ".obsidian": "Obsidian vault", "zotero.sqlite": "Zotero library", "metadata.db": "Calibre library",
+    "collection.anki2": "Anki profile", "steamapps": "Steam library", "prefs.js": "Firefox/Thunderbird profile",
+    ".minecraft": "Minecraft folder", "node_modules": "code project", "iTunes Library.itl": "iTunes library",
+    **{marker: "code project" for marker in PROJECT_MARKERS},
+}
+LINK_DEPTH = 3          # how deep below the home folder links and shortcuts are looked for
+SHORTCUT_MAX = 65536    # Windows .lnk files are small; bigger files are not shortcuts
+LSOF_TIMEOUT = 20       # seconds for listing the files open in running programs
+SHOWN_PROGRAMS = 3      # programs named per open file
+
+
+class Context(NamedTuple):
+    """Collected once per run: links/shortcuts (place → what they point to) and files open in programs."""
+    links: List[Tuple[Path, str]]
+    open_files: Dict[str, str]
+
+
+def managed_places() -> List[Path]:
+    """Folders that belong to programs or the system, per operating system."""
+    home = Path.home()
+    if sys.platform == "win32":
+        names = ("APPDATA", "LOCALAPPDATA", "PROGRAMDATA", "ProgramFiles", "ProgramFiles(x86)", "SystemRoot")
+        return [Path(os.environ[n]) for n in names if os.environ.get(n)]
+    if sys.platform == "darwin":
+        return [home / "Library", Path("/Library"), Path("/Applications"), Path("/System"), Path("/usr"),
+                Path("/opt")]
+    return [home / ".config", home / ".local", home / ".var", home / "snap", Path("/usr"), Path("/opt"),
+            Path("/etc"), Path("/var/lib")]
+
+
+def user_places() -> List[Path]:
+    """The person's own cloud folders, even though they lie inside program folders (iCloud Drive in ~/Library …)."""
+    home = Path.home()
+    return [home / "Library" / "Mobile Documents" / "com~apple~CloudDocs", home / "Library" / "CloudStorage"]
+
+
+def _inside(path: Path, folder: Path) -> bool:
+    return path == folder or folder in path.parents
+
+
+def place_risk(path: Path) -> Optional[str]:
+    """Is the path in a folder that programs manage? Temporary folders are not counted."""
+    if any(_inside(path, p) for p in [Path(tempfile.gettempdir()).resolve(), *user_places()]):
+        return None
+    for place in managed_places():
+        if _inside(path, place):
+            return t("in the program folder {place}", place=place)
+    home = Path.home()
+    if _inside(path, home) and path != home:
+        parts = path.relative_to(home).parts  # programs keep hidden folders directly in the home folder (~/.config);
+        if len(parts) > 1 and parts[0].startswith("."):  # hidden folders deeper down belong to the person
+            return t("in the hidden program folder {place}", place=home / parts[0])
+    return None
+
+
+def kind_of(folder: Path, names: Iterable[str]) -> Optional[str]:
+    """Program library or project, judged from the folder's name and its entry names (no extra disk access)."""
+    if folder.suffix.lower() in LIBRARY_SUFFIXES:
+        return LIBRARY_SUFFIXES[folder.suffix.lower()]
+    present = set(names)
+    return next((kind for marker, kind in FOLDER_MARKERS.items() if marker in present), None)
+
+
+def _kind(folder: Path) -> Optional[str]:
+    if folder.suffix.lower() in LIBRARY_SUFFIXES:
+        return LIBRARY_SUFFIXES[folder.suffix.lower()]
+    try:
+        if not folder.is_dir():
+            return None
+        return next((kind for marker, kind in FOLDER_MARKERS.items() if (folder / marker).exists()), None)
+    except OSError:  # a folder that cannot be read (owned by another user) is not judged
+        return None
+
+
+def library_risk(path: Path, look_inside: bool = True) -> Optional[str]:
+    """Is the path a program library or project, part of one, or (with `look_inside`) does it contain one?"""
+    for folder in [path, *path.parents]:
+        kind = _kind(folder)
+        if kind:
+            return t("is a {kind}", kind=t(kind)) if folder == path else t("part of a {kind} ({folder})",
+                                                                          kind=t(kind), folder=folder)
+    if look_inside and path.is_dir():
+        for dirpath, dirnames, _ in os.walk(path):
+            for d in dirnames:
+                kind = _kind(Path(dirpath) / d)
+                if kind:
+                    return t("contains a {kind} ({folder})", kind=t(kind), folder=Path(dirpath) / d)
+    return None
+
+
+def _shortcut_text(lnk: Path) -> str:
+    """Text of a Windows shortcut; its target path is searched in it, no shortcut parser needed."""
+    try:
+        if lnk.stat().st_size > SHORTCUT_MAX:
+            return ""
+        data = lnk.read_bytes()
+    except OSError:
+        return ""
+    return "\n".join((data.decode("latin-1"), data.decode("utf-16-le", "ignore"),
+                      data[1:].decode("utf-16-le", "ignore")))
+
+
+def find_links(roots: Iterable[Path], depth: int = LINK_DEPTH) -> List[Tuple[Path, str]]:
+    """Symbolic links (resolved target) and Windows shortcuts (their text) below the roots, skipping program folders."""
+    found: List[Tuple[Path, str]] = []
+    places = managed_places()
+    for root in roots:
+        if not root.is_dir():
+            continue
+        base = len(root.parts)
+        for dirpath, dirnames, filenames in os.walk(root):
+            folder = Path(dirpath)
+            for name in dirnames + filenames:
+                entry = folder / name
+                if entry.is_symlink():
+                    found.append((entry, os.path.realpath(entry)))
+                elif name.lower().endswith(".lnk"):
+                    found.append((entry, _shortcut_text(entry)))
+            if len(folder.parts) - base >= depth:
+                dirnames.clear()
+            dirnames[:] = [d for d in dirnames if not d.startswith(".") and not (folder / d).is_symlink()
+                           and not (place_risk(folder / d) and any(_inside(folder / d, p) for p in places))]
+    return found
+
+
+def open_files() -> Dict[str, str]:
+    """Files open in the person's running programs (path → program), via lsof where it exists."""
+    lsof = shutil.which("lsof")
+    if not lsof or not hasattr(os, "getuid"):
+        return {}  # Windows itself refuses to move files that are open
+    try:
+        out = subprocess.run([lsof, "-w", "-n", "-u", str(os.getuid()), "-F", "cn"], capture_output=True,
+                             text=True, errors="replace", timeout=LSOF_TIMEOUT).stdout
+    except (OSError, subprocess.SubprocessError):
+        return {}
+    files: Dict[str, str] = {}
+    program = ""
+    for line in out.splitlines():
+        if line.startswith("c"):
+            program = line[1:]
+        elif line.startswith("n/"):
+            files.setdefault(line[1:], program)
+    return files
+
+
+def context(roots: Optional[Iterable[Path]] = None) -> Context:
+    """Links below the home folder (and the Windows start menu) plus open files, collected once."""
+    if roots is None:
+        roots = [Path.home()]
+        if sys.platform == "win32" and os.environ.get("APPDATA"):
+            roots.append(Path(os.environ["APPDATA"]) / "Microsoft" / "Windows" / "Start Menu")
+    return Context(find_links(roots), open_files())
+
+
+def _points_to(link: Path, target: str, path: Path, real: str) -> bool:
+    if link.suffix.lower() == ".lnk" and not link.is_symlink():
+        return str(path).lower() in target.lower()
+    return target == real or target.startswith(real + os.sep)
+
+
+def risks(path, ctx: Context) -> List[str]:
+    """Reasons why moving or deleting `path` may stop a program from working. Empty list: safe to move."""
+    path = full_path(path)
+    real = os.path.realpath(path)
+    found = [r for r in (place_risk(path), library_risk(path)) if r]
+    found += [t("the link {link} points to it", link=link) for link, target in ctx.links
+              if link != path and _points_to(link, target, path, real)]
+    in_use = sorted({prog for f, prog in ctx.open_files.items() if f == real or f.startswith(real + os.sep)})
+    if in_use:
+        more = t(" and {n} more", n=len(in_use) - SHOWN_PROGRAMS) if len(in_use) > SHOWN_PROGRAMS else ""
+        found.append(t("open in {programs}{more} – close it first", programs=", ".join(in_use[:SHOWN_PROGRAMS]),
+                       more=more))
+    return found
+
+
+def target_risk(target) -> Optional[str]:
+    """Filing into a program folder or library would hand records over to a program. Other things in the target
+    folder do not matter: a project next to the target is not touched."""
+    folder = full_path(target).parent
+    return place_risk(folder) or library_risk(folder, look_inside=False)
+
+
+def leave_link(old: Path, new: Path) -> None:
+    """Put a link at the old place that points to the new one, so programs find the files as before.
+    Where symbolic links are not allowed (Windows without Developer Mode): a junction for folders, a hard link for
+    files (same drive only) – neither needs admin rights."""
+    try:
+        os.symlink(new, old, target_is_directory=new.is_dir())
+        return
+    except OSError:
+        if new.is_dir() and sys.platform != "win32":
+            raise
+    if new.is_dir():
+        done = subprocess.run(["cmd", "/c", "mklink", "/J", str(old), str(new)], capture_output=True, text=True)
+        if done.returncode != 0:
+            raise OSError(done.stderr.strip() or "mklink /J failed")
+    else:
+        os.link(new, old)
+
+
+def is_link_to(old: Path, new: Path) -> bool:
+    """Is `old` a link left behind by leave_link that leads to `new`?"""
+    if not new.exists() or not (old.is_symlink() or old.exists()):
+        return False
+    if old.is_symlink() or (old.is_dir() and sys.platform == "win32"):
+        return old != new and os.path.realpath(old) == os.path.realpath(new)
+    return old.is_file() and new.is_file() and os.path.samefile(old, new)
+
+
+def remove_link(old: Path) -> None:
+    """Remove only the link itself – never what it points to."""
+    try:
+        old.unlink()
+    except OSError:
+        os.rmdir(old)  # directory symlinks and junctions on Windows; fails safely on a real, non-empty folder

aichivist/bagit.py

@@ -0,0 +1,103 @@
+"""Export a closed collection as a BagIt 1.0 bag (RFC 8493, Library of Congress) and validate bags.
+
+The bag is a self-describing archival package: payload in data/, SHA-256 manifests, bag-info metadata. Any
+BagIt tool (e.g. bagit-python, Bagger) can validate it – no aichivist needed in the future.
+"""
+import shutil
+from datetime import date
+from pathlib import Path
+from typing import Dict, List
+
+from . import __version__, journal, lifecycle
+from .checksums import digest, manifest
+from .config import full_path
+from .fileops import FilingError
+
+BAGIT_TXT = "BagIt-Version: 1.0\nTag-File-Character-Encoding: UTF-8\n"
+PAYLOAD_MANIFEST = "manifest-sha256.txt"
+TAG_MANIFEST = "tagmanifest-sha256.txt"
+TAG_FILES = ("bagit.txt", "bag-info.txt", PAYLOAD_MANIFEST)
+
+
+def encode(path: str) -> str:
+    """Only CR/LF are encoded, as in the reference implementation bagit-python. RFC 8493 also asks for "%" → "%25",
+    but bagit-python does not decode it, so such bags would fail validation there; interoperability wins."""
+    return path.replace("\r", "%0D").replace("\n", "%0A")
+
+
+def decode(path: str) -> str:
+    return path.replace("%0A", "\n").replace("%0D", "\r")
+
+
+def _write_manifest(path: Path, entries: Dict[str, str]) -> None:
+    path.write_text("".join(f"{h}  {encode(rel)}\n" for rel, h in sorted(entries.items())), encoding="utf-8")
+
+
+def _read_manifest(path: Path) -> Dict[str, str]:
+    entries = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            checksum, rel = line.split(maxsplit=1)
+            entries[decode(rel.strip())] = checksum
+    return entries
+
+
+def _copy_payload(root: Path, dest: Path, recorded: Dict[str, str]) -> Dict[str, str]:
+    payload = {}
+    for rel, checksum in recorded.items():
+        target = dest / "data" / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(root / rel, target)
+        if digest(target) != checksum:
+            raise FilingError(f"copy of {rel} does not match the fixity manifest; export aborted")
+        payload[f"data/{rel}"] = checksum
+    return payload
+
+
+def export(area, dest) -> Path:
+    info = lifecycle.status(area)
+    if info.state != "closed":
+        raise FilingError(f"only closed collections can be exported as a bag: {area}")
+    root, dest = info.root, full_path(dest)
+    if dest.exists():
+        raise FilingError(f"target exists, nothing overwritten: {dest}")
+    changes = [f"{kind} {rel}" for kind, items in lifecycle.verify(root).items() for rel in items]
+    if changes:
+        raise FilingError(f"{root} changed since it was closed ({', '.join(changes[:5])}); run `aichivist verify`")
+    recorded = lifecycle.recorded_manifest(root)
+    try:
+        payload = _copy_payload(root, dest, recorded)
+    except BaseException:
+        shutil.rmtree(dest, ignore_errors=True)  # no half-written bag
+        raise
+    (dest / "bagit.txt").write_text(BAGIT_TXT, encoding="utf-8")
+    _write_manifest(dest / PAYLOAD_MANIFEST, payload)
+    total = sum((root / rel).stat().st_size for rel in recorded)
+    (dest / "bag-info.txt").write_text(
+        f"Bagging-Date: {date.today().isoformat()}\n"
+        f"Payload-Oxum: {total}.{len(recorded)}\n"
+        f"External-Identifier: {root.name}\n"
+        f"External-Description: {' '.join((info.note or 'closed collection').split())}\n"
+        f"Closed-At: {info.closed_at}\n"
+        f"Bag-Software-Agent: aichivist {__version__}\n", encoding="utf-8")
+    _write_manifest(dest / TAG_MANIFEST, {name: digest(dest / name) for name in TAG_FILES})
+    journal.write(root, dest, "export_bag")
+    return dest
+
+
+def validate(bag) -> List[str]:
+    """Problems found in a bag; an empty list means the bag is complete and intact."""
+    bag = full_path(bag)
+    if not (bag / "bagit.txt").exists() or not (bag / PAYLOAD_MANIFEST).exists():
+        return ["not a bag: bagit.txt or manifest-sha256.txt missing"]
+    problems = []
+    if (bag / TAG_MANIFEST).exists():
+        for name, checksum in _read_manifest(bag / TAG_MANIFEST).items():
+            if not (bag / name).exists() or digest(bag / name) != checksum:
+                problems.append(f"tag file changed: {name}")
+    recorded = _read_manifest(bag / PAYLOAD_MANIFEST)
+    present = {f"data/{rel}": h for rel, h in manifest(bag / "data").items()} if (bag / "data").exists() else {}
+    problems += [f"changed: {rel}" for rel in sorted(recorded) if rel in present and present[rel] != recorded[rel]]
+    problems += [f"missing: {rel}" for rel in sorted(recorded) if rel not in present]
+    problems += [f"not in manifest: {rel}" for rel in sorted(present) if rel not in recorded]
+    return problems