mindslice 0.1.0__py3-none-any.whl

mindslice/model/lineage.py

@@ -0,0 +1,228 @@
+"""Lineage semantics: trust policies, supersession forwarding and cycle detection."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Callable, Hashable, Iterable, Sequence, TypeVar
+
+from .addressing import format_address, normalize_alias
+from ..errors import InvalidAddressError
+
+N = TypeVar("N", bound=Hashable)
+FollowSpec = bool | Sequence[str] | None
+
+
+class TrustPolicy:
+    """Which ``supersedes`` edges may be followed automatically.
+
+    * ``True``  - every active replacement is trusted (default)
+    * ``False`` - never forward; replacements are only reported
+    * ``["curated", "@team"]`` - trust replacements whose mount ``role`` or ``@alias`` is listed
+    """
+
+    def __init__(self, follow: FollowSpec = True) -> None:
+        if follow is None:
+            follow = True
+        if isinstance(follow, str):
+            follow = [follow]
+        self.all = follow is True
+        self.none = follow is False
+        self.allow: set[str] = set()
+        if not isinstance(follow, bool):
+            for item in follow:
+                item = str(item).strip()
+                if not item:
+                    continue
+                if item.startswith("@"):
+                    try:
+                        item = normalize_alias(item)
+                    except InvalidAddressError:
+                        pass
+                self.allow.add(item)
+
+    def trusts(self, mount: str, role: str) -> bool:
+        if self.all:
+            return True
+        if self.none:
+            return False
+        return mount in self.allow or role in self.allow
+
+
+@dataclass
+class Forward:
+    """Result of following trusted ``supersedes`` edges from a starting node.
+
+    ``node`` is where a read lands: the unique terminal replacement, or - when
+    replacements compete - the fork point reached by following the unambiguous
+    part of the chain (``start`` itself if it is directly contested or on a cycle).
+    """
+
+    start: str
+    node: str
+    terminals: list[str] = field(default_factory=list)
+    path: list[str] = field(default_factory=list)  # start -> ... -> node
+    superseded: set[str] = field(default_factory=set)  # nodes passed through before ``node``
+    competing: bool = False
+    cycle: bool = False
+
+    @property
+    def redirected(self) -> bool:
+        return self.node != self.start
+
+    @property
+    def terminal(self) -> str | None:
+        return None if (self.competing or self.cycle) else self.node
+
+
+class LineageView:
+    """Per-request lineage queries over an index (memoized)."""
+
+    def __init__(self, index, policy: TrustPolicy) -> None:
+        self.index = index
+        self.policy = policy
+        self._superseders: dict[str, list[tuple[str, bool, int, int]]] = {}
+
+    @staticmethod
+    def split(address: str) -> tuple[str, str]:
+        mount, _, path = address.partition("/")
+        return mount, path
+
+    def superseders(self, address: str) -> list[tuple[str, bool, int, int]]:
+        """Direct active inbound ``supersedes`` sources: ``(address, trusted, precedence, mtime_ns)``."""
+        if address not in self._superseders:
+            mount, path = self.split(address)
+            rows = self.index.inbound("supersedes", mount, path)
+            self._superseders[address] = [
+                (
+                    format_address(r["src_mount"], r["src_path"]),
+                    self.policy.trusts(r["src_mount"], r["role"]),
+                    r["precedence"],
+                    r["mtime_ns"],
+                )
+                for r in rows
+            ]
+        return self._superseders[address]
+
+    def trusted_superseders(self, address: str) -> list[str]:
+        return [a for a, trusted, _, _ in self.superseders(address) if trusted]
+
+    def untrusted_superseders(self, address: str) -> list[str]:
+        return [a for a, trusted, _, _ in self.superseders(address) if not trusted]
+
+    def all_superseders(self, address: str) -> list[str]:
+        return [a for a, _, _, _ in self.superseders(address)]
+
+    def forward(self, start: str) -> Forward:
+        parent: dict[str, str] = {}
+        seen = {start}
+        queue = deque([start])
+        order: dict[str, tuple[int, int]] = {}
+        while queue:
+            node = queue.popleft()
+            for addr, trusted, precedence, mtime in self.superseders(node):
+                if not trusted or addr in seen:
+                    continue
+                seen.add(addr)
+                parent[addr] = node
+                order[addr] = (precedence, mtime)
+                queue.append(addr)
+        reached = seen - {start}
+        if not reached:
+            return Forward(start, start, [start], [start], set())
+        terminals = [n for n in reached if not self.trusted_superseders(n)]
+        terminals.sort(key=lambda a: (-order[a][0], a))
+        if not terminals:
+            return Forward(start, start, [], [start], set(), cycle=True)
+        if len(terminals) > 1:
+            # Follow the chain while it is unambiguous; stop at the fork.
+            path = [start]
+            while True:
+                nxt = self.trusted_superseders(path[-1])
+                if len(nxt) != 1 or nxt[0] in path:
+                    break
+                path.append(nxt[0])
+            return Forward(start, path[-1], terminals, path, set(path[:-1]), competing=True)
+        terminal = terminals[0]
+        path = [terminal]
+        while path[-1] != start:
+            path.append(parent[path[-1]])
+        path.reverse()
+        return Forward(start, terminal, [terminal], path, seen - {terminal})
+
+
+# ---------------------------------------------------------------------------
+# Graph algorithms
+# ---------------------------------------------------------------------------
+
+
+def cycle_through(start: N, successors: Callable[[N], Iterable[N]]) -> list[N] | None:
+    """Return a cycle ``[start, ..., start]`` if ``start`` can reach itself, else None."""
+    parent: dict[N, N] = {}
+    queue: deque[N] = deque()
+    for nxt in successors(start):
+        if nxt not in parent:
+            parent[nxt] = start
+            queue.append(nxt)
+    while queue:
+        node = queue.popleft()
+        if node == start:
+            chain: list[N] = []
+            cur = parent[start]
+            while cur != start:
+                chain.append(cur)
+                cur = parent[cur]
+            return [start, *reversed(chain), start]
+        for nxt in successors(node):
+            if nxt not in parent:
+                parent[nxt] = node
+                queue.append(nxt)
+    return None
+
+
+def strongly_connected_cycles(nodes: Iterable[N], successors: Callable[[N], Iterable[N]]) -> list[list[N]]:
+    """Tarjan's algorithm (iterative); returns SCCs that contain a cycle."""
+    index_of: dict[N, int] = {}
+    low: dict[N, int] = {}
+    on_stack: set[N] = set()
+    stack: list[N] = []
+    result: list[list[N]] = []
+    counter = 0
+    for root in nodes:
+        if root in index_of:
+            continue
+        work: list[tuple[N, Iterable[N]]] = [(root, iter(list(successors(root))))]
+        index_of[root] = low[root] = counter
+        counter += 1
+        stack.append(root)
+        on_stack.add(root)
+        while work:
+            node, it = work[-1]
+            advanced = False
+            for nxt in it:
+                if nxt not in index_of:
+                    index_of[nxt] = low[nxt] = counter
+                    counter += 1
+                    stack.append(nxt)
+                    on_stack.add(nxt)
+                    work.append((nxt, iter(list(successors(nxt)))))
+                    advanced = True
+                    break
+                if nxt in on_stack:
+                    low[node] = min(low[node], index_of[nxt])
+            if advanced:
+                continue
+            work.pop()
+            if work:
+                low[work[-1][0]] = min(low[work[-1][0]], low[node])
+            if low[node] == index_of[node]:
+                comp: list[N] = []
+                while True:
+                    member = stack.pop()
+                    on_stack.discard(member)
+                    comp.append(member)
+                    if member == node:
+                        break
+                if len(comp) > 1 or node in set(successors(node)):
+                    result.append(sorted(comp, key=str))
+    return result

