mindslice 0.1.0__py3-none-any.whl

mindslice/operations/boot.py

@@ -0,0 +1,183 @@
+"""Always-loaded cards (``load = "always"``): the boot set, its rendering, and its write protection.
+
+A card whose frontmatter says ``load = "always"`` holds session-level context: an agent persona, the
+user's language, standing instructions. Every session reads it at start (MCP ``initialize``
+instructions, ``manifest()``, ``mindslice boot``), whether or not a query would have found it.
+Otherwise it is an ordinary card: searchable, readable, and subject to lineage like any other.
+
+The boot set is each always-loaded card resolved as ``read()`` resolves it: a superseded card
+forwards to its replacement, and baselines and extensions are composed in. Its *footprint* is
+every card whose content (or lineage) decides what the set contains. Because those cards shape
+every session, a write that touches the footprint is staged for the user's approval by default
+(``write(stage=None)``), and ``apply()`` is that approval.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING, Any, Iterable
+
+from ..retrieval import query
+from ..model.addressing import format_address, resolve_ref
+from ..model.card import LOAD_ALWAYS, parse_card
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..storage.config import MountTable
+    from ..workspace import Workspace
+
+# Extensions composed into one boot card (read() pages them; the boot set shows them all up to this).
+MAX_EXTENSIONS = 50
+
+HEADER = (
+    "# Always-loaded memory\n\n"
+    "These cards come from the user's MindSlice memory and apply to the whole session (persona, language, "
+    "standing instructions). Follow them unless the user says otherwise. Changes to them are staged for the "
+    "user's approval."
+)
+
+
+def _card(c: dict[str, Any]) -> dict[str, Any]:
+    return {"address": c["address"], "title": c["title"], "summary": c.get("summary", ""), "body": c.get("body", "")}
+
+
+def collect(ctx: "query._Ctx") -> tuple[list[dict[str, Any]], set[str]]:
+    """``(entries, footprint)``: the rendered boot cards and every address that shapes them."""
+    entries: list[dict[str, Any]] = []
+    footprint: set[str] = set()
+    shown: set[str] = set()
+    for row in ctx.idx.always_cards():
+        address = format_address(row["mount"], row["path"])
+        r = query.resolve(ctx, address, max_backlinks=0, max_extensions=MAX_EXTENSIONS, bump_telemetry=False)
+        baselines = r.get("baselines", [])
+        extensions = r.get("extensions", [])
+        parts = [r["address"], *(b["address"] for b in baselines), *(e["address"] for e in extensions)]
+        footprint.update([address, *r.get("lineage_path", []), *parts])
+        if all(a in shown for a in parts):
+            continue  # everything it would show is already in the set (e.g. an always-loaded extension)
+        shown.update(parts)
+        entry = _card(r) | {"mount": r["mount"], "role": r["role"], "sha256": r["sha256"]}
+        if r.get("redirected_from"):
+            entry["redirected_from"] = r["redirected_from"]
+        if r.get("status") != "active":
+            entry["status"] = r["status"]
+        if baselines:
+            entry["baselines"] = [_card(b) for b in baselines]
+        if extensions:
+            entry["extensions"] = [_card(e) for e in extensions]
+            if r.get("total_extensions", 0) > len(extensions):
+                entry["total_extensions"] = r["total_extensions"]
+        entries.append(entry)
+    return entries, footprint
+
+
+def pending_approval(ws: "Workspace") -> list[dict[str, Any]]:
+    out = []
+    for path, entry in ws.staging.entries().items():
+        reason = entry.get("requires_approval")
+        if reason:
+            out.append({"id": path, "op": entry.get("op", "write"), "reason": reason})
+    return out
+
+
+def is_empty_workspace(ws: "Workspace", table: "MountTable") -> bool:
+    """True when only ``@overlay`` is mounted, no cards are indexed, and nothing is staged."""
+    if len(table.all()) > 1 or ws.staging.entries():
+        return False
+    return ws.index.conn.execute("SELECT 1 FROM cards LIMIT 1").fetchone() is None
+
+
+def snapshot(ws: "Workspace", table: "MountTable") -> dict[str, Any]:
+    """The boot set for a caller that already holds the workspace lock."""
+    entries, _ = collect(query._Ctx(ws, table, True))
+    out: dict[str, Any] = {"cards": entries, "total": len(entries)}
+    pending = pending_approval(ws)
+    if pending:
+        out["pending_approval"] = pending
+    if not entries and is_empty_workspace(ws, table):
+        out["empty_workspace"] = True
+    return out
+
+
+def boot(ws: "Workspace") -> dict[str, Any]:
+    with ws._reading() as table:
+        return snapshot(ws, table)
+
+
+def fingerprint(entry: dict[str, Any]) -> str:
+    return hashlib.sha256(json.dumps(entry, sort_keys=True, ensure_ascii=False).encode("utf-8")).hexdigest()
+
+
+def render_markdown(cards: Iterable[dict[str, Any]], header: str = HEADER) -> str:
+    """The boot cards as one Markdown block, ready for a system prompt. Empty when there are none."""
+    out: list[str] = []
+
+    def block(c: dict[str, Any], heading: str) -> None:
+        out.append(f"{heading} {c['title']} ({c['address']})")
+        for part in (c.get("summary", ""), c.get("body", "")):
+            if part.strip():
+                out.append("")
+                out.append(part.strip())
+        out.append("")
+
+    for c in cards:
+        for base in c.get("baselines", []):
+            block(base, "## Baseline:")
+        block(c, "##")
+        for ext in c.get("extensions", []):
+            block(ext, "### Extension:")
+    if not out:
+        return ""
+    prefix = header.rstrip() + "\n\n" if header.strip() else ""
+    return prefix + "\n".join(out).rstrip() + "\n"
+
+
+def protection_reason(
+    ws: "Workspace",
+    table: "MountTable",
+    path: str,
+    texts: Iterable[str | None],
+    load: str | None,
+    lineage: Iterable[tuple[str, str]],
+) -> str | None:
+    """Why a write to ``@overlay/<path>`` changes the always-loaded context (None if it does not).
+
+    ``texts`` are the card's current versions (overlay and staged), ``load`` and ``lineage`` the
+    write's own ``load`` argument and ``extends`` / ``supersedes`` references (named by kind in
+    ``lineage``: ``[("extends", ref), ...]``).
+    """
+    overlay = table.overlay
+    address = format_address(overlay.alias, path)
+    if load == LOAD_ALWAYS:
+        return f"it makes {address} always-loaded"
+    parsed = [parse_card(t) for t in texts if t is not None]
+    if any(p.load == LOAD_ALWAYS for p in parsed):
+        return f"{address} is always-loaded"
+    ctx = query._Ctx(ws, table, True)
+    _, footprint = collect(ctx)
+    if not footprint:
+        return None
+    if address in footprint:
+        return f"{address} is part of the always-loaded context"
+    cats = ws.index.catalogs()
+    refs = list(lineage)
+    for p in parsed:
+        refs += [("extends", raw) for raw in p.extends] + [("supersedes", raw) for raw in p.supersedes]
+    for verb, raw in refs:
+        res = resolve_ref(raw, overlay.alias, cats)
+        if res.resolved and res.address in footprint:
+            return f"it {verb} {res.address}, which is part of the always-loaded context"
+    return None
+
+
+__all__ = [
+    "boot",
+    "snapshot",
+    "collect",
+    "is_empty_workspace",
+    "render_markdown",
+    "protection_reason",
+    "pending_approval",
+    "fingerprint",
+    "HEADER",
+]

mindslice/operations/impact.py

@@ -0,0 +1,98 @@
+"""Inbound impact of retiring a card: who still links to it or extends it.
+
+When ``write()`` supersedes or deletes a card, the cards that ``[[link]]`` to it or ``extends`` it keep
+pointing at the old card: a link whose target names an old value keeps stating that value, and an
+extension keeps resting on a premise that changed. This module lists them, straight from the index
+(plus staged overrides for ``stage=True``), so the caller can update or rebase them. It is pure
+mechanism: no ranking, no judgment about which ones matter. Results are ordered by mount precedence,
+then address, then target, and bounded by ``MAX_AFFECTED`` per list (totals are always reported).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterable
+
+from ..model.addressing import MountCatalog, format_address, resolve_ref
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..model.card import ParsedCard
+    from ..retrieval.index import Index
+
+MAX_AFFECTED = 25
+_KINDS = (("wikilink", "affected_backlinks", "links_to"), ("extends", "affected_extensions", "extends"))
+
+
+def _split(address: str) -> tuple[str, str]:
+    mount, _, path = address.partition("/")
+    return mount, path
+
+
+def supersede_targets(parsed: "ParsedCard", src_mount: str, cats: dict[str, MountCatalog]) -> list[str]:
+    """Resolved addresses of the cards ``parsed`` supersedes, in order, without duplicates."""
+    out: list[str] = []
+    for raw in parsed.supersedes:
+        res = resolve_ref(raw, src_mount, cats)
+        if res.resolved and res.address and res.address not in out:
+            out.append(res.address)
+    return out
+
+
+def inbound_impact(
+    index: "Index",
+    overlay_alias: str,
+    overlay_precedence: int,
+    targets: Iterable[str],
+    *,
+    overrides: dict[str, "ParsedCard | None"] | None = None,
+    cats: dict[str, MountCatalog] | None = None,
+    exclude: Iterable[str] = (),
+    dangling: bool = False,
+) -> dict[str, Any]:
+    """``affected_backlinks`` / ``affected_extensions`` (+ totals) for cards that reference ``targets``.
+
+    ``overrides`` are staged overlay cards (path -> parsed card, None for a staged delete): indexed
+    links from those paths are replaced by the staged versions' own references, resolved with
+    ``cats``. ``exclude`` drops sources (the card being written). ``dangling=True`` matches references
+    that name a target by path but no longer resolve (the target was already deleted).
+    """
+    targets = list(dict.fromkeys(targets))
+    overrides = overrides or {}
+    skip = set(exclude) | set(targets)
+    found: dict[str, dict[tuple[str, str], int]] = {kind: {} for kind, _, _ in _KINDS}
+    for target in targets:
+        mount, path = _split(target)
+        for kind, _, _ in _KINDS:
+            rows = index.dangling_inbound(kind, mount, path) if dangling else index.inbound(kind, mount, path)
+            for r in rows:
+                if r["src_mount"] == overlay_alias and r["src_path"] in overrides:
+                    continue  # superseded by its staged version, handled below
+                src = format_address(r["src_mount"], r["src_path"])
+                if src not in skip:
+                    found[kind][(src, target)] = r["precedence"]
+    if overrides and cats is not None:
+        wanted = set(targets)
+        for path, parsed in overrides.items():
+            src = format_address(overlay_alias, path)
+            if parsed is None or src in skip:
+                continue
+            refs = {"wikilink": parsed.wikilink_targets(), "extends": parsed.extends}
+            for kind, raws in refs.items():
+                for raw in raws:
+                    res = resolve_ref(raw, overlay_alias, cats)
+                    if res.resolved and res.address in wanted:
+                        found[kind][(src, res.address)] = overlay_precedence
+    out: dict[str, Any] = {}
+    for kind, key, field in _KINDS:
+        ordered = sorted(found[kind].items(), key=lambda kv: (-kv[1], kv[0][0], kv[0][1]))
+        items = []
+        for (src, target), _ in ordered[:MAX_AFFECTED]:
+            item: dict[str, Any] = {"address": src, field: target}
+            if _split(src)[0] != overlay_alias:
+                item["read_only"] = True
+            items.append(item)
+        out[key] = items
+        out["total_" + key] = len(ordered)
+    return out
+
+
+__all__ = ["MAX_AFFECTED", "inbound_impact", "supersede_targets"]

