core-runtime 0.1.1__py3-none-any.whl

shared/infrastructure/events/bus.py

@@ -0,0 +1,76 @@
+# src/shared/infrastructure/events/bus.py
+"""
+In-Memory Event Bus.
+Provides a singleton mechanism for decoupling components via events.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import ClassVar
+
+from shared.logger import getLogger
+
+from .base import CloudEvent
+
+
+logger = getLogger(__name__)
+
+EventHandler = Callable[[CloudEvent], None]
+
+
+# ID: d96a395b-da60-459d-8b40-76a5806f9cdd
+class EventBus:
+    """
+    Synchronous In-Memory Event Bus.
+    """
+
+    _instance: ClassVar[EventBus | None] = None
+    _subscribers: ClassVar[dict[str, list[EventHandler]]] = {}
+
+    @classmethod
+    # ID: 50193784-7898-4bfc-9f4b-5daaf58ea9a1
+    def get_instance(cls) -> EventBus:
+        """Get the singleton instance of the EventBus."""
+        if cls._instance is None:
+            cls._instance = EventBus()
+        return cls._instance
+
+    # ID: efad6590-574d-418b-821c-5ec932d5736f
+    def subscribe(self, event_type: str, handler: EventHandler) -> None:
+        """
+        Register a handler for a specific event type.
+        Use '*' for wildcard subscription (all events).
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        self._subscribers[event_type].append(handler)
+        logger.debug("Subscribed handler to event type: %s", event_type)
+
+    # ID: 5fb18622-b0a0-4f86-ac8b-207036292e4a
+    def emit(self, event: CloudEvent) -> None:
+        """
+        Emit an event to all subscribers of its type.
+        Also triggers wildcard '*' subscribers.
+        """
+        handlers = self._subscribers.get(event.type, [])
+        # Also support wildcard subscriptions '*'
+        handlers.extend(self._subscribers.get("*", []))
+
+        if not handlers:
+            logger.debug("No handlers for event: %s", event.type)
+            return
+
+        logger.debug("Emitting event: %s to %d handlers", event.type, len(handlers))
+
+        for handler in handlers:
+            try:
+                handler(event)
+            except Exception as e:
+                # We do not crash the bus; observability picks this up via logs
+                logger.error(
+                    "Error in event handler for %s: %s",
+                    event.type,
+                    str(e),
+                    exc_info=True,
+                )

shared/infrastructure/git_service.py