mindslice/model/text.py

@@ -0,0 +1,19 @@
+"""Shared Unicode normalization for card text and exact-match keys."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+# Default-ignorable characters that must not change what text matches.
+_IGNORABLE = re.compile("[­​-‍⁠︀-️\U000e0100-\U000e01ef]")
+
+
+def normalize(text: str) -> str:
+    """Search-side normalization: drop ignorable characters, then NFKC."""
+    return unicodedata.normalize("NFKC", _IGNORABLE.sub("", text or ""))
+
+
+def fold(text: str) -> str:
+    """Normalization for exact-match keys (aliases, tags): NFKC + case folding + whitespace."""
+    return " ".join(normalize(text).casefold().split())

mindslice/model/tomlfmt.py

@@ -0,0 +1,129 @@
+"""Minimal, verified TOML v1.0 serializer for MindSlice's flat schemas.
+
+``tomllib`` only parses, so MindSlice ships its own writer for the two shapes
+it emits: card frontmatter (``str`` / ``list[str]`` values) and manifests such
+as ``mounts.toml`` / ``slice.toml`` (which additionally use ``int`` / ``bool``
+values and tables).
+
+Strings are emitted as UTF-8 directly (never as UTF-16 surrogate escapes the
+way ``json.dumps`` would), with the TOML short escapes for ``\\ \" \\b \\t \\n
+\\f \\r`` and 4-digit ``\\uXXXX`` scalars for the remaining control characters
+(U+0000-U+001F, U+007F). Every document produced here is re-parsed with
+``tomllib.loads()`` and compared against its input before it is returned.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from typing import Any, Mapping
+
+from ..errors import FrontmatterError
+
+_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+_SHORT_ESCAPES = {
+    "\\": "\\\\",
+    '"': '\\"',
+    "\b": "\\b",
+    "\t": "\\t",
+    "\n": "\\n",
+    "\f": "\\f",
+    "\r": "\\r",
+}
+
+
+def escape_string(value: str) -> str:
+    """Return ``value`` as a TOML basic string literal (including quotes)."""
+    out = ['"']
+    for ch in value:
+        code = ord(ch)
+        if ch in _SHORT_ESCAPES:
+            out.append(_SHORT_ESCAPES[ch])
+        elif code < 0x20 or code == 0x7F:
+            out.append(f"\\u{code:04X}")
+        elif 0xD800 <= code <= 0xDFFF:
+            raise FrontmatterError(f"lone UTF-16 surrogate U+{code:04X} cannot be encoded in TOML")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def format_key(key: str) -> str:
+    if not isinstance(key, str) or not key:
+        raise FrontmatterError(f"invalid TOML key: {key!r}")
+    return key if _BARE_KEY.match(key) else escape_string(key)
+
+
+def format_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        return escape_string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ", ".join(format_value(v) for v in value) + "]"
+    raise FrontmatterError(f"unsupported TOML value type: {type(value).__name__}")
+
+
+def _verify(text: str, expected: Mapping[str, Any]) -> str:
+    try:
+        parsed = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:  # pragma: no cover - defensive
+        raise FrontmatterError(f"serializer produced invalid TOML: {exc}") from exc
+    if parsed != _normalize(expected):
+        raise FrontmatterError("TOML round-trip verification failed")
+    return text
+
+
+def _normalize(obj: Any) -> Any:
+    if isinstance(obj, Mapping):
+        return {k: _normalize(v) for k, v in obj.items()}
+    if isinstance(obj, tuple):
+        return [_normalize(v) for v in obj]
+    if isinstance(obj, list):
+        return [_normalize(v) for v in obj]
+    return obj
+
+
+def dumps_flat(data: Mapping[str, Any]) -> str:
+    """Serialize a flat mapping of scalars / lists of scalars (card frontmatter)."""
+    lines = []
+    for key, value in data.items():
+        if isinstance(value, Mapping):
+            raise FrontmatterError(f"frontmatter key {key!r} must be flat (got a table)")
+        lines.append(f"{format_key(key)} = {format_value(value)}")
+    text = "\n".join(lines) + ("\n" if lines else "")
+    return _verify(text, data)
+
+
+def dumps_document(
+    top: Mapping[str, Any] | None = None,
+    tables: Mapping[str, Mapping[str, Any]] | None = None,
+    array_tables: Mapping[str, list[Mapping[str, Any]]] | None = None,
+    header: str | None = None,
+) -> str:
+    """Serialize a document made of top-level keys, ``[tables]`` and ``[[array tables]]``."""
+    top = dict(top or {})
+    tables = dict(tables or {})
+    array_tables = dict(array_tables or {})
+    chunks: list[str] = []
+    if header:
+        chunks.append("".join(f"# {line}\n" if line else "#\n" for line in header.splitlines()))
+    if top:
+        chunks.append("".join(f"{format_key(k)} = {format_value(v)}\n" for k, v in top.items()))
+    for name, body in tables.items():
+        lines = [f"[{format_key(name)}]"]
+        lines += [f"{format_key(k)} = {format_value(v)}" for k, v in body.items()]
+        chunks.append("\n".join(lines) + "\n")
+    for name, items in array_tables.items():
+        for body in items:
+            lines = [f"[[{format_key(name)}]]"]
+            lines += [f"{format_key(k)} = {format_value(v)}" for k, v in body.items()]
+            chunks.append("\n".join(lines) + "\n")
+    text = "\n".join(chunks)
+    expected: dict[str, Any] = dict(top)
+    expected.update({k: dict(v) for k, v in tables.items()})
+    expected.update({k: [dict(i) for i in v] for k, v in array_tables.items() if v})
+    return _verify(text, expected)

