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

package/runtime/claude/egregore_runtime/upgrade_worker.py

@@ -0,0 +1,53 @@
+"""Detached preparation worker for the transactional Runtime upgrade.
+
+Runs the staged engine for one instance with stdio fully detached, so the
+launching surface (Settings, CLI) returns immediately and reconnects later
+through the durable state file. Progress survives the terminal session; an
+interrupted run resumes completed stages instead of restarting them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-runtime-upgrade-worker")
+    parser.add_argument("--repository-root", type=Path, required=True)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    root = args.repository_root.resolve()
+
+    from .adapters.qmd import QmdLocalRetriever
+    from .runtime import local_runtime
+    from .upgrade import UpgradeEngine, UpgradeStore, upgrade_root
+
+    store = UpgradeStore(root=upgrade_root(root))
+    engine = UpgradeEngine(
+        repository_root=root,
+        store=store,
+        runtime=local_runtime(root, push_remote=False),
+        retriever=QmdLocalRetriever(repository_root=root),
+    )
+    try:
+        state = engine.prepare()
+    except Exception as exc:  # a detached process records, never raises
+        current = store.load()
+        if current is not None:
+            current["status"] = "failed"
+            current["failure"] = {
+                "stage": "worker",
+                "message": f"{type(exc).__name__}: {exc}"[:300],
+            }
+            store.write(current)
+        return 1
+    return 0 if state.get("status") in ("ready-to-activate", "active") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/claude/egregore_runtime/writeback.py

@@ -0,0 +1,391 @@
+"""Canonical artifact writeback orchestration.
+
+The orchestrator deliberately knows only domain protocols.  Git, QMD, graph,
+and telemetry implementations stay behind their respective adapters.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import replace
+from datetime import UTC, datetime
+from typing import Callable, Sequence
+
+from .artifacts import (
+    ARTIFACT_SCHEMA_VERSION,
+    CanonicalArtifactStore,
+    CanonicalDocument,
+    artifact_id_from_path,
+    canonical_relative_path,
+    content_digest,
+    validate_artifact,
+)
+from .contracts import (
+    ActionAuthorizer,
+    ActorContext,
+    CanonicalArtifact,
+    GraphProjection,
+    Permission,
+    Retriever,
+    SyncTransport,
+    TelemetryEvent,
+    TelemetrySink,
+    WritebackEvent,
+    WritebackStatus,
+)
+from .telemetry import TELEMETRY_SCHEMA_VERSION
+from .policy import scope_allows_path
+
+
+class CanonicalArtifactWriteback:
+    """Authorize and persist canonical state, then update disposable projections."""
+
+    def __init__(
+        self,
+        *,
+        authorizer: ActionAuthorizer,
+        store: CanonicalArtifactStore,
+        sync_transport: SyncTransport,
+        retriever: Retriever,
+        telemetry: TelemetrySink,
+        graph: GraphProjection | None = None,
+        clock: Callable[[], datetime] | None = None,
+        id_factory: Callable[[], str] | None = None,
+    ) -> None:
+        self.authorizer = authorizer
+        self.store = store
+        self.sync_transport = sync_transport
+        self.retriever = retriever
+        self.telemetry = telemetry
+        self.graph = graph
+        self.clock = clock or (lambda: datetime.now(UTC))
+        self.id_factory = id_factory or (lambda: f"writeback-{uuid.uuid4().hex}")
+
+    def _event_id(self) -> str:
+        return self.id_factory()
+
+    def _emit(
+        self,
+        *,
+        actor: ActorContext,
+        event_id: str,
+        artifact_id: str,
+        status: WritebackStatus,
+        warning_count: int,
+    ) -> None:
+        self.telemetry.emit(
+            TelemetryEvent(
+                schema_version=TELEMETRY_SCHEMA_VERSION,
+                event_id=f"telemetry-{event_id}",
+                event_type=f"writeback.{status.value}",
+                occurred_at=self.clock(),
+                org_id=actor.profile.org_id,
+                actor_id=actor.actor.actor_id,
+                session_id=actor.session_id,
+                org_revision=actor.profile.revision,
+                metrics={
+                    "count": warning_count,
+                    "writeback_result": status.value,
+                    "success": status is WritebackStatus.ACCEPTED,
+                },
+                artifact_ids=(artifact_id,) if artifact_id else (),
+            )
+        )
+
+    def _prepare(
+        self,
+        actor: ActorContext,
+        artifact: CanonicalArtifact,
+        content: str,
+        *,
+        policy_hints: dict[str, object] | None = None,
+        source_document: CanonicalDocument | None = None,
+    ) -> CanonicalDocument:
+        if artifact.org_id != actor.profile.org_id:
+            raise ValueError("artifact organization does not match the active actor context")
+        path = canonical_relative_path(artifact.canonical_path)
+        digest = content_digest(content)
+        prepared = replace(
+            artifact,
+            schema_version=ARTIFACT_SCHEMA_VERSION,
+            artifact_id=artifact.artifact_id or artifact_id_from_path(path),
+            canonical_path=path,
+            created_by=(
+                actor.actor.actor_id
+                if source_document is not None and source_document.migrated_from is not None
+                else artifact.created_by or actor.actor.actor_id
+            ),
+            revision=artifact.revision or f"sha256:{digest[:16]}",
+            content_hash=digest,
+        )
+        return CanonicalDocument(
+            artifact=validate_artifact(prepared, content),
+            body=content,
+            policy_hints=policy_hints or {},
+            legacy_fields=(source_document.legacy_fields if source_document else {}),
+            migrated_from=(source_document.migrated_from if source_document else None),
+            warnings=(source_document.warnings if source_document else ()),
+        )
+
+    def write(
+        self,
+        actor: ActorContext,
+        artifact: CanonicalArtifact,
+        content: str,
+    ) -> WritebackEvent:
+        return self._write(actor, artifact, content, policy_hints={}, source_document=None)
+
+    def write_document(
+        self,
+        actor: ActorContext,
+        document: CanonicalDocument,
+    ) -> WritebackEvent:
+        """Richer local API that preserves advisory envelope policy hints."""
+
+        return self._write(
+            actor,
+            document.artifact,
+            document.body,
+            policy_hints=dict(document.policy_hints),
+            source_document=document,
+        )
+
+    def write_documents(
+        self,
+        actor: ActorContext,
+        documents: Sequence[CanonicalDocument],
+    ) -> tuple[WritebackEvent, ...]:
+        """Persist a validated artifact set with one provenance/projection cycle."""
+
+        if not documents:
+            return ()
+        event_id = self._event_id()
+        resources = tuple(
+            document.artifact.artifact_id or document.artifact.canonical_path
+            for document in documents
+        )
+        decision = self.authorizer.authorize_action(actor, Permission.WRITE, resources)
+        if not decision.allowed:
+            warnings = tuple(decision.reasons)
+            return tuple(
+                WritebackEvent(
+                    event_id=f"{event_id}-{index}",
+                    artifact=document.artifact,
+                    permission_decision=decision,
+                    status=WritebackStatus.REJECTED,
+                    warnings=warnings,
+                )
+                for index, document in enumerate(documents, start=1)
+            )
+
+        prepared = tuple(
+            self._prepare(
+                actor,
+                document.artifact,
+                document.body,
+                policy_hints=dict(document.policy_hints),
+                source_document=document,
+            )
+            for document in documents
+        )
+        if decision.scopes:
+            outside = tuple(
+                document.artifact.canonical_path
+                for document in prepared
+                if not scope_allows_path(
+                    f"memory/{document.artifact.canonical_path}", decision.scopes
+                )
+            )
+            if outside:
+                raise PermissionError("canonical write path is outside the actor's authorized scope")
+
+        persisted_paths = tuple(self.store.persist(document) for document in prepared)
+        artifacts = tuple(document.artifact for document in prepared)
+        warnings: list[str] = []
+        git_revision: str | None = None
+        index_revision: str | None = None
+        embedding_state: str | None = None
+
+        try:
+            sync = self.sync_transport.push(
+                message=f"docs(memory): capture {len(artifacts)} artifacts",
+                paths=tuple(str(path) for path in persisted_paths),
+            )
+            git_revision = sync.local_revision
+            warnings.extend(f"sync: {warning}" for warning in sync.warnings)
+        except Exception as exc:
+            warnings.append(f"sync: {exc}")
+
+        if git_revision is None:
+            warnings.append("retrieval: skipped because canonical Git provenance failed")
+        else:
+            try:
+                health = self.retriever.update(tuple(str(path) for path in persisted_paths))
+                index_revision = health.index_revision
+                if not health.available:
+                    warnings.append("retrieval: index unavailable after canonical write")
+                warnings.extend(f"retrieval: {warning}" for warning in health.warnings)
+            except Exception as exc:
+                warnings.append(f"retrieval update: {exc}")
+            try:
+                health = self.retriever.embed_background()
+                embedding_state = health.embedding_state
+                warnings.extend(f"embedding: {warning}" for warning in health.warnings)
+            except Exception as exc:
+                warnings.append(f"embedding: {exc}")
+
+        if self.graph is not None and git_revision is not None:
+            try:
+                health = self.graph.project(artifacts)
+                if health.enabled:
+                    warnings.extend(f"graph: {warning}" for warning in health.warnings)
+                    if health.consistent is False:
+                        warnings.append("graph: projection is inconsistent with canonical state")
+            except Exception as exc:
+                warnings.append(f"graph: {exc}")
+
+        status = WritebackStatus.PARTIAL if warnings else WritebackStatus.ACCEPTED
+        receipts = tuple(
+            WritebackEvent(
+                event_id=f"{event_id}-{index}",
+                artifact=artifact,
+                permission_decision=decision,
+                status=status,
+                git_revision=git_revision,
+                index_revision=index_revision,
+                embedding_state=embedding_state,
+                warnings=tuple(warnings),
+            )
+            for index, artifact in enumerate(artifacts, start=1)
+        )
+        for receipt in receipts:
+            try:
+                self._emit(
+                    actor=actor,
+                    event_id=receipt.event_id,
+                    artifact_id=receipt.artifact.artifact_id,
+                    status=status,
+                    warning_count=len(warnings),
+                )
+            except Exception as exc:
+                warnings.append(f"telemetry: {exc}")
+                status = WritebackStatus.PARTIAL
+        if status is WritebackStatus.PARTIAL and any(
+            receipt.status is WritebackStatus.ACCEPTED for receipt in receipts
+        ):
+            receipts = tuple(replace(receipt, status=status, warnings=tuple(warnings)) for receipt in receipts)
+        return receipts
+
+    def _write(
+        self,
+        actor: ActorContext,
+        artifact: CanonicalArtifact,
+        content: str,
+        *,
+        policy_hints: dict[str, object],
+        source_document: CanonicalDocument | None,
+    ) -> WritebackEvent:
+        event_id = self._event_id()
+        resource = artifact.artifact_id or artifact.canonical_path
+        decision = self.authorizer.authorize_action(actor, Permission.WRITE, (resource,))
+        if not decision.allowed:
+            warnings = tuple(decision.reasons)
+            try:
+                self._emit(
+                    actor=actor,
+                    event_id=event_id,
+                    artifact_id=artifact.artifact_id,
+                    status=WritebackStatus.REJECTED,
+                    warning_count=len(warnings),
+                )
+            except Exception:
+                warnings += ("telemetry: failed to record denied writeback",)
+            return WritebackEvent(
+                event_id=event_id,
+                artifact=artifact,
+                permission_decision=decision,
+                status=WritebackStatus.REJECTED,
+                warnings=warnings,
+            )
+
+        path = canonical_relative_path(artifact.canonical_path)
+        if decision.scopes and not scope_allows_path(f"memory/{path}", decision.scopes):
+            raise PermissionError("canonical write path is outside the actor's authorized scope")
+
+        document = self._prepare(
+            actor,
+            artifact,
+            content,
+            policy_hints=policy_hints,
+            source_document=source_document,
+        )
+        persisted_path = self.store.persist(document)
+        artifact = document.artifact
+
+        warnings: list[str] = []
+        git_revision: str | None = None
+        index_revision: str | None = None
+        embedding_state: str | None = None
+
+        try:
+            sync = self.sync_transport.push(
+                message=f"docs(memory): capture {artifact.artifact_type}",
+                paths=(str(persisted_path),),
+            )
+            git_revision = sync.local_revision
+            warnings.extend(f"sync: {warning}" for warning in sync.warnings)
+        except Exception as exc:
+            warnings.append(f"sync: {exc}")
+
+        if git_revision is None:
+            warnings.append("retrieval: skipped because canonical Git provenance failed")
+        else:
+            try:
+                health = self.retriever.update((str(persisted_path),))
+                index_revision = health.index_revision
+                if not health.available:
+                    warnings.append("retrieval: index unavailable after canonical write")
+                warnings.extend(f"retrieval: {warning}" for warning in health.warnings)
+            except Exception as exc:
+                warnings.append(f"retrieval update: {exc}")
+
+            try:
+                health = self.retriever.embed_background()
+                embedding_state = health.embedding_state
+                warnings.extend(f"embedding: {warning}" for warning in health.warnings)
+            except Exception as exc:
+                warnings.append(f"embedding: {exc}")
+
+        if self.graph is not None and git_revision is not None:
+            try:
+                health = self.graph.project((artifact,))
+                if health.enabled:
+                    warnings.extend(f"graph: {warning}" for warning in health.warnings)
+                    if health.consistent is False:
+                        warnings.append("graph: projection is inconsistent with canonical state")
+            except Exception as exc:
+                warnings.append(f"graph: {exc}")
+
+        status = WritebackStatus.PARTIAL if warnings else WritebackStatus.ACCEPTED
+        try:
+            self._emit(
+                actor=actor,
+                event_id=event_id,
+                artifact_id=artifact.artifact_id,
+                status=status,
+                warning_count=len(warnings),
+            )
+        except Exception as exc:
+            warnings.append(f"telemetry: {exc}")
+            status = WritebackStatus.PARTIAL
+
+        return WritebackEvent(
+            event_id=event_id,
+            artifact=artifact,
+            permission_decision=decision,
+            status=status,
+            git_revision=git_revision,
+            index_revision=index_revision,
+            embedding_state=embedding_state,
+            warnings=tuple(warnings),
+        )