@@ -0,0 +1,385 @@
+# src/shared/infrastructure/git_service.py
+
+"""
+GitService: thin, testable wrapper around git commands used by CORE.
+
+Responsibilities
+- Validate repo path and .git presence on init.
+- Provide small, composable operations (status, add, commit, etc.).
+- Raise RuntimeError with useful stderr/stdout on git failures.
+
+Constitutional sanctuary: this module is the sole permitted user of
+subprocess for git operations. All other layers must go through this service.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import uuid
+from pathlib import Path
+
+from shared.infrastructure.intent.operational_config import load_operational_config
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+_CFG_GIT = load_operational_config().git
+
+# ADR-071 D2.2 Phase 1: hermetic action execution via git worktree.
+# Sandbox worktrees live under SANDBOX_PARENT with names beginning
+# SANDBOX_PREFIX so the orphan sweep on daemon boot can identify and
+# reclaim them without touching unrelated worktrees.
+SANDBOX_PARENT = Path("/tmp")
+SANDBOX_PREFIX = "core-action-sandbox-"
+
+
+# ID: 4c70a9c7-ee57-40d7-80af-470c19223c21
+class GitService:
+    """Provides basic git operations for agents and services."""
+
+    def __init__(self, repo_path: str | Path):
+        """
+        Initializes the GitService and validates the repository path.
+        """
+        self.repo_path = Path(repo_path).resolve()
+        logger.info("GitService initialized for path %s", self.repo_path)
+
+    def _run_command(self, command: list[str], cwd: Path | None = None) -> str:
+        """Runs a git command and returns stdout; raises RuntimeError on failure."""
+        try:
+            effective_cwd = cwd or self.repo_path
+            logger.debug(
+                "Running git command: {' '.join(command)} in %s", effective_cwd
+            )
+            result = subprocess.run(
+                ["git", *command],
+                cwd=effective_cwd,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError as e:
+            msg = e.stderr or e.stdout or ""
+            logger.error("Git command failed: %s", msg)
+            raise RuntimeError(f"Git command failed: {msg}") from e
+
+    # ID: 06b9d4c8-a43e-4430-9f34-08d45747674a
+    def init(self, path: Path):
+        """Initializes a new Git repository at the specified path."""
+        self._run_command(["init"], cwd=path)
+
+    # ID: cc819226-e33c-4559-a2d6-88d5d9e0ddaa
+    def get_current_commit(self) -> str:
+        """Returns the hash of the current HEAD commit."""
+        return self._run_command(["rev-parse", "HEAD"])
+
+    # ID: e7a5c19d-2f48-4b6c-9d3a-1f0b4e8c5d72
+    def get_current_branch(self) -> str:
+        """
+        Returns the current branch name (e.g. 'main').
+
+        Raises RuntimeError on failure — for example, when HEAD is detached
+        or the repository has no commits yet. Callers that treat git
+        metadata as optional should wrap this call.
+        """
+        return self._run_command(["rev-parse", "--abbrev-ref", "HEAD"])
+
+    # ID: f8b6d2ae-3059-4c7d-ae4b-208c5f9d6e83
+    def get_remote_url(self, remote: str = "origin") -> str:
+        """
+        Returns the configured URL for the given remote (default 'origin').
+
+        Raises RuntimeError if the remote is not configured. Callers that
+        treat the remote URL as optional should wrap this call.
+        """
+        return self._run_command(["remote", "get-url", remote])
+
+    # ID: 62355f31-f9eb-4ac1-984e-eea556b29f31
+    def get_staged_files(self) -> list[str]:
+        """Returns a list of files that are currently staged for commit."""
+        try:
+            output = self._run_command(
+                ["diff", "--cached", "--name-only", "--diff-filter=ACMR"]
+            )
+            if not output:
+                return []
+            return output.splitlines()
+        except RuntimeError:
+            return []
+
+    # ID: e506910f-2fc8-41ac-8f77-4dd79da1e6c6
+    def is_git_repo(self) -> bool:
+        """Returns True if a '.git' directory exists."""
+        return (self.repo_path / ".git").exists()
+
+    # ID: 715fe14e-e905-4032-9721-35bc67639ed7
+    def status_porcelain(self) -> str:
+        """Returns the porcelain status output."""
+        return self._run_command(["status", "--porcelain"])
+
+    # ID: db520983-cdb8-4b99-a1d9-60467128b6dc
+    def add_all(self) -> None:
+        """Stages all changes, including untracked files.
+
+        Intended for manual/CLI callers (governor-driven flows) that
+        legitimately want to capture every working-tree change.
+        Autonomous workers must NOT use this — they must use
+        ``add(path)`` or ``commit_paths(paths, message)`` so their
+        commits are scoped to declared files and cannot accidentally
+        sweep in unrelated working-tree changes (debug edits, partial
+        WIP, other workers' artifacts).
+        """
+        self._run_command(["add", "-A"])
+
+    # ID: 823668c8-17fc-4472-9d37-b22735b8d018
+    def add(self, path: str | Path) -> None:
+        """Stages a specific file."""
+        self._run_command(["add", str(path)])
+
+    # ID: 3acb0e63-e71b-4eba-a5ed-88e8e4eec35d
+    def commit(self, message: str) -> None:
+        """
+        Commits all changes with the provided message.
+
+        Stages all changes (``git add -A``) before committing. If the first
+        commit attempt fails because a pre-commit hook modified files (hooks
+        exit non-zero and rewrite staged content), stages again and retries
+        once. This is the standard two-pass pattern required when pre-commit
+        hooks auto-fix files.
+
+        Intended for manual/CLI callers (governor-driven flows) that
+        legitimately want to capture every working-tree change in a single
+        commit. Autonomous workers must NOT use this — they must use
+        ``commit_paths(paths, message)`` so their commits are scoped to
+        declared files and cannot accidentally sweep in unrelated
+        working-tree changes (debug edits, partial WIP, other workers'
+        artifacts).
+        """
+        self._run_command(["add", "-A"])
+        try:
+            self._run_command(["commit", "-m", message])
+        except RuntimeError as first_err:
+            # Pre-commit hooks can modify files and exit non-zero on the first
+            # pass. Stage their changes and retry exactly once.
+            logger.info(
+                "GitService: first commit attempt failed — "
+                "re-staging after pre-commit hook modifications and retrying: %s",
+                first_err,
+            )
+            self._run_command(["add", "-A"])
+            self._run_command(["commit", "-m", message])
+
+    # ID: d4e5f6a7-b8c9-0123-4567-89abcdef0123
+    def restore_paths(self, paths: list[str]) -> None:
+        """
+        Reverts the working-tree state of the given tracked paths to HEAD.
+
+        Used by ProposalExecutor's failure branches per ADR-021 D2/D4.
+        Untracked paths in the input are silently dropped (consistent with
+        `git checkout -- <pathspec>` semantics).
+        """
+        if not paths:
+            logger.debug("GitService.restore_paths: no paths to restore")
+            return
+
+        ls_output = self._run_command(["ls-files", "--", *paths])
+        tracked = [line for line in ls_output.splitlines() if line]
+
+        if not tracked:
+            logger.info(
+                "GitService.restore_paths: no tracked paths in input (count_input=%d)",
+                len(paths),
+            )
+            return
+
+        self._run_command(["checkout", "--", *tracked])
+        logger.info("GitService.restore_paths: reverted %d paths", len(tracked))
+
+    # ID: e5f6a7b8-c9d0-1234-5678-9abcdef01234
+    def commit_paths(self, paths: list[str], message: str) -> None:
+        """
+        Stages and commits exactly the given paths.
+
+        Used by ProposalExecutor's success branches per ADR-021 D3. Mirrors
+        the two-pass retry pattern in `commit` for pre-commit hook
+        auto-modifications.
+        """
+        if not paths:
+            raise ValueError(
+                "commit_paths requires at least one path; an autonomous "
+                "proposal that resolved to no files is malformed"
+            )
+
+        self._run_command(["add", "--", *paths])
+        try:
+            self._run_command(["commit", "-m", message])
+        except RuntimeError as first_err:
+            logger.info(
+                "GitService.commit_paths: first commit attempt failed — "
+                "re-staging after pre-commit hook modifications and retrying: %s",
+                first_err,
+            )
+            self._run_command(["add", "--", *paths])
+            self._run_command(["commit", "-m", message])
+
+    # ID: a1b2c3d4-e5f6-7890-abcd-ef1234567892
+    def get_recent_commits(self, n: int = _CFG_GIT.recent_commits_n) -> list[str]:
+        """
+        Returns the last n commit summaries (oneline, no merges).
+        Used by SystemContextGatherer for change context (Dimension 5).
+        """
+        try:
+            output = self._run_command(["log", f"-{n}", "--oneline", "--no-merges"])
+            return output.splitlines() if output else []
+        except RuntimeError:
+            return []
+
+    # ID: ff02b770-4928-4a10-9358-c6df84ff091f
+    def get_diff_stat(self, base: str = "HEAD~5", target: str = "HEAD") -> str:
+        """
+        Returns the diffstat between two refs.
+        Used by SystemContextGatherer for change context (Dimension 5).
+        """
+        try:
+            return self._run_command(["diff", "--stat", base, target])
+        except RuntimeError:
+            return ""
+
+    # ID: c3d4e5f6-a7b8-9012-cdef-123456789003
+    def get_changed_files_log(self, n: int = _CFG_GIT.changed_files_log_n) -> list[str]:
+        """
+        Returns filenames touched in the last n commits (Python files only).
+        Used by SystemContextGatherer for change context (Dimension 5).
+        """
+        try:
+            output = self._run_command(
+                ["log", "--name-only", "--pretty=format:", f"-{n}"]
+            )
+            return [
+                line.strip()
+                for line in output.splitlines()
+                if line.strip() and line.strip().endswith(".py")
+            ]
+        except RuntimeError:
+            return []
+
+    # ID: 2204a851-0f11-495b-be3d-c0af82bb13ee
+    def create_worktree(self, sha: str) -> ScopedGitService:
+        """
+        Create a hermetic git worktree rooted at `sha` for action execution.
+
+        Path: SANDBOX_PARENT/SANDBOX_PREFIX<uuid4>/. Uses --detach so no
+        branch is created. Returns a ScopedGitService wrapping the worktree;
+        the caller MUST call cleanup() (or use as a context manager). Any
+        leaked worktrees are reclaimed by sweep_orphan_worktrees() on the
+        next daemon boot.
+
+        ADR-071 D2.2 Phase 1.
+        """
+        worktree_path = SANDBOX_PARENT / f"{SANDBOX_PREFIX}{uuid.uuid4().hex}"
+        self._run_command(["worktree", "add", "--detach", str(worktree_path), sha])
+        logger.info(
+            "GitService: created worktree %s at sha %s",
+            worktree_path,
+            sha[:12],
+        )
+        return ScopedGitService(worktree_path, parent=self)
+
+    # ID: 7990798e-4c6b-4aff-a8ce-26f7f1f9d480
+    def sweep_orphan_worktrees(self) -> int:
+        """
+        Remove any sandbox worktrees left behind by crashed actions.
+
+        Lists worktrees registered against this repo, removes those whose
+        path lives directly under SANDBOX_PARENT with the SANDBOX_PREFIX,
+        and prunes the administrative entries. Returns the count removed.
+        Safe to call on daemon boot; failures are logged and swallowed so
+        ignition is never blocked.
+
+        ADR-071 D2.2 Phase 1.
+        """
+        try:
+            output = self._run_command(["worktree", "list", "--porcelain"])
+        except RuntimeError as exc:
+            logger.warning("GitService.sweep_orphan_worktrees: list failed: %s", exc)
+            return 0
+
+        removed = 0
+        for line in output.splitlines():
+            if not line.startswith("worktree "):
+                continue
+            path_str = line[len("worktree ") :].strip()
+            path = Path(path_str)
+            if path.parent != SANDBOX_PARENT or not path.name.startswith(
+                SANDBOX_PREFIX
+            ):
+                continue
+            try:
+                self._run_command(["worktree", "remove", "--force", path_str])
+                removed += 1
+                logger.info("GitService: removed orphan worktree %s", path_str)
+            except RuntimeError as exc:
+                logger.warning(
+                    "GitService: failed to remove orphan worktree %s: %s",
+                    path_str,
+                    exc,
+                )
+
+        try:
+            self._run_command(["worktree", "prune"])
+        except RuntimeError as exc:
+            logger.debug("GitService.sweep_orphan_worktrees: prune failed: %s", exc)
+
+        return removed
+
+
+# ID: ea3110a9-3a63-402f-af22-61f1860eff2b
+class ScopedGitService(GitService):
+    """GitService bound to a temporary git worktree (ADR-071 D2.2 Phase 1).
+
+    Inherits every GitService operation; because `self.repo_path` points at
+    the worktree, all commands execute against the sandbox rather than the
+    main tree. The caller is responsible for `cleanup()` — either directly
+    or via context-manager use — once execution finishes.
+    """
+
+    def __init__(self, worktree_path: Path, parent: GitService):
+        super().__init__(worktree_path)
+        self._parent = parent
+        self._cleaned_up = False
+
+    # ID: 375faa32-d545-47ee-9fdb-3894b425de5a
+    def cleanup(self) -> None:
+        """
+        Remove the worktree. Idempotent. Uses `git worktree remove --force`
+        which discards any uncommitted changes in the sandbox — intentional,
+        because the caller is expected to copy out wanted changes before
+        cleanup.
+        """
+        if self._cleaned_up:
+            return
+        try:
+            self._parent._run_command(
+                ["worktree", "remove", "--force", str(self.repo_path)]
+            )
+        except RuntimeError as exc:
+            logger.warning(
+                "ScopedGitService.cleanup: git worktree remove failed (%s); "
+                "falling back to rmtree on %s",
+                exc,
+                self.repo_path,
+            )
+            if self.repo_path.exists():
+                shutil.rmtree(self.repo_path, ignore_errors=True)
+        finally:
+            self._cleaned_up = True
+            logger.info("ScopedGitService: cleaned up worktree %s", self.repo_path)
+
+    def __enter__(self) -> ScopedGitService:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.cleanup()

shared/infrastructure/intent/action_risk.py

@@ -0,0 +1,135 @@
+# src/shared/infrastructure/intent/action_risk.py
+"""
+Action-id to impact-level mapping helper.
+
+Single source of truth for atomic-action impact classification. The
+mapping is owned by .intent/enforcement/config/action_risk.yaml and
+governs which actions auto-execute (safe), require human approval
+(moderate), or are blocked unless explicitly authorized (dangerous).
+
+Authority: policy. The governing document is
+.intent/enforcement/config/action_risk.yaml, accessed exclusively
+via IntentRepository. No other module may hardcode the action_id ->
+impact_level mapping — all call sites route through this helper. See
+ADR-008.
+
+The _FALLBACK_* constants below are last-resort graceful degradation
+for the narrow case where the policy document cannot be loaded (e.g.
+bootstrap races, corrupt YAML). They MUST NOT be treated as
+defaults-in-logic — when the policy loads successfully, it always wins.
+
+LAYER: shared/infrastructure/intent — pure helper. No imports from
+will/, body/, or cli/.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+_VALID_LEVELS: frozenset[str] = frozenset({"safe", "moderate", "dangerous"})
+
+_FALLBACK_MAPPING: dict[str, str] = {
+    "build.tests": "safe",
+    "check.imports": "safe",
+    "claim.proposal": "safe",
+    "crate.create": "safe",
+    "file.create": "moderate",
+    "file.edit": "moderate",
+    "file.read": "safe",
+    "file.tag_metadata": "safe",
+    "fix.atomic_actions": "moderate",
+    "fix.docstrings": "moderate",
+    "fix.duplicate_ids": "moderate",
+    "fix.format": "safe",
+    "fix.headers": "safe",
+    "fix.ids": "safe",
+    "fix.imports": "safe",
+    "fix.logging": "safe",
+    "fix.modularity": "moderate",
+    "fix.placeholders": "safe",
+    "sync.db": "moderate",
+    "sync.vectors_code": "moderate",
+    "sync.vectors_constitution": "moderate",
+}
+
+
+# ID: 4b8d2e7c-1f9a-4d6b-8c3e-5a7f9b2d4e6c
+def _validate_config(mapping: dict[str, Any]) -> None:
+    """
+    Validate at load time that every value in the mapping is one of
+    {safe, moderate, dangerous}. Raises ValueError with a clear message
+    on the first offending key/value encountered.
+    """
+    for action_id, level in mapping.items():
+        if level not in _VALID_LEVELS:
+            raise ValueError(
+                f"action_risk: actions[{action_id!r}] = {level!r} is not a "
+                f"valid impact level; allowed values are {sorted(_VALID_LEVELS)}"
+            )
+
+
+# ID: 5c9e3f8d-2a0b-4e7c-9d4f-6b8a0c3e5f7d
+def load_action_risk() -> dict[str, str]:
+    """
+    Load .intent/enforcement/config/action_risk.yaml via IntentRepository.
+
+    Returns the action_id -> impact_level mapping on success. On any
+    failure — missing file, parse error, unexpected top-level type —
+    returns fallback defaults and logs a warning so callers degrade
+    gracefully rather than halting.
+
+    The loader validates every impact level against
+    {safe, moderate, dangerous} before returning. A YAML that maps an
+    action to anything else raises ValueError at load time, not at the
+    call site.
+    """
+    try:
+        from shared.infrastructure.intent.intent_repository import (
+            get_intent_repository,
+        )
+
+        repo = get_intent_repository()
+        config_path = repo.resolve_rel("enforcement/config/action_risk.yaml")
+        config = repo.load_document(config_path)
+        if isinstance(config, dict):
+            actions = config.get("actions")
+            if isinstance(actions, dict):
+                _validate_config(actions)
+                return dict(actions)
+            logger.warning(
+                "action_risk: action_risk.yaml missing 'actions' dict "
+                "— using fallback defaults."
+            )
+        else:
+            logger.warning(
+                "action_risk: action_risk.yaml did not parse as a dict "
+                "— using fallback defaults."
+            )
+    except ValueError:
+        raise
+    except Exception as exc:
+        logger.warning(
+            "action_risk: could not load .intent/enforcement/config/"
+            "action_risk.yaml (%s) — using fallback defaults.",
+            exc,
+        )
+    return dict(_FALLBACK_MAPPING)
+
+
+# ID: 6da0f4ae-3b1c-4f8d-ae5b-7c9b1d4f6a8e
+def get_impact_level(action_id: str) -> str:
+    """
+    Return the impact level for a given action_id.
+
+    Raises KeyError if the action_id is not present in the mapping —
+    callers must register every action in
+    .intent/enforcement/config/action_risk.yaml.
+    """
+    mapping = load_action_risk()
+    return mapping[action_id]