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

package/runtime/codex/egregore_runtime/adapters/qmd_cli.py

@@ -0,0 +1,210 @@
+"""Internal compatibility bridge from ``bin/search.sh`` to the QMD adapter.
+
+This is intentionally not the public Egregore Runtime CLI.  Harness-facing
+commands should use the integrated runtime boundary; this module only keeps the
+existing shell search UX working while QMD details stay inside its adapter.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+from egregore_runtime.adapters.qmd import QmdAdapterError, QmdLocalRetriever
+from egregore_runtime.contracts import EvidenceItem, RetrievalMode, RetrievalRequest
+from egregore_runtime.errors import AuthorizationDenied
+from egregore_runtime.runtime import local_runtime
+
+
+def _root() -> Path:
+    configured = os.environ.get("EGREGORE_ROOT")
+    return Path(configured).resolve() if configured else Path.cwd().resolve()
+
+
+def _config(root: Path) -> dict[str, object]:
+    try:
+        return json.loads((root / "egregore.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _retriever(root: Path) -> QmdLocalRetriever:
+    return QmdLocalRetriever(
+        repository_root=root,
+        memory_root=root / "memory",
+        collection=os.environ.get("EGREGORE_QMD_COLLECTION") or None,
+    )
+
+
+def _request(args: argparse.Namespace, *, org_id: str, actor_id: str) -> RetrievalRequest:
+    lex = tuple(args.lex)
+    vec = tuple(args.vec)
+    if args.mode is RetrievalMode.LEX and not lex:
+        lex = vec
+    if args.mode is RetrievalMode.VEC and not vec:
+        vec = lex
+    return RetrievalRequest(
+        request_id=f"search-{uuid.uuid4()}",
+        org_id=org_id,
+        actor_id=actor_id,
+        task=args.task,
+        lex=lex,
+        vec=vec,
+        top_k=args.limit,
+        mode=args.mode,
+        open_sources=False,
+    )
+
+
+def _render_evidence(evidence: EvidenceItem) -> str:
+    parts = [
+        "---",
+        f"**file:** `{evidence.canonical_path}`",
+        f"**artifact:** `{evidence.artifact_id}`",
+        f"**reason:** {evidence.reason}",
+    ]
+    if evidence.content:
+        parts.extend(("", evidence.content))
+    return "\n".join(parts)
+
+
+def _actor(runtime):
+    return runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid.uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+
+
+def _query(args: argparse.Namespace) -> int:
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    actor = _actor(runtime)
+    context = runtime.observe(
+        actor,
+        _request(args, org_id=actor.profile.org_id, actor_id=actor.actor.actor_id),
+        token_budget=actor.profile.default_context_budget,
+    )
+    if args.json:
+        print(json.dumps(context.to_dict(), indent=2))
+    elif context.evidence:
+        print("\n\n".join(_render_evidence(item) for item in context.evidence))
+    else:
+        print("No results found.")
+    return 0
+
+
+def _status(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).retrieval_health()
+    if args.json:
+        print(json.dumps(health.to_dict(), indent=2))
+    else:
+        print(f"adapter: {health.adapter} {health.adapter_version}")
+        print(f"index spec: {health.index_spec_version}")
+        print(f"index revision: {health.index_revision}")
+        print(f"source revision: {health.source_revision}")
+        print(f"embedding: {health.embedding_state}")
+        print(f"readiness: {health.runtime_state}")
+        print(f"bm25 ready: {'yes' if health.bm25_ready else 'no'}")
+        print(f"semantic ready: {'yes' if health.semantic_ready else 'no'}")
+        print(f"semantic build: {health.semantic_source_revision or 'none'}")
+        print(f"worker pid: {health.runtime_pid or 'none'}")
+        print(f"endpoint: {health.runtime_endpoint or 'none'}")
+        print(f"index: {health.index_path or 'unknown'}")
+        print(f"collection: {health.collection or 'unknown'}")
+        print(f"available: {'yes' if health.available else 'no'}")
+        for warning in health.warnings:
+            print(f"warning: {warning}")
+    return 0 if health.available else 1
+
+
+def _start(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).start_retrieval()
+    print(json.dumps(health.to_dict(), indent=2) if args.json else health.runtime_state)
+    return 0 if health.available and health.bm25_ready else 1
+
+
+def _stop(args: argparse.Namespace) -> int:
+    health = local_runtime(_root(), push_remote=False).shutdown_retrieval()
+    print(json.dumps(health.to_dict(), indent=2) if args.json else "stopped")
+    return 0
+
+
+def _update(args: argparse.Namespace) -> int:
+    retriever = _retriever(_root())
+    health = retriever.update()
+    if args.embed:
+        health = retriever.embed_foreground()
+    print(json.dumps(health.to_dict(), indent=2) if args.json else health.index_revision)
+    return 0
+
+
+def _install(args: argparse.Namespace) -> int:
+    del args
+    print(_retriever(_root()).install_managed())
+    return 0
+
+
+def _open(args: argparse.Namespace) -> int:
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    actor = _actor(runtime)
+    sys.stdout.write(runtime.open_source(actor, args.path))
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-runtime-qmd")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    query = commands.add_parser("query")
+    query.add_argument("--task", required=True)
+    query.add_argument("--lex", action="append", default=[])
+    query.add_argument("--vec", action="append", default=[])
+    query.add_argument("--mode", type=RetrievalMode, default=RetrievalMode.HYBRID)
+    query.add_argument("--limit", type=int, default=6)
+    query.add_argument("--json", action="store_true")
+    query.set_defaults(handler=_query)
+
+    status = commands.add_parser("status")
+    status.add_argument("--json", action="store_true")
+    status.set_defaults(handler=_status)
+
+    start = commands.add_parser("start")
+    start.add_argument("--json", action="store_true")
+    start.set_defaults(handler=_start)
+
+    stop = commands.add_parser("stop")
+    stop.add_argument("--json", action="store_true")
+    stop.set_defaults(handler=_stop)
+
+    update = commands.add_parser("update")
+    update.add_argument("--embed", action="store_true")
+    update.add_argument("--json", action="store_true")
+    update.set_defaults(handler=_update)
+
+    install = commands.add_parser("install")
+    install.set_defaults(handler=_install)
+
+    source = commands.add_parser("open")
+    source.add_argument("path")
+    source.set_defaults(handler=_open)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    if getattr(args, "limit", 1) < 1:
+        raise QmdAdapterError("retrieval limit must be positive")
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (AuthorizationDenied, QmdAdapterError, ValueError) as exc:
+        print(f"search: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc

package/runtime/codex/egregore_runtime/adapters/qmd_embed_worker.py

@@ -0,0 +1,59 @@
+"""Detached embedding worker for an instance-owned QMD Local runtime."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from .qmd import QmdLocalRetriever
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-qmd-embed-worker")
+    parser.add_argument("--repository-root", type=Path, required=True)
+    parser.add_argument("--memory-root", type=Path, required=True)
+    parser.add_argument("--collection", required=True)
+    parser.add_argument("--collection-purpose", required=True)
+    parser.add_argument("--source-revision", required=True)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    retriever = QmdLocalRetriever(
+        repository_root=args.repository_root,
+        memory_root=args.memory_root,
+        collection=args.collection,
+        collection_purpose=args.collection_purpose,
+    )
+    lock = retriever._embed_lock_path()
+    try:
+        # args.source_revision documents the scheduling trigger (visible in
+        # ps output); each cycle embeds whatever update just indexed and
+        # records the covered revision, so convergence needs no target.
+        for _ in range(3):
+            retriever.update()
+            retriever.embed_foreground()
+            if retriever._semantic_state_current():
+                return 0
+            retriever._source_revision_cache = None
+        raise RuntimeError("canonical state changed repeatedly during background embedding")
+    except Exception as exc:  # detached process records a local diagnostic receipt
+        retriever._atomic_json(
+            retriever._runtime_root() / "embedding-error.json",
+            {"pid": os.getpid(), "error_type": type(exc).__name__, "message": str(exc)[:400]},
+        )
+        return 1
+    finally:
+        try:
+            state = json.loads(lock.read_text(encoding="utf-8"))
+            if int(state.get("pid", -1)) == os.getpid():
+                lock.unlink(missing_ok=True)
+        except (OSError, ValueError, TypeError):
+            pass
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/codex/egregore_runtime/admin_gate.py