mindslice/operations/recovery.py

@@ -0,0 +1,113 @@
+"""Preview and journal a slice-pointer rollback without reverting overlay or staging."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from ..errors import RecoveryError
+from ..model.addressing import normalize_alias
+from ..storage.config import Mount, MountTable, dump_mounts, load_slice_manifest, portable_path
+from ..storage.history import event, file_action, file_sha
+from ..storage.snapshots import inventory
+from .audit import history_path
+from .validation import Report, SliceSource, lint
+
+
+def _issues(ws, table):
+    report = Report(str(ws.root))
+    sources = []
+    for m in table.all():
+        if not m.root.is_dir():
+            report.add('error', 'missing_mount', f'mount {m.alias} has no directory', address=m.alias)
+            continue
+        nested = tuple(o.root for o in table.all() if o.alias != m.alias and m.root in o.root.parents)
+        sources.append(SliceSource(m.alias, m.root, load_slice_manifest(m.root), m.kind, tuple(ws._exclude()) + nested))
+    lint(sources, report)
+    return report.errors + report.warnings
+
+
+def rollback(ws, alias, path=None, *, dry_run=False, revision=None):
+    alias = normalize_alias(alias)
+    with ws._writing() as table:
+        current = table.get(alias)
+        if current is None or current.kind == 'overlay':
+            raise RecoveryError('rollback requires a mounted read-only slice', alias=alias)
+        if path is None:
+            previous = next((e.get('previous_path') for e in reversed(ws.history.events())
+                             if e['event'] == 'baked' and e.get('alias') == alias
+                             and history_path(ws, e['path']) == current.root), None)
+            if not previous:
+                raise RecoveryError('no recorded predecessor for this slice; specify --to /path/to/version', alias=alias)
+            target = history_path(ws, previous)
+        else:
+            target = Path(path).expanduser().absolute()
+        if target == current.root:
+            raise RecoveryError('target is already mounted', path=str(target))
+        if any(target.resolve() == m.root.resolve() for m in table.all()):
+            raise RecoveryError('target is already mounted under another alias', path=str(target))
+        if any(target.resolve() == p.resolve() or target.resolve().is_relative_to(p.resolve())
+               for p in (table.overlay.root, ws.staging.root, ws.cache_dir, ws.history.root)):
+            raise RecoveryError('rollback target must be a slice directory, not live or internal workspace storage')
+        target_files = inventory(target)
+        replacement = Mount(alias, portable_path(ws.root, target), current.precedence, current.role, 'slice', target)
+        projected = MountTable(table.overlay, [replacement if m.alias == alias else m for m in table.mounts])
+        before = _issues(ws, table)
+        after = _issues(ws, projected)
+        def identity(issue):
+            return (issue['code'], issue.get('address'), issue['message'])
+        existing = {identity(i) for i in before}
+        blockers = [i for i in after if identity(i) not in existing and
+                    (i['severity'] == 'error' or i['code'] in ('broken_wikilink', 'unmounted_dependency', 'missing_dependency'))]
+        # A malformed destination is never accepted just because the current version has the same defect.
+        blockers += [i for i in after if i['severity'] == 'error' and
+                     (i.get('address', '').startswith(alias + '/') or
+                      (i.get('file') and Path(i['file']).is_relative_to(target))) and i not in blockers]
+        state = ws.status()
+        overlay = [
+            f"{table.overlay.alias}/{c['path']}" for c in ws.index.all_cards(table.overlay.alias)]
+        plan = {'alias': alias, 'previous_path': str(current.root), 'path': str(target),
+                'version': load_slice_manifest(target).version,
+                'precedence': current.precedence, 'role': current.role,
+                'overlay_preserved': overlay,
+                'overlay_same_paths': [f"{table.overlay.alias}/{r['path']}" for r in ws.index.all_cards(table.overlay.alias)
+                                       if (target / (r['path'] + '.md')).is_file()],
+                'pending_preserved': [i['address'] for i in state['pending_review']['files']],
+                'blockers': blockers, 'warnings': [i for i in after if i not in blockers], 'ready': not blockers,
+                'note': 'Only the slice pointer changes. Existing overlay overrides and pending proposals remain; this does not undo the whole workspace.'}
+        # Bind confirmation to the mount table, destination bytes, all live card bytes, and pending proposals.
+        live_files = {f"{r['mount']}/{r['path']}": file_sha(table.get(r['mount']).root / (r['path'] + '.md'))
+                      for r in ws.index.all_cards()}
+        fingerprint = {'plan': plan, 'target': target_files, 'live': live_files,
+                       'mounts': (ws.root / 'mounts.toml').read_text(encoding='utf-8'),
+                       'staging': inventory(ws.staging.root)}
+        plan['revision'] = hashlib.sha256(json.dumps(fingerprint, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+        if dry_run:
+            return plan
+        if revision is not None and revision != plan['revision']:
+            raise RecoveryError('rollback preview is stale; review the target and remaining overlay again')
+        if blockers:
+            raise RecoveryError('rollback would introduce invalid references or cards; resolve the blockers first', plan=plan)
+        record = event('rolled_back', alias=alias, previous_path=str(current.root), path=str(target), version=plan['version'])
+        guards = [{'path': str(target / name), 'sha256': info['sha256']} for name, info in target_files['files'].items()]
+        ws.history.transact([file_action(ws.root / 'mounts.toml', dump_mounts(projected))], [record], guards=guards)
+        ws._sync(ws._reload_table())
+        return dict(plan, history_event_id=record['event_id'], rolled_back=True)
+
+
+def render_rollback(plan):
+    lines = [f"{plan['alias']}: {plan['previous_path']} -> {plan['path']} (v{plan['version'] or 'unspecified'})",
+             plan['note'], f"Overlay cards retained: {len(plan['overlay_preserved'])}",
+             f"Pending proposals retained: {len(plan['pending_preserved'])}"]
+    for address in plan['overlay_preserved']:
+        lines.append('  Overlay: ' + address)
+    if plan['overlay_same_paths']:
+        lines.append('Overlay cards sharing target paths: ' + ', '.join(plan['overlay_same_paths']))
+        lines.append('Use explain CARD to check which version an unqualified read selects.')
+    for address in plan['pending_preserved']:
+        lines.append('  Pending: ' + address)
+    for issue in plan['blockers']:
+        lines.append('Blocked: ' + issue['message'])
+    for issue in plan['warnings']:
+        lines.append('Warning: ' + issue['message'])
+    return '\n'.join(lines) + '\n'