mindslice/operations/__init__.py

@@ -0,0 +1 @@
+"""Workspace memory operations, staging, startup context and validation."""

mindslice/operations/audit.py

@@ -0,0 +1,195 @@
+"""Human-facing history and read explanations, without guessing unrecorded reasons."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors import AmbiguousAddressError, NotFoundError
+from ..model.addressing import format_address, parse_address
+from ..retrieval import query
+
+
+def history_path(ws, path, records=None):
+    """Translate old absolute version pointers after a portable workspace restore."""
+    raw = str(path).replace('\\', '/').rstrip('/')
+    for record in reversed(ws.history.events() if records is None else records):
+        if record['event'] != 'restored':
+            continue
+        for source, relative in sorted(record.get('path_map', {}).items(), key=lambda x: -len(x[0])):
+            source = source.replace('\\', '/').rstrip('/')
+            if raw == source or raw.startswith(source + '/'):
+                return ws.root / relative / raw[len(source):].lstrip('/')
+    return Path(path)
+
+
+def _baked_revision(ws, root, path, sha, records):
+    """Follow a bake's parent for unchanged cards; a recorded mismatch ends attribution."""
+    versions = {str(history_path(ws, e['path'], records)): e for e in records if e['event'] == 'baked'}
+    seen = set()
+    current = str(root)
+    while current not in seen and current in versions:
+        seen.add(current)
+        e = versions[current]
+        card = next((c for c in e.get('cards', []) if c['target'].partition('/')[2] == path), None)
+        if card:
+            return (True, card['change_ids']) if card['after_sha256'] == sha else (False, [])
+        if not e.get('previous_path'):
+            break
+        current = str(history_path(ws, e['previous_path'], records))
+    return False, []
+
+
+def _event_addresses(record):
+    addresses = {record['address']} if record.get('address') else set()
+    addresses.update(record.get('retired_overlay_cards', []))
+    for card in record.get('cards', []):
+        addresses.update(card[k] for k in ('source', 'target') if card.get(k))
+    return addresses
+
+
+def card_history(ws, address=None, limit=20, offset=0):
+    query._nonneg(limit=limit, offset=offset)
+    with ws._reading() as table:
+        records = ws.history.events()
+        canonical = None
+        physical_versions = set()
+        if address is not None:
+            alias, path = parse_address(address)
+            try:
+                canonical, _ = query._select(query._Ctx(ws, table, False), address)
+                selected_alias, _ = parse_address(canonical)
+                selected_mount = table.get(selected_alias)
+                if selected_mount.kind == 'slice':
+                    version = str(selected_mount.root)
+                    versions = {str(history_path(ws, e['path'], records)): e for e in records if e['event'] == 'baked'}
+                    while version not in physical_versions:
+                        physical_versions.add(version)
+                        previous = versions.get(version, {}).get('previous_path')
+                        if not previous:
+                            break
+                        version = str(history_path(ws, previous, records))
+            except NotFoundError:
+                if alias:
+                    canonical = format_address(alias, path)
+                else:
+                    matches = sorted({a for e in records for a in _event_addresses(e) if a.partition('/')[2] == path})
+                    if len(matches) > 1:
+                        raise AmbiguousAddressError('historical address is ambiguous; use @alias/path', candidates=matches)
+                    canonical = matches[0] if matches else format_address(table.overlay.alias, path)
+        if canonical:
+            def matches(card, record):
+                return canonical in (card.get('source'), card.get('target')) or (
+                    record.get('path') and str(history_path(ws, record['path'], records)) in physical_versions
+                    and card.get('target', '').partition('/')[2] == canonical.partition('/')[2])
+            ids = {e['change_id'] for e in records if e.get('address') == canonical and e.get('change_id')}
+            for e in records:
+                for card in e.get('cards', []):
+                    if matches(card, e):
+                        ids.update(card.get('change_ids', []))
+            filtered = []
+            for e in records:
+                cards = [c for c in e.get('cards', []) if matches(c, e)
+                         or ids.intersection(c.get('change_ids', []))]
+                pointer_change = e['event'] == 'rolled_back' and e.get('alias') == canonical.partition('/')[0]
+                retired = canonical in e.get('retired_overlay_cards', [])
+                if e.get('address') == canonical or e.get('change_id') in ids or cards or pointer_change or retired:
+                    entry = dict(e)
+                    if 'retired_overlay_cards' in entry:
+                        entry['retired_overlay_cards'] = [a for a in e['retired_overlay_cards'] if a == canonical
+                                                         or any(c.get('source') == a for c in cards)]
+                    if 'cards' in e:
+                        entry['cards'] = cards
+                        entry['change_ids'] = list(dict.fromkeys(i for c in cards for i in c.get('change_ids', [])))
+                    filtered.append(entry)
+            records = filtered
+        details = ws.history.details()
+        records = list(reversed(records))
+        page = []
+        for e in records[offset:offset + limit]:
+            entry = dict(e)
+            if 'reason' not in entry and entry.get('change_id') in details:
+                entry['reason'] = details[entry['change_id']].get('reason')
+            if entry.get('change_ids'):
+                entry['changes'] = ws.history.descriptions(entry['change_ids'], records=details)
+            page.append(entry)
+        return {'address': canonical, 'events': page, 'total': len(records), 'offset': offset,
+                'next_offset': query._page(len(records), offset, limit),
+                'content_snapshots': False,
+                'note': 'Metadata history only. External editor changes are not automatically logged; old text requires a slice version or backup.'}
+
+
+def explain(ws, address, follow_supersedes=True, max_extensions=5, extensions_offset=0):
+    query._nonneg(max_extensions=max_extensions, extensions_offset=extensions_offset)
+    with ws._reading() as table:
+        ctx = query._Ctx(ws, table, follow_supersedes)
+        selected, shadows = query._select(ctx, address)
+        result = query.resolve(ctx, address, max_backlinks=0, max_extensions=max_extensions,
+                               extensions_offset=extensions_offset, bump_telemetry=False)
+        records = ws.history.events()
+        sources = []
+        parts = [('selected', ctx.card_payload(selected)), ('resolved', result)]
+        parts += [('baseline', c) for c in result.get('baselines', [])]
+        parts += [('extension', c) for c in result.get('extensions', [])]
+        for role, card in parts:
+            alias, path = parse_address(card['address'])
+            mount = table.get(alias)
+            changes = []
+            matched = False
+            if mount.kind == 'overlay':
+                changes = ws.history.changes_for(card['address'], card['sha256'])
+                matched = bool(changes)
+            else:
+                matched, ids = _baked_revision(ws, mount.root, path, card['sha256'], records)
+                changes = ws.history.descriptions(ids)
+            sources.append({'role': role, 'address': card['address'], 'path': str(mount.root / f'{path}.md'),
+                            'sha256': card['sha256'], 'mount_role': mount.role, 'precedence': mount.precedence,
+                            'revision_recorded': matched, 'changes': changes})
+        notices = {k: result[k] for k in ('status', 'competing_replacements', 'superseded_by_untrusted',
+                   'bypassed_replacements', 'unrebased_extensions', 'baseline_superseded_by', 'missing_baselines') if k in result}
+        return {'requested': address, 'selected': selected, 'resolved': result['address'],
+                'follow_supersedes': follow_supersedes, 'lineage_path': result.get('lineage_path', [selected]),
+                'shadows': shadows, 'sources': sources, 'notices': notices,
+                'total_extensions': result.get('total_extensions', 0),
+                'extensions_next_offset': result.get('extensions_next_offset'),
+                'pending_review': [i['address'] for i in ws.diff()['items'] if i['address'] in {c['address'] for _, c in parts}],
+                'note': 'Selection uses mount precedence, then explicit lineage under the supplied trust policy. '
+                        'Unrecorded revisions have no verified reason; pending edits do not affect this result.'}
+
+
+def render_history(result):
+    lines = [f"History: {result['address'] or 'workspace'} ({result['total']} events; newest first)"]
+    for e in result['events']:
+        lines.append(f"{e['timestamp']}  {e['event']}  {e.get('address', e.get('alias', ''))}")
+        if e.get('reason'):
+            lines.append('  Reason: ' + e['reason'])
+        for c in e.get('changes', []):
+            if c.get('reason'):
+                lines.append('  Reason: ' + c['reason'])
+        for key in ('previous_path', 'path'):
+            if e.get(key):
+                lines.append(f"  {key}: {e[key]}")
+    if result['next_offset'] is not None:
+        lines.append(f"More events: --offset {result['next_offset']}")
+    return '\n'.join(lines + [result['note']]) + '\n'
+
+
+def render_explain(result):
+    lines = [f"Selected: {result['selected']}", f"Resolved: {result['resolved']}",
+             'Lineage: ' + ' -> '.join(result['lineage_path'])]
+    if result['shadows']:
+        lines.append('Shadows: ' + ', '.join(result['shadows']))
+    for source in result['sources']:
+        if source['role'] == 'selected' and result['selected'] == result['resolved']:
+            continue
+        lines.append(f"{source['role']}: {source['address']} ({source['path']}; precedence={source['precedence']}, role={source['mount_role']})")
+        for change in source['changes']:
+            if change.get('reason'):
+                lines.append('  Reason: ' + change['reason'])
+        if not source['revision_recorded']:
+            lines.append('  No history record matching these current bytes.')
+    if result['pending_review']:
+        lines.append('Pending, not active: ' + ', '.join(result['pending_review']))
+    for name, value in result['notices'].items():
+        lines.append(f'{name}: {value}')
+    if result['extensions_next_offset'] is not None:
+        lines.append(f"More extensions: --extensions-offset {result['extensions_next_offset']}")
+    return '\n'.join(lines + [result['note']]) + '\n'