package/runtime/claude/egregore_runtime/writeback_cli.py

@@ -0,0 +1,114 @@
+"""Internal shell bridge to the canonical artifact/writeback service."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+from .artifacts import parse_canonical_markdown
+from .contracts import Permission
+from .runtime import local_runtime
+
+
+def _root() -> Path:
+    return Path(os.environ.get("EGREGORE_ROOT") or Path.cwd()).resolve()
+
+
+def _adopt(args: argparse.Namespace) -> int:
+    root = _root()
+    memory = (root / "memory").resolve()
+    source = Path(args.path)
+    if not source.is_absolute():
+        source = root / source
+    # Capture workers report the checkout-facing memory symlink. Resolve both
+    # sides before enforcing containment so a legitimate instance-owned
+    # canonical write is not mistaken for an external path.
+    source = source.resolve()
+    try:
+        relative = source.relative_to(memory).as_posix()
+    except ValueError as exc:
+        raise ValueError("canonical artifact must be inside memory/") from exc
+
+    runtime = local_runtime(root, push_remote=not args.no_push)
+    actor = runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid.uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    document = parse_canonical_markdown(
+        source.read_text(encoding="utf-8"),
+        canonical_path=relative,
+        default_org_id=actor.profile.org_id,
+    )
+    receipt = runtime.write_document(actor, document)
+    print(json.dumps(receipt.to_dict(), ensure_ascii=False))
+    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+
+
+def _create(args: argparse.Namespace) -> int:
+    root = _root()
+    runtime = local_runtime(root, push_remote=not args.no_push)
+    actor = runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid.uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    source = Path(args.input).resolve()
+    document = parse_canonical_markdown(
+        source.read_text(encoding="utf-8"),
+        canonical_path=args.path.removeprefix("memory/"),
+        default_org_id=actor.profile.org_id,
+    )
+    receipt = runtime.write_document(actor, document)
+    print(json.dumps(receipt.to_dict(), ensure_ascii=False))
+    return 0 if receipt.status.value in {"accepted", "partial"} else 1
+
+
+def _authorize(args: argparse.Namespace) -> int:
+    root = _root()
+    runtime = local_runtime(root, push_remote=False)
+    actor = runtime.resolve_actor(
+        session_id=os.environ.get("EGREGORE_SESSION_ID", f"session_{uuid.uuid4().hex}"),
+        harness=os.environ.get("EGREGORE_RUNTIME", "shell"),
+    )
+    decision = runtime.authorize(
+        actor,
+        Permission(args.permission),
+        (args.resource,) if args.resource else (),
+    )
+    print(json.dumps(decision.to_dict(), ensure_ascii=False))
+    return 0 if decision.allowed else 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="egregore-artifact-writeback")
+    commands = parser.add_subparsers(dest="command", required=True)
+    adopt = commands.add_parser("adopt")
+    adopt.add_argument("path")
+    adopt.add_argument("--no-push", action="store_true")
+    adopt.set_defaults(handler=_adopt)
+    create = commands.add_parser("create")
+    create.add_argument("--path", required=True)
+    create.add_argument("--input", required=True)
+    create.add_argument("--no-push", action="store_true")
+    create.set_defaults(handler=_create)
+    authorize = commands.add_parser("authorize")
+    authorize.add_argument("permission", choices=[item.value for item in Permission])
+    authorize.add_argument("--resource")
+    authorize.set_defaults(handler=_authorize)
+    return parser
+
+
+def main() -> int:
+    args = _parser().parse_args()
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError) as exc:
+        print(f"writeback: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc