mindslice 0.1.0__py3-none-any.whl

mindslice/storage/snapshots.py

@@ -0,0 +1,262 @@
+"""Portable directory snapshots with content verification and isolated restore."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import stat
+import tempfile
+from pathlib import Path, PurePosixPath
+
+from ..errors import RecoveryError
+from .config import Mount, MountTable, dump_mounts, load_mounts
+from .fsutil import atomic_write_text, fsync_dir
+from .history import ChangeHistory, event
+
+MANIFEST = 'backup.json'
+
+
+def digest(path):
+    with Path(path).open('rb') as stream:
+        return hashlib.file_digest(stream, 'sha256').hexdigest()
+
+
+def inventory(root, exclude=()):
+    """Do not follow symlinks, including directory links and special files."""
+    root = Path(root)
+    if root.is_symlink() or not root.is_dir():
+        raise RecoveryError('snapshot source must be a real directory', path=str(root))
+    files, directories = {}, []
+    def unreadable(exc):
+        raise RecoveryError('cannot read a snapshot directory', path=str(exc.filename)) from exc
+    for directory, names, filenames in os.walk(root, followlinks=False, onerror=unreadable):
+        current = Path(directory)
+        for name in sorted(names + filenames):
+            path = current / name
+            rel = path.relative_to(root).as_posix()
+            if any(rel == e or rel.startswith(e + '/') for e in exclude):
+                if name in names:
+                    names.remove(name)
+                continue
+            mode = path.lstat().st_mode
+            if stat.S_ISLNK(mode) or not (stat.S_ISDIR(mode) or stat.S_ISREG(mode)):
+                raise RecoveryError('snapshot contains a symlink or special file; use ordinary files/directories', path=str(path))
+            if stat.S_ISDIR(mode):
+                directories.append(rel)
+            else:
+                files[rel] = {'sha256': digest(path), 'size': path.stat().st_size}
+    return {'files': dict(sorted(files.items())), 'directories': sorted(directories)}
+
+
+def _copy(source, target, listing):
+    target.mkdir(parents=True, exist_ok=True)
+    for name in listing['directories']:
+        (target / name).mkdir(parents=True, exist_ok=True)
+    for name, info in listing['files'].items():
+        src, dst = source / name, target / name
+        if src.is_symlink() or not stat.S_ISREG(src.stat().st_mode):
+            raise RecoveryError('source changed during snapshot', path=str(src))
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        with src.open('rb') as reader, dst.open('xb') as stream:
+            shutil.copyfileobj(reader, stream)
+            stream.flush()
+            shutil.copystat(src, dst)
+            os.fsync(stream.fileno())
+        if digest(dst) != info['sha256'] or dst.stat().st_size != info['size']:
+            raise RecoveryError('source changed during snapshot', path=str(src))
+    for name in reversed(listing['directories']):
+        fsync_dir(target / name)
+    fsync_dir(target)
+
+
+def _destination(path, sources):
+    target = Path(path).expanduser().absolute()
+    if target.exists() or target.is_symlink():
+        raise RecoveryError('destination already exists; choose a new directory', path=str(target))
+    for root in sources:
+        if target.resolve().is_relative_to(root.resolve()):
+            raise RecoveryError('destination must be outside the source directories', path=str(target), source=str(root))
+    return target
+
+
+def _publish(temporary, target):
+    if target.exists() or target.is_symlink():
+        raise RecoveryError('destination appeared during operation; preserved', path=str(target))
+    os.rename(temporary, target)
+    fsync_dir(target.parent)
+
+
+def _safe_relative(value):
+    if not isinstance(value, str) or not value or '\\' in value or ':' in value or '\x00' in value:
+        raise RecoveryError('invalid path in backup manifest')
+    path = PurePosixPath(value)
+    if path.is_absolute() or any(p in ('', '.', '..') for p in value.split('/')):
+        raise RecoveryError('unsafe path in backup manifest', path=value)
+    return value
+
+
+def backup(ws, output):
+    from ..operations.audit import history_path
+
+    with ws._writing() as table:
+        # Recovery has completed before recording any bytes. A partial orphan log tail is not a backupable event.
+        _, complete = ws.history._read()
+        if ws.history.path.exists() and ws.history.path.stat().st_size != complete:
+            raise RecoveryError('history has an incomplete final record; inspect it before backing up')
+        roots = [ws.root]
+        requested = [m.root for m in table.all()]
+        unavailable = []
+        records = ws.history.events()
+        for e in records:
+            if e['event'] in ('baked', 'rolled_back'):
+                for field in ('path', 'previous_path'):
+                    if e.get(field):
+                        path = history_path(ws, e[field], records)
+                        if path.is_dir():
+                            requested.append(path)
+                        else:
+                            unavailable.append(str(path))
+        for root in requested:
+            if not root.is_dir():
+                raise RecoveryError('a mounted source is missing; restore its path or unmount it first', path=str(root))
+            if root != ws.root and ws.root.is_relative_to(root):
+                raise RecoveryError('a mounted source contains the workspace; mount a narrower directory before backup', path=str(root))
+        external = sorted(set(p for p in requested if not p.is_relative_to(ws.root)), key=lambda p: (len(p.parts), str(p)))
+        for root in external:
+            if not any(root.is_relative_to(r) for r in roots):
+                roots.append(root)
+        target = _destination(output, roots)
+        locations = {root: ('workspace' if root == ws.root else f'external/{i}') for i, root in enumerate(roots)}
+        def location(path):
+            root = next(r for r in roots if path.is_relative_to(r))
+            return (PurePosixPath(locations[root]) / path.relative_to(root).as_posix()).as_posix()
+        snapshots = {root: inventory(root, ('.cache',) if root == ws.root else ()) for root in roots}
+        if any(p in snapshots[ws.root]['files'] for p in ('staging/.apply_journal.json', '.history/.pending.json')):
+            raise RecoveryError('unfinished transaction; recover it before backing up')
+        target.parent.mkdir(parents=True, exist_ok=True)
+        temporary = Path(tempfile.mkdtemp(prefix='.mindslice-backup-', dir=target.parent))
+        try:
+            for root in roots:
+                _copy(root, temporary / locations[root], snapshots[root])
+            for root in roots:
+                if snapshots[root] != inventory(root, ('.cache',) if root == ws.root else ()):
+                    raise RecoveryError('source changed during backup; retry after edits finish', path=str(root))
+            listing = inventory(temporary)
+            for name in list(listing['files']) + listing['directories']:
+                _safe_relative(name)
+            metadata = {'format': 'mindslice-workspace-backup', 'version': 1,
+                        'workspace': str(ws.root), 'roots': {str(p): locations[p] for p in roots},
+                        'mounts': [dict(m.to_toml(), kind=m.kind, stored=location(m.root)) for m in table.all()],
+                        'unavailable_versions': sorted(set(unavailable)), **listing}
+            atomic_write_text(temporary / MANIFEST, json.dumps(metadata, indent=2, ensure_ascii=False) + '\n')
+            _publish(temporary, target)
+        finally:
+            if temporary.exists():
+                shutil.rmtree(temporary)
+        return {'path': str(target), 'files': len(listing['files']), 'external_sources': len(roots) - 1,
+                'unavailable_versions': metadata['unavailable_versions'],
+                'note': 'Includes workspace files, staging, history, mounted external sources and available recorded versions; cache excluded.'}
+
+
+def _load_backup(source):
+    if source.is_symlink() or (source / MANIFEST).is_symlink():
+        raise RecoveryError('backup and its manifest must not be symlinks')
+    try:
+        metadata = json.loads((source / MANIFEST).read_text(encoding='utf-8'))
+    except (OSError, ValueError) as exc:
+        raise RecoveryError('cannot read backup manifest', path=str(source)) from exc
+    if not isinstance(metadata, dict) or metadata.get('format') != 'mindslice-workspace-backup' or metadata.get('version') != 1:
+        raise RecoveryError('unsupported backup format')
+    files, directories = metadata.get('files'), metadata.get('directories')
+    if not isinstance(files, dict) or not isinstance(directories, list):
+        raise RecoveryError('invalid backup inventory')
+    for name in list(files) + directories:
+        _safe_relative(name)
+    for info in files.values():
+        if not isinstance(info, dict) or not isinstance(info.get('sha256'), str) or not isinstance(info.get('size'), int):
+            raise RecoveryError('invalid file checksum in backup')
+    actual = inventory(source, (MANIFEST,))
+    if actual != {'files': files, 'directories': directories}:
+        raise RecoveryError('backup contents do not match the manifest; no workspace restored')
+    if 'workspace/mounts.toml' not in files:
+        raise RecoveryError('backup has no workspace mount table')
+    if any(p in files for p in ('workspace/staging/.apply_journal.json', 'workspace/.history/.pending.json')):
+        raise RecoveryError('backup contains an unfinished transaction; refusing to replay old absolute paths')
+    roots = metadata.get('roots')
+    if not isinstance(roots, dict) or not isinstance(metadata.get('mounts'), list):
+        raise RecoveryError('invalid backup source mapping')
+    stored_roots = list(roots.values())
+    if stored_roots.count('workspace') != 1 or len(set(stored_roots)) != len(stored_roots):
+        raise RecoveryError('backup must contain one workspace and unique external roots')
+    for original, stored in roots.items():
+        if not isinstance(original, str):
+            raise RecoveryError('invalid original source path')
+        _safe_relative(stored)
+        if stored != 'workspace' and (len(PurePosixPath(stored).parts) != 2 or not stored.startswith('external/')):
+            raise RecoveryError('invalid stored source path')
+        if stored not in directories:
+            raise RecoveryError('missing stored source directory', path=stored)
+    for mount in metadata['mounts']:
+        if not isinstance(mount, dict):
+            raise RecoveryError('invalid mount record')
+        stored = _safe_relative(mount.get('stored'))
+        if not any(stored == r or stored.startswith(r + '/') for r in stored_roots) or stored not in directories:
+            raise RecoveryError('mount points outside stored sources', path=stored)
+    return metadata
+
+
+def restore(source, destination):
+    source = Path(source).expanduser().absolute()
+    metadata = _load_backup(source)
+    target = _destination(destination, [source])
+    # Reserve a namespace for external sources without replacing any backed-up files.
+    external_dir = '.restored-mounts'
+    n = 1
+    while f'workspace/{external_dir}' in metadata['directories'] or f'workspace/{external_dir}' in metadata['files']:
+        n += 1
+        external_dir = f'.restored-mounts-{n}'
+    def relocated(stored):
+        if stored == 'workspace':
+            return '.'
+        if stored.startswith('workspace/'):
+            return stored[len('workspace/'):]
+        return external_dir + '/' + stored[len('external/'):]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = Path(tempfile.mkdtemp(prefix='.mindslice-restore-', dir=target.parent))
+    try:
+        for stored in metadata['roots'].values():
+            prefix = stored + '/'
+            subset = {'files': {p[len(prefix):]: v for p, v in metadata['files'].items() if p.startswith(prefix)},
+                      'directories': [p[len(prefix):] for p in metadata['directories'] if p.startswith(prefix)]}
+            _copy(source / stored, temporary / relocated(stored), subset)
+        mounts = []
+        for entry in metadata['mounts']:
+            rel = relocated(entry['stored'])
+            mounts.append(Mount(entry['alias'], './' + rel, entry['precedence'], entry['role'], entry['kind'], temporary / rel))
+        overlays = [m for m in mounts if m.kind == 'overlay']
+        if len(overlays) != 1 or any(m.kind not in ('overlay', 'slice') for m in mounts):
+            raise RecoveryError('backup needs exactly one overlay')
+        atomic_write_text(temporary / 'mounts.toml', dump_mounts(MountTable(overlays[0], [m for m in mounts if m.kind == 'slice'])))
+        # Parse only the rewritten local paths, never access original paths from the manifest.
+        load_mounts(temporary)
+        history = ChangeHistory(temporary / '.history')
+        _, complete = history._read()
+        if history.path.exists() and complete != history.path.stat().st_size:
+            raise RecoveryError('backup history has an incomplete record')
+        path_map = {original: relocated(stored) for original, stored in metadata['roots'].items()}
+        history.append([event('restored', backup=str(source), path=str(target), path_map=path_map)])
+        # A reviewed bake plan is bound to the original workspace and must be reviewed again.
+        (temporary / '.bake-plan.json').unlink(missing_ok=True)
+        if _load_backup(source) != metadata:
+            raise RecoveryError('backup changed during restore; retry with an unchanged backup')
+        _publish(temporary, target)
+    except (KeyError, TypeError, ValueError) as exc:
+        raise RecoveryError('invalid backup metadata; no workspace restored') from exc
+    finally:
+        if temporary.exists():
+            shutil.rmtree(temporary)
+    return {'workspace': str(target), 'backup': str(source), 'mounts': [dict(m.to_toml(), path=str(target / m.path)) for m in mounts],
+            'unavailable_versions': metadata.get('unavailable_versions', []),
+            'note': 'Restored into a new directory. Overlay and staging preserved; cache rebuilds on first use. '
+                    'Review bake choices again and point the client at this workspace.'}

mindslice/workspace.py

@@ -0,0 +1,385 @@
+"""The MindSlice workspace: mount table + overlay + staging + disposable index.
+
+All nine primitives are methods on :class:`Workspace`:
+
+* Group A (online, also exposed over MCP): ``manifest``, ``search``, ``read``, ``write``
+  (plus ``boot``: the always-loaded cards, which ``manifest`` also returns)
+* Group B (slice management):              ``mount`` / ``unmount``, ``validate``, ``bake`` (plus ``status``)
+* Group C (transactional sandbox):         ``diff``, ``apply`` / ``discard``
+
+Every operation runs under ``.cache/workspace.lock`` (``LOCK_SH`` for reads,
+``LOCK_EX`` for writes). Before serving any request the workspace finishes an
+interrupted ``apply()`` (if ``staging/.apply_journal.json`` exists) and
+re-indexes files whose ``(mtime_ns, size)`` changed, upgrading to ``LOCK_EX``
+only when there is maintenance to do.
+"""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator, Sequence
+
+from .baking import bake as bake_mod, slice_transfer
+from .operations import boot as boot_mod, staging as staging_mod, status as status_mod, validation, writer
+from .retrieval import query
+from .model.addressing import alias_from_name, normalize_alias
+from .storage.config import (
+    MOUNTS_FILE,
+    Mount,
+    MountTable,
+    load_mounts,
+    load_slice_manifest,
+    portable_path,
+    save_mounts,
+)
+from .errors import MountError, NotFoundError, WorkspaceNotFoundError
+from .storage.history import ChangeHistory
+from .retrieval.index import FRONTMATTER_CODES, Index, SyncStats
+from .model.lineage import FollowSpec
+from .storage.locking import WorkspaceLock
+from .operations.staging import StagingArea
+
+CACHE_DIR = ".cache"
+INDEX_FILE = "index.sqlite"
+LOCK_FILE = "workspace.lock"
+STAGING_DIR = "staging"
+SLICES_DIR = "slices"
+
+
+class Workspace:
+    def __init__(self, root: str | os.PathLike[str], *, create: bool = False, lock_timeout: float = 30.0) -> None:
+        self.root = Path(os.path.abspath(Path(root).expanduser()))
+        if not (self.root / MOUNTS_FILE).is_file():
+            if not create:
+                raise WorkspaceNotFoundError(
+                    f"{self.root} is not a MindSlice workspace (no {MOUNTS_FILE}); run `mindslice init`", next_steps=[
+                        "If the path is wrong, pass the right workspace with `-w PATH`; a hook or MCP configuration "
+                        "needs the absolute path.",
+                        f"If there is no workspace yet, create one: `mindslice init {self.root}`."])
+            self._bootstrap()
+        self.cache_dir = self.root / CACHE_DIR
+        self.staging = StagingArea(self.root / STAGING_DIR)
+        self.history = ChangeHistory(self.root / ".history")
+        self.lock = WorkspaceLock(self.cache_dir / LOCK_FILE, timeout=lock_timeout)
+        self._index: Index | None = None
+        self._table: MountTable | None = None
+        self.last_sync: SyncStats | None = None
+        self.last_recovery: dict[str, Any] | None = None
+
+    # ------------------------------------------------------------------
+    # construction helpers
+    # ------------------------------------------------------------------
+    @classmethod
+    def init(cls, root: str | os.PathLike[str], **kwargs: Any) -> "Workspace":
+        """Create (or open) a workspace with an empty overlay and default mount table."""
+        return cls(root, create=True, **kwargs)
+
+    @classmethod
+    def discover(cls, start: str | os.PathLike[str] | None = None, **kwargs: Any) -> "Workspace":
+        """Find the nearest enclosing workspace (directory containing ``mounts.toml``)."""
+        current = Path(os.path.abspath(Path(start or os.getcwd()).expanduser()))
+        for candidate in (current, *current.parents):
+            if (candidate / MOUNTS_FILE).is_file():
+                return cls(candidate, **kwargs)
+        raise WorkspaceNotFoundError(f"no {MOUNTS_FILE} found in {current} or any parent directory", next_steps=[
+            "Name the workspace: `mindslice -w PATH <command>`, or set `MINDSLICE_WORKSPACE=PATH`.",
+            "If there is no workspace yet, create one: `mindslice init PATH`."])
+
+    def _bootstrap(self) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        for sub in ("overlay", STAGING_DIR, SLICES_DIR, CACHE_DIR):
+            (self.root / sub).mkdir(exist_ok=True)
+        gitignore = self.root / ".gitignore"
+        if not gitignore.exists():
+            gitignore.write_text(f"{CACHE_DIR}/\n", encoding="utf-8")
+        table = load_mounts(self.root)  # defaults: ./overlay @overlay precedence=100 role=runtime
+        save_mounts(self.root, table)
+
+    # ------------------------------------------------------------------
+    # lifecycle
+    # ------------------------------------------------------------------
+    @property
+    def index(self) -> Index:
+        if self._index is None:
+            self._index = Index(self.cache_dir / INDEX_FILE)
+        return self._index
+
+    def close(self) -> None:
+        if self._index is not None:
+            self._index.close()
+            self._index = None
+        self.lock.close()
+
+    def __enter__(self) -> "Workspace":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Workspace({str(self.root)!r})"
+
+    # ------------------------------------------------------------------
+    # mount table / maintenance
+    # ------------------------------------------------------------------
+    def table(self) -> MountTable:
+        if self._table is None:
+            self._table = load_mounts(self.root)
+        return self._table
+
+    def _reload_table(self) -> MountTable:
+        self._table = load_mounts(self.root)
+        return self._table
+
+    def _exclude(self) -> list[Path]:
+        return [self.staging.root, self.cache_dir, self.history.root]
+
+    def _sync(self, table: MountTable | None = None, verify: bool = False) -> SyncStats:
+        stats = self.index.sync(table or self.table(), self._exclude(), verify=verify)
+        self.last_sync = stats
+        return stats
+
+    def _recover(self, table: MountTable) -> None:
+        if self.history.recover():
+            self.last_recovery = {"recovered": True, "history": True}
+            table = self._reload_table()
+        journal = self.staging.read_journal()
+        if journal is None:
+            return
+        if journal.get("corrupt"):
+            moved_to = self.staging.quarantine_journal()
+            self.last_recovery = {"recovered": False, "corrupt_journal": str(moved_to)}
+            return
+        report = staging_mod.replay(self, table, journal)
+        report["recovered"] = True
+        self.last_recovery = report
+
+    def _needs_maintenance(self, table: MountTable) -> bool:
+        return self.history.has_journal() or self.staging.has_journal() or self.index.is_stale(table, self._exclude())
+
+    @contextmanager
+    def _reading(self) -> Iterator[MountTable]:
+        """Shared lock; upgrades to exclusive only if a journal or stale files need handling."""
+        with self.lock.shared():
+            table = self._reload_table()
+            if not self._needs_maintenance(table):
+                yield table
+                return
+        with self.lock.exclusive():
+            table = self._reload_table()
+            self._recover(table)
+            table = self._reload_table()
+            self._sync(table)
+            yield table
+
+    @contextmanager
+    def _writing(self, sync: bool = True) -> Iterator[MountTable]:
+        with self.lock.exclusive():
+            table = self._reload_table()
+            self._recover(table)
+            table = self._reload_table()
+            if sync:
+                self._sync(table)
+            yield table
+
+    # ------------------------------------------------------------------
+    # Group A: online read/write
+    # ------------------------------------------------------------------
+    def manifest(self, limit: int = 20, offset: int = 0, max_folders_per_mount: int = 10,
+                 include_overview: bool = False, include_always: bool = True) -> dict[str, Any]:
+        return query.manifest(self, limit, offset, max_folders_per_mount, include_overview, include_always)
+
+    def boot(self) -> dict[str, Any]:
+        """The always-loaded cards (``load = "always"``), resolved and composed, for a session's start."""
+        return boot_mod.boot(self)
+
+    def search(self, query_text: str, source: str | Sequence[str] | None = None,
+               tags: str | Sequence[str] | None = None, k: int = 10, offset: int = 0,
+               max_neighbors: int = 3, follow_supersedes: FollowSpec = True) -> dict[str, Any]:
+        return query.search(self, query_text, source, tags, k, offset, max_neighbors, follow_supersedes)
+
+    def read(self, address: str, follow_supersedes: FollowSpec = True, max_backlinks: int = 10,
+             backlinks_offset: int = 0, max_extensions: int = 5, extensions_offset: int = 0) -> dict[str, Any]:
+        return query.read(self, address, follow_supersedes, max_backlinks, backlinks_offset,
+                          max_extensions, extensions_offset)
+
+    def write(self, id: str, op: str = "create", content: Any = None, summary: str | None = None,
+              title: str | None = None, tags: Sequence[str] | None = None, aliases: Sequence[str] | None = None,
+              extends: Sequence[str] | None = None, supersedes: Sequence[str] | None = None,
+              stage: bool | None = None, if_match: str | None = None, load: str | None = None, reason: str | None = None) -> dict[str, Any]:
+        """``stage=None`` stages changes to the always-loaded context for approval (see ``boot``)."""
+        return writer.write(self, id, op, content, summary, title, tags, aliases, extends, supersedes, stage,
+                            if_match, load, reason)
+
+    # ------------------------------------------------------------------
+    # Group B: slice management, linting & packaging
+    # ------------------------------------------------------------------
+    def status(self) -> dict[str, Any]:
+        """Mounts, pending review and unbaked overlay changes, without card bodies."""
+        return status_mod.status(self)
+
+    def card_history(self, address: str | None = None, limit: int = 20, offset: int = 0) -> dict[str, Any]:
+        from .operations.audit import card_history
+        return card_history(self, address, limit, offset)
+
+    def explain(self, address: str, follow_supersedes=True, max_extensions: int = 5,
+                extensions_offset: int = 0) -> dict[str, Any]:
+        from .operations.audit import explain
+        return explain(self, address, follow_supersedes, max_extensions, extensions_offset)
+
+    def rollback(self, alias: str, path=None, *, dry_run: bool = False, revision: str | None = None) -> dict[str, Any]:
+        from .operations.recovery import rollback
+        return rollback(self, alias, path, dry_run=dry_run, revision=revision)
+
+    def backup(self, output) -> dict[str, Any]:
+        from .storage.snapshots import backup
+        return backup(self, output)
+
+    @classmethod
+    def restore(cls, source, destination) -> dict[str, Any]:
+        from .storage.snapshots import restore
+        return restore(source, destination)
+
+    def mount(self, path: str | os.PathLike[str], alias: str | None = None, precedence: int = 50,
+              role: str = "baseline", retire_overlay: bool = True) -> dict[str, Any]:
+        """Mount a read-only slice directory.
+
+        Relative paths are resolved against the current directory, falling back to the
+        workspace root. ``mounts.toml`` stores ``./relative`` paths for slices inside the workspace.
+
+        Any directory of Markdown works as is: notes without frontmatter, or with legacy ``---`` YAML,
+        are indexed without conversion, and without ``alias`` or a ``slice.toml`` alias the directory
+        name becomes one (``My Notes`` -> ``@My-Notes``).
+
+        ``retire_overlay`` (default): overlay cards this slice holds unchanged after reference
+        rewriting are removed so they don't shadow it. References from the overlay cards that stay
+        are rewritten to the slice (``slice_transfer.retire_copies``).
+        """
+        target = Path(path).expanduser()
+        if not target.is_absolute():
+            target = target.absolute() if target.is_dir() else self.root / target
+        target = Path(os.path.abspath(target))
+        if not target.is_dir():
+            raise MountError(f"{target} is not a directory", path=str(target))
+        if isinstance(precedence, bool) or not isinstance(precedence, int):
+            raise MountError("precedence must be an integer")
+        if not isinstance(role, str) or not role.strip():
+            raise MountError("role must be a non-empty string")
+        sm = load_slice_manifest(target)
+        if alias or sm.alias:
+            alias = normalize_alias(alias or sm.alias)
+        else:  # a plain folder: its name, made a valid alias
+            alias = alias_from_name(target.name.removesuffix(".slice"))
+        with self._writing() as table:
+            if alias == table.overlay.alias or table.get(alias) is not None:
+                raise MountError(f"alias {alias} is already mounted", alias=alias, next_steps=[
+                    f"Mount under another name with `--alias NAME`, or run `mindslice unmount {alias}` first to "
+                    "replace that mount; `mindslice status` lists the mounts."])
+            for m in table.all():
+                if m.root == target:
+                    raise MountError(f"{target} is already mounted as {m.alias}", alias=m.alias, next_steps=[
+                        f"Nothing to do: its cards are available as {m.alias}. To change its alias or precedence, "
+                        f"run `mindslice unmount {m.alias}` and mount it again."])
+            if target in (self.staging.root, self.cache_dir, self.history.root) or any(
+                    root in target.parents for root in (self.cache_dir, self.history.root)):
+                raise MountError("cannot mount MindSlice internal directories")
+            new = Mount(alias, portable_path(self.root, target), precedence, role.strip(), "slice", target)
+            new_table = MountTable(table.overlay, [*table.mounts, new])
+            save_mounts(self.root, new_table)
+            table = self._reload_table()
+            stats = self._sync(table)
+            retired = slice_transfer.retire_copies(self, table, alias) if retire_overlay else {}
+            if retired:
+                self._sync(table)
+            mounted = {m.alias for m in new_table.all()}
+            missing = []
+            for dep in sm.dependencies:
+                try:
+                    if normalize_alias(dep) not in mounted:
+                        missing.append(dep)
+                except ValueError:
+                    missing.append(dep)
+            rows = [r for r in self.index.all_cards(alias) if not r["is_overview"]]
+            result: dict[str, Any] = {
+                "alias": alias, "path": new.path, "precedence": precedence, "role": new.role,
+                "cards": len(rows), "sync": stats.to_dict(),
+            }
+            plain = sum(1 for r in rows if r["has_frontmatter"] == FRONTMATTER_CODES[None])
+            yaml = sum(1 for r in rows if r["has_frontmatter"] == FRONTMATTER_CODES["yaml"])
+            if plain or yaml:  # indexed as is: title from the heading or file name, summary from the first paragraph
+                result["formats"] = {"toml": len(rows) - plain - yaml, "yaml": yaml, "plain": plain}
+            result.update(retired)
+            if missing:
+                result["missing_dependencies"] = missing
+            if sm.errors:
+                result["manifest_errors"] = sm.errors
+            always = [c for c in boot_mod.snapshot(self, self.table())["cards"]
+                      if c["mount"] == alias or c.get("redirected_from", "").startswith(alias + "/")]
+            if always:
+                result["always_loaded"] = always
+            return result
+
+    def unmount(self, alias: str) -> dict[str, Any]:
+        alias = normalize_alias(alias)
+        with self._writing() as table:
+            if alias == table.overlay.alias:
+                raise MountError(f"{alias} is the writable overlay and cannot be unmounted")
+            if table.get(alias) is None:
+                raise NotFoundError(f"{alias} is not mounted", alias=alias)
+            new_table = MountTable(table.overlay, [m for m in table.mounts if m.alias != alias])
+            save_mounts(self.root, new_table)
+            stats = self._sync(self._reload_table())
+            return {"alias": alias, "removed_cards": stats.removed, "sync": stats.to_dict()}
+
+    def validate(self, slice_path: str | os.PathLike[str] | None = None, rebuild_index: bool = False) -> dict[str, Any]:
+        return validation.validate(self, slice_path, rebuild_index)
+
+    def bake(self, alias: str | None = None, output_path: str | os.PathLike[str] | None = None, prefix: str | None = None,
+             tags: str | Sequence[str] | None = None, include_deps: bool = False, dry_run: bool = False,
+             *, name: str | None = None, description: str | None = None, version: str | None = None,
+             plan: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Bake one alias, or a reviewed workspace plan when ``alias`` is omitted.
+
+        Named new slices require ``prefix``; batch plans explicitly assign individual cards.
+        ``bake(dry_run=True)`` returns the batch plan; ``bake(plan=reviewed)`` verifies and executes it.
+        Previous directories remain untouched. Batch outputs use workspace ``slices/`` defaults.
+        """
+        if alias is None:
+            from .baking import bake_batch
+            from .errors import InvalidArgumentsError
+            if any(x is not None for x in (output_path, prefix, tags, name, description, version)) or include_deps:
+                raise InvalidArgumentsError("single-slice options require an alias")
+            reviewed = self.plan_bake() if plan is None else plan
+            if dry_run:
+                return reviewed if plan is None else bake_batch.inspect_plan(self, reviewed)
+            return bake_batch.execute(self, reviewed)
+        if plan is not None:
+            from .errors import InvalidArgumentsError
+            raise InvalidArgumentsError("a workspace bake plan cannot be combined with an alias")
+        return bake_mod.bake(self, alias, output_path, prefix, tags, include_deps, dry_run,
+                             name=name, description=description, version=version)
+
+    def plan_bake(self, assignments: dict[str, str | None] | None = None, *, resume: bool = True) -> dict[str, Any]:
+        """Review all overlay cards; null destinations explicitly defer cards. No content writes."""
+        from .baking.bake_batch import plan_bake
+        return plan_bake(self, assignments, resume=resume)
+
+    # ------------------------------------------------------------------
+    # Group C: transactional sandbox
+    # ------------------------------------------------------------------
+    def diff(self, scope: str = "staging") -> dict[str, Any]:
+        return staging_mod.diff(self, scope)
+
+    def apply(self, ids: list[str] | None = None) -> dict[str, Any]:
+        """Accept all pending changes, or only the specified staging card IDs."""
+        return staging_mod.apply(self, ids)
+
+    def discard(self, ids: list[str] | None = None) -> dict[str, Any]:
+        """Reject all pending changes, or only the specified staging card IDs."""
+        return staging_mod.discard(self, ids)
+
+    def review(self, accept: list[str], reject: list[str], *, revision: str, dry_run: bool = False) -> dict[str, Any]:
+        """Execute reviewed choices in one recoverable batch; other cards stay pending."""
+        return staging_mod.apply(self, accept, reject=reject, revision=revision, dry_run=dry_run)