create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/prime/egregore_runtime/graph.py

@@ -0,0 +1,356 @@
+"""Optional graph projection adapter for the Egregore Runtime.
+
+The graph is a disposable projection of canonical Markdown.  This module never
+reads graph values back into canonical artifacts and never enables the graph by
+configuration discovery: callers must explicitly request the legacy adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+import json
+from pathlib import Path
+import re
+import subprocess
+from typing import Callable, Sequence
+
+from .contracts import CanonicalArtifact, GraphProjectionHealth
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+CommandRunner = Callable[[Sequence[str], Path, int], CommandResult]
+
+
+def _run(command: Sequence[str], cwd: Path, timeout: int) -> CommandResult:
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+    return CommandResult(completed.returncode, completed.stdout, completed.stderr)
+
+
+def _canonical_inventory(memory_root: Path) -> dict[str, str]:
+    if not memory_root.is_dir():
+        return {}
+    return {
+        f"memory/{path.relative_to(memory_root).as_posix()}": sha256(
+            path.read_bytes()
+        ).hexdigest()
+        for path in sorted(memory_root.rglob("*.md"))
+        if path.is_file()
+    }
+
+
+def _projection_inventory(memory_root: Path) -> dict[str, str]:
+    """Inventory only canonical families covered by the legacy projector."""
+
+    inventory = _canonical_inventory(memory_root)
+    projected_prefixes = (
+        "memory/handoffs/",
+        "memory/wraps/",
+        "memory/knowledge/decisions/",
+        "memory/knowledge/findings/",
+        "memory/knowledge/patterns/",
+        "memory/knowledge/research/",
+        "memory/artifacts/",
+        "memory/quests/",
+    )
+    return {
+        path: digest
+        for path, digest in inventory.items()
+        if path.startswith(projected_prefixes)
+        and Path(path).name not in {"index.md", "index.md.bak"}
+    }
+
+
+def _snapshot_revision(inventory: dict[str, str]) -> str:
+    payload = json.dumps(inventory, sort_keys=True, separators=(",", ":"))
+    return f"snapshot:{sha256(payload.encode()).hexdigest()}"
+
+
+def _canonical_revision(root: Path, memory_root: Path) -> str:
+    completed = subprocess.run(
+        ["git", "-C", str(memory_root), "rev-parse", "HEAD"],
+        cwd=root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    revision = completed.stdout.strip()
+    if completed.returncode == 0 and revision:
+        status = subprocess.run(
+            ["git", "-C", str(memory_root), "status", "--porcelain"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if status.returncode == 0 and status.stdout.strip():
+            snapshot = _snapshot_revision(_canonical_inventory(memory_root))
+            return f"{revision}+dirty:{snapshot.removeprefix('snapshot:')[:12]}"
+        return revision
+    return _snapshot_revision(_canonical_inventory(memory_root))
+
+
+def _declared_content_hash(path: Path) -> str | None:
+    """Read a canonical v1 hash without treating arbitrary body text as schema."""
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    if not text.startswith("---\n"):
+        return None
+    frontmatter = text[4:].split("\n---", 1)[0]
+    match = re.search(
+        r"(?m)^(?:content_hash|contentHash):\s*['\"]?([a-fA-F0-9]{32,128})['\"]?\s*$",
+        frontmatter,
+    )
+    return match.group(1).lower() if match else None
+
+
+def _canonical_path(raw_path: str, memory_root: Path) -> str | None:
+    """Normalize graph file pointers without allowing paths outside memory/."""
+
+    value = raw_path.strip().replace("\\", "/")
+    if not value:
+        return None
+    resolved_prefix = memory_root.resolve().as_posix().rstrip("/") + "/"
+    if value.startswith(resolved_prefix):
+        value = "memory/" + value[len(resolved_prefix) :]
+    elif Path(value).is_absolute():
+        return None
+    elif value.startswith("qmd://"):
+        parts = value.split("/", 3)
+        value = "memory/" + parts[3] if len(parts) == 4 else ""
+    elif not value.startswith("memory/"):
+        value = "memory/" + value.lstrip("/")
+    relative = value.removeprefix("memory/")
+    if not relative or ".." in Path(relative).parts:
+        return None
+    return "memory/" + Path(relative).as_posix()
+
+
+class DisabledGraphProjection:
+    """Safe default: a complete no-op with explicit health reporting."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root.resolve()
+        self.memory_root = (self.root / "memory").resolve()
+
+    def health(self) -> GraphProjectionHealth:
+        return GraphProjectionHealth(
+            enabled=False,
+            adapter="disabled",
+            projection_revision=None,
+            canonical_revision=_canonical_revision(self.root, self.memory_root),
+            coverage=None,
+            consistent=None,
+            warnings=(
+                "graph projection is disabled; canonical Markdown is authoritative",
+            ),
+        )
+
+    def project(
+        self, artifacts: Sequence[CanonicalArtifact]
+    ) -> GraphProjectionHealth:
+        del artifacts
+        return self.health()
+
+    def rebuild(self) -> GraphProjectionHealth:
+        return self.health()
+
+    def verify(self) -> GraphProjectionHealth:
+        return self.health()
+
+
+class LegacyGraphProjection:
+    """Explicit compatibility adapter over the preserved graph shell tools.
+
+    `project` currently delegates to the repository-wide idempotent projector
+    because the legacy implementation does not expose an artifact-scoped
+    operation.  Inputs are nevertheless checked against canonical memory first.
+    """
+
+    _INVENTORY_QUERY = """MATCH (n)
+WHERE n.filePath IS NOT NULL
+RETURN n.filePath AS path,
+       coalesce(n.contentHash, '') AS contentHash,
+       coalesce(n.canonicalRevision, n.gitRevision, n.commit, '') AS canonicalRevision
+ORDER BY path"""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        runner: CommandRunner | None = None,
+        timeout: int = 120,
+    ) -> None:
+        self.root = root.resolve()
+        self.memory_root = (self.root / "memory").resolve()
+        self.runner = runner or _run
+        self.timeout = timeout
+
+    def _base_health(self, *warnings: str) -> GraphProjectionHealth:
+        return GraphProjectionHealth(
+            enabled=True,
+            adapter="legacy-shell-v1",
+            projection_revision=None,
+            canonical_revision=_canonical_revision(self.root, self.memory_root),
+            coverage=None,
+            consistent=None,
+            warnings=tuple(warnings),
+        )
+
+    def _inventory(self) -> tuple[dict[str, tuple[str, str]], tuple[str, ...]]:
+        result = self.runner(
+            ["bash", "bin/graph.sh", "query", self._INVENTORY_QUERY],
+            self.root,
+            self.timeout,
+        )
+        if result.returncode != 0:
+            detail = (result.stderr or result.stdout).strip()
+            return {}, (f"graph projection unavailable: {detail or 'query failed'}",)
+        try:
+            payload = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            return {}, ("graph projection returned an invalid health response",)
+        if "values" not in payload:
+            reason = payload.get("reason") or "no projection inventory envelope"
+            return {}, (f"graph projection unavailable: {reason}",)
+
+        entries: dict[str, tuple[str, str]] = {}
+        for row in payload.get("values", []):
+            if not isinstance(row, list) or not row:
+                continue
+            path = _canonical_path(str(row[0] or ""), self.memory_root)
+            if path is None:
+                continue
+            content_hash = str(row[1] or "") if len(row) > 1 else ""
+            revision = str(row[2] or "") if len(row) > 2 else ""
+            entries[path] = (content_hash, revision)
+        return entries, ()
+
+    def health(self) -> GraphProjectionHealth:
+        return self.verify()
+
+    def verify(self) -> GraphProjectionHealth:
+        canonical = _projection_inventory(self.memory_root)
+        canonical_revision = _canonical_revision(self.root, self.memory_root)
+        projected, warnings = self._inventory()
+        if warnings:
+            return self._base_health(*warnings)
+
+        canonical_paths = set(canonical)
+        projected_paths = set(projected)
+        present = canonical_paths & projected_paths
+        coverage = len(present) / len(canonical_paths) if canonical_paths else 1.0
+        missing = canonical_paths - projected_paths
+        extra = projected_paths - canonical_paths
+        declared_hashes = {
+            path: _declared_content_hash(self.root / path)
+            for path in present
+        }
+        comparable = {
+            path
+            for path in present
+            if projected[path][0] and declared_hashes[path]
+        }
+        mismatched = {
+            path
+            for path in comparable
+            if projected[path][0].lower() != declared_hashes[path]
+        }
+        consistent = None if not comparable else not mismatched
+
+        graph_shape = {
+            path: {"content_hash": values[0], "canonical_revision": values[1]}
+            for path, values in sorted(projected.items())
+        }
+        graph_payload = json.dumps(graph_shape, sort_keys=True, separators=(",", ":"))
+        projection_revision = f"graph:{sha256(graph_payload.encode()).hexdigest()}"
+
+        notices = list(warnings)
+        if missing:
+            notices.append(f"projection missing {len(missing)} canonical artifact(s)")
+        if extra:
+            notices.append(
+                f"projection has {len(extra)} path(s) without canonical artifacts; ignored"
+            )
+        if mismatched:
+            notices.append(
+                f"projection disagrees with {len(mismatched)} canonical artifact(s); canonical wins"
+            )
+        projected_revisions = {
+            revision for _, revision in projected.values() if revision
+        }
+        if projected_revisions and canonical_revision not in projected_revisions:
+            notices.append("projection source revision differs from canonical revision")
+
+        return GraphProjectionHealth(
+            enabled=True,
+            adapter="legacy-shell-v1",
+            projection_revision=projection_revision,
+            canonical_revision=canonical_revision,
+            coverage=coverage,
+            consistent=consistent,
+            warnings=tuple(notices),
+        )
+
+    def _validate_artifacts(self, artifacts: Sequence[CanonicalArtifact]) -> None:
+        for artifact in artifacts:
+            relative = artifact.canonical_path.removeprefix("memory/")
+            candidate = (self.memory_root / relative).resolve()
+            if self.memory_root not in candidate.parents:
+                raise ValueError(
+                    f"artifact {artifact.artifact_id!r} is outside canonical memory"
+                )
+            if not candidate.is_file():
+                raise ValueError(
+                    f"artifact {artifact.artifact_id!r} has no canonical file"
+                )
+
+    def project(
+        self, artifacts: Sequence[CanonicalArtifact]
+    ) -> GraphProjectionHealth:
+        self._validate_artifacts(artifacts)
+        return self._sync("project")
+
+    def rebuild(self) -> GraphProjectionHealth:
+        return self._sync("rebuild")
+
+    def _sync(self, operation: str) -> GraphProjectionHealth:
+        result = self.runner(
+            ["bash", "bin/sync-graph.sh"], self.root, self.timeout
+        )
+        if result.returncode != 0:
+            detail = (result.stderr or result.stdout).strip()
+            return self._base_health(
+                f"graph {operation} failed: {detail or 'sync-graph exited nonzero'}",
+                "canonical Markdown was preserved and remains authoritative",
+            )
+        return self.verify()
+
+
+def graph_projection(
+    root: Path,
+    *,
+    enabled: bool = False,
+    runner: CommandRunner | None = None,
+) -> DisabledGraphProjection | LegacyGraphProjection:
+    """Build the projection adapter; callers must opt in on every construction."""
+
+    if not enabled:
+        return DisabledGraphProjection(root)
+    return LegacyGraphProjection(root, runner=runner)

package/runtime/prime/egregore_runtime/handoff_lookup.py

@@ -0,0 +1,196 @@
+"""Deterministic lifecycle lookup for exact handoff questions.
+
+QMD answers fuzzy topical recall; this service answers exact
+organizational-state questions — "latest handoff addressed to me", "oldest
+unresolved handoff", "what did I last hand off to X" — as a typed operation
+over canonical artifact metadata. No QMD, no graph, no ranking: iterate the
+canonical handoff repository, filter by stable identity, order by canonical
+creation time with a deterministic tie-breaker.
+
+Identity: "me" is the resolved ActorContext. The stable actor id matches
+``created_by``/``to_actor_id`` directly; addressing fields written as
+handles (``to: oz``) resolve through the actor's own alias set or, for a
+named member, through the organization member presentations — addressing
+resolution, never authorization. Authorization stays with the Runtime READ
+decision, and admin-marked handoffs are withheld from non-admins exactly as
+on every other surface.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from .artifacts import split_frontmatter
+from .contracts import ActorContext, Permission
+from .errors import AuthorizationDenied
+from .identity import organization_member_presentations
+from .policy import scope_allows_path
+from .questions import actor_aliases
+
+_CLOSED_STATUSES = frozenset(
+    {"done", "completed", "closed", "resolved", "superseded", "cancelled", "archived"}
+)
+
+
+@dataclass(frozen=True, slots=True)
+class HandoffRecord:
+    canonical_path: str
+    topic: str
+    sender: str
+    recipient: str
+    status: str
+    occurred_at: str
+    claim: str
+    ask: str
+
+
+def _scalar(fields: Any, *names: str) -> str:
+    for name in names:
+        value = fields.get(name)
+        if value is None:
+            continue
+        if isinstance(value, list):
+            value = ", ".join(str(item) for item in value)
+        text = str(value).strip()
+        if text:
+            return text
+    return ""
+
+
+def _occurred_at(fields: Any, path_stem: str) -> str:
+    created = _scalar(fields, "created_at")
+    if created:
+        return created
+    date = _scalar(fields, "date")
+    if date:
+        # A date-only stamp sorts before any same-day ISO timestamp; suffix
+        # with the day's start so date-only records order stably among
+        # themselves and the path tie-breaker decides within one day.
+        return f"{date}T00:00:00Z"
+    return f"0000-00-00T00:00:00Z:{path_stem}"
+
+
+def _member_terms(root: Path, actor: ActorContext, name: str) -> frozenset[str]:
+    """Stable-identity terms for a NAMED member (addressing resolution)."""
+
+    needle = name.strip().removeprefix("@").casefold()
+    if not needle:
+        return frozenset()
+    for member in organization_member_presentations(root, actor):
+        values = {
+            str(member.display_name).casefold(),
+            *(str(alias).casefold() for alias in member.aliases),
+        }
+        if needle in values:
+            return frozenset(values)
+    return frozenset({needle})
+
+
+def _self_terms(actor: ActorContext) -> frozenset[str]:
+    return frozenset({actor.actor.actor_id.casefold(), *actor_aliases(actor)})
+
+
+class HandoffLookupService:
+    """Typed lifecycle lookup over the canonical handoff repository."""
+
+    def __init__(self, runtime: Any, root: Path):
+        self.runtime = runtime
+        self.root = Path(root)
+        self.memory_root = (self.root / "memory").resolve()
+
+    def query(
+        self,
+        actor: ActorContext,
+        *,
+        addressed_to: str | None = None,
+        sent_by: str | None = None,
+        status_filter: str = "any",
+        order: str = "newest",
+        limit: int = 1,
+    ) -> list[HandoffRecord]:
+        decision = self.runtime.authorize(actor, Permission.READ)
+        if not decision.allowed:
+            raise AuthorizationDenied("; ".join(decision.reasons))
+        scopes = tuple(decision.scopes)
+
+        gate = getattr(self.runtime, "admin_gate", None)
+        admin_visible = True
+        if gate is not None:
+            try:
+                admin_visible = bool(gate.actor_is_admin(actor))
+            except Exception:
+                admin_visible = False
+
+        recipient_terms = self._terms(actor, addressed_to)
+        sender_terms = self._terms(actor, sent_by)
+
+        records: list[tuple[str, str, HandoffRecord]] = []
+        base = self.memory_root / "handoffs"
+        if not base.is_dir():
+            return []
+        for path in base.rglob("*.md"):
+            if path.name.startswith("index"):
+                continue
+            relative = path.relative_to(self.memory_root).as_posix()
+            canonical = f"memory/{relative}"
+            if not scope_allows_path(canonical, scopes):
+                continue
+            if not admin_visible and gate is not None and gate.path_is_admin(canonical):
+                continue
+            try:
+                fields, _ = split_frontmatter(path.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+            status = (_scalar(fields, "status") or "active").casefold()
+            if status_filter in ("open", "unresolved") and status in _CLOSED_STATUSES:
+                continue
+            if recipient_terms is not None:
+                recipient_actor = _scalar(fields, "to_actor_id").casefold()
+                recipient_text = _scalar(fields, "addressed_to", "to").casefold()
+                if recipient_actor:
+                    if recipient_actor not in recipient_terms:
+                        continue
+                elif not self._addressed_match(recipient_text, recipient_terms):
+                    continue
+            if sender_terms is not None:
+                sender_actor = _scalar(fields, "created_by").casefold()
+                sender_text = _scalar(fields, "from", "author").casefold()
+                if sender_actor and sender_actor in sender_terms:
+                    pass
+                elif not self._addressed_match(sender_text, sender_terms):
+                    continue
+            record = HandoffRecord(
+                canonical_path=canonical,
+                topic=_scalar(fields, "topic", "title") or path.stem,
+                sender=_scalar(fields, "from", "author", "created_by") or "unknown",
+                recipient=_scalar(fields, "addressed_to", "to") or "unaddressed",
+                status=status,
+                occurred_at=_occurred_at(fields, path.stem),
+                claim=_scalar(fields, "claim"),
+                ask=_scalar(fields, "ask"),
+            )
+            records.append((record.occurred_at, canonical, record))
+
+        records.sort(key=lambda item: (item[0], item[1]), reverse=(order == "newest"))
+        return [record for _, _, record in records[: max(1, limit)]]
+
+    def _terms(self, actor: ActorContext, who: str | None) -> frozenset[str] | None:
+        if who is None:
+            return None
+        if who.strip().casefold() in ("me", "self", actor.actor.actor_id.casefold()):
+            return _self_terms(actor)
+        return _member_terms(self.root, actor, who)
+
+    @staticmethod
+    def _addressed_match(text: str, terms: frozenset[str]) -> bool:
+        if not text:
+            return False
+        parts = {
+            piece.strip().removeprefix("@").casefold()
+            for chunk in text.split(",")
+            for piece in chunk.split()
+        }
+        parts.add(text.strip().casefold())
+        return bool(parts & terms)