@@ -0,0 +1,102 @@
+"""Egregore-surface admin-content protection.
+
+``admin: true`` frontmatter gives a canonical document its documented
+meaning: hidden on Egregore surfaces from non-admin members, and refused for
+external publication without an authorized admin's separate confirmation.
+
+This is soft product-layer protection. Every organization member holds full
+repository access and can read raw Git files; nothing here claims per-document
+filesystem confidentiality, and no surface may describe it as an ACL. What it
+guarantees is that Egregore itself — retrieval evidence, Observe context,
+source opening, listings, rendering, publication — never hands admin-marked
+content to a non-admin member, exposing at most an opaque withheld count.
+
+Admin capability derives from stable identity: the resolved actor's
+``github.username`` alias (recorded by onboarding into the identity state)
+matched against the organization's configured ``admins`` list. Display names,
+the ``legacy.person`` alias, Git configuration, OS usernames, branch names,
+and paths never participate. Every error path fails closed to non-admin.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+_FRONTMATTER_ADMIN = re.compile(r"^\s*admin:\s*[\"']?true[\"']?\s*$", re.MULTILINE)
+_HEAD_BYTES = 4096
+
+
+def document_is_admin(text: str) -> bool:
+    """True when the document's YAML frontmatter declares ``admin: true``."""
+
+    if not text.startswith("---"):
+        return False
+    end = text.find("\n---", 3)
+    head = text[3:end] if end != -1 else text[3:_HEAD_BYTES]
+    return bool(_FRONTMATTER_ADMIN.search(head))
+
+
+@dataclass
+class AdminGate:
+    config_path: Path
+    memory_root: Path
+    _flag_cache: dict[str, tuple[int, int, bool]] = field(default_factory=dict)
+
+    def admin_handles(self) -> frozenset[str]:
+        try:
+            config: Any = json.loads(self.config_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return frozenset()
+        handles = config.get("admins") if isinstance(config, dict) else None
+        if not isinstance(handles, list):
+            return frozenset()
+        return frozenset(
+            str(handle).strip().casefold()
+            for handle in handles
+            if str(handle).strip()
+        )
+
+    def actor_is_admin(self, actor: Any) -> bool:
+        """Stable-identity admin check — github.username alias only."""
+
+        handles = self.admin_handles()
+        if not handles:
+            return False
+        try:
+            aliases = getattr(actor.actor, "aliases", None) or {}
+            handle = aliases.get("github.username") if isinstance(aliases, dict) else None
+        except AttributeError:
+            return False
+        if not handle:
+            return False
+        return str(handle).strip().casefold() in handles
+
+    def path_is_admin(self, canonical_path: str) -> bool:
+        """True when the canonical document at ``memory/...`` is admin-marked.
+
+        Unreadable or missing files report False — absence of evidence is not
+        an admin marking, and the surrounding authorization already decided
+        whether the path may be read at all.
+        """
+
+        relative = canonical_path.strip().replace("\\", "/").removeprefix("memory/")
+        target = self.memory_root / relative
+        try:
+            stat = target.stat()
+        except OSError:
+            return False
+        cached = self._flag_cache.get(relative)
+        if cached and cached[0] == stat.st_mtime_ns and cached[1] == stat.st_size:
+            return cached[2]
+        try:
+            with target.open("r", encoding="utf-8", errors="replace") as handle:
+                head = handle.read(_HEAD_BYTES)
+        except OSError:
+            return False
+        flag = document_is_admin(head)
+        self._flag_cache[relative] = (stat.st_mtime_ns, stat.st_size, flag)
+        return flag