core-runtime 0.1.1__py3-none-any.whl

body/atomic/registry.py

@@ -0,0 +1,326 @@
+# src/body/atomic/registry.py
+"""
+Atomic Actions Registry - Constitutional Action Definitions
+
+Every action in CORE is:
+1. Independently executable
+2. Constitutionally governed
+3. Returns ActionResult
+4. Composable into workflows
+5. Auditable and traceable
+
+UNIX Philosophy: Each action does ONE thing well.
+
+CONSTITUTIONAL ENFORCEMENT:
+This module enforces .intent/rules/architecture/atomic_actions.json at registration time.
+Actions that violate constitutional rules CANNOT be registered.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+
+from shared.action_types import ActionResult
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+# ID: 9e2f7a1c-4b8d-4e6f-a3c2-1d5b8f0a4e9c
+class ConstitutionalError(RuntimeError):
+    """Raised when the action registry violates a constitutional invariant."""
+
+    pass
+
+
+# ID: 6166d4ed-db63-4363-95c3-504ef1b9a3e0
+class ActionCategory(str, Enum):
+    """Constitutional action categories."""
+
+    FIX = "fix"  # Code remediation
+    SYNC = "sync"  # State synchronization
+    CHECK = "check"  # Validation/audit
+    BUILD = "build"  # Construction
+    STATE = "state"  # State machine transitions
+
+
+@dataclass
+# ID: 89f5c3e2-1a47-4c8d-9e57-2c6e4a8f3b1d
+class ActionDefinition:
+    """
+    Constitutional metadata for an atomic action.
+
+    Every action must declare:
+    - What it does (description)
+    - What policies govern it (policies)
+    - What category it belongs to (category)
+    - What impact level it has (impact_level)
+    - Which audit check_ids it can remediate (remediates)
+    """
+
+    action_id: str
+    """Unique action identifier (e.g., 'fix.format', 'sync.db')"""
+
+    description: str
+    """Human-readable description of what this action does"""
+
+    category: ActionCategory
+    """Constitutional category"""
+
+    policies: list[str]
+    """Policy IDs that govern this action"""
+
+    executor: Callable[..., Awaitable[ActionResult]]
+    """Async function that executes the action"""
+
+    impact_level: str = ""
+    """
+    Impact level: 'safe', 'moderate', 'dangerous'.
+
+    Defaults to "" — overlaid at executor init from
+    .intent/enforcement/config/action_risk.yaml via
+    ActionRegistry.apply_risk_config(). Never authored in code.
+    """
+
+    requires_db: bool = False
+    """Whether this action requires database access"""
+
+    requires_vectors: bool = False
+    """Whether this action requires vector store access"""
+
+    remediates: list[str] = field(default_factory=list)
+    """
+    Audit check IDs this action can autonomously remediate.
+
+    ViolationRemediatorWorker uses this to map Blackboard findings
+    to actions without any static YAML mapping.
+
+    Example: ["purity.stable_id_anchor", "linkage.assign_ids"]
+    """
+
+
+# ID: 7f4b2c8e-9d3a-4e1f-8c7d-5a2b3c4d5e6f
+class ActionRegistry:
+    """
+    Global registry of all atomic actions in CORE.
+
+    Actions are registered at module load time and can be:
+    - Executed individually via CLI
+    - Composed into workflows
+    - Validated against constitutional policies
+    - Audited for compliance
+    - Looked up by the check_ids they remediate
+    """
+
+    def __init__(self):
+        self._actions: dict[str, ActionDefinition] = {}
+        # Reverse index: check_id -> action_id for O(1) remediation lookup
+        self._remediates_index: dict[str, str] = {}
+
+    # ID: 2a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d
+    def register(self, definition: ActionDefinition) -> None:
+        """Register an action definition."""
+        if definition.action_id in self._actions:
+            raise ValueError(f"Action already registered: {definition.action_id}")
+        self._actions[definition.action_id] = definition
+
+        # Build reverse index for remediation lookup
+        for check_id in definition.remediates:
+            if check_id in self._remediates_index:
+                logger.warning(
+                    "check_id '%s' already claimed by action '%s', "
+                    "skipping claim by '%s'",
+                    check_id,
+                    self._remediates_index[check_id],
+                    definition.action_id,
+                )
+            else:
+                self._remediates_index[check_id] = definition.action_id
+
+    # ID: 3b4c5d6e-7f8a-9b0c-1d2e-3f4a5b6c7d8e
+    def get(self, action_id: str) -> ActionDefinition | None:
+        """Get action definition by ID."""
+        return self._actions.get(action_id)
+
+    # ID: 8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d
+    def get_by_check_id(self, check_id: str) -> ActionDefinition | None:
+        """
+        Look up the action that remediates the given audit check_id.
+
+        Used by ViolationRemediatorWorker to map Blackboard findings
+        directly to executable actions — no static YAML required.
+
+        Returns None if no registered action claims this check_id.
+        """
+        action_id = self._remediates_index.get(check_id)
+        if not action_id:
+            return None
+        return self._actions.get(action_id)
+
+    # ID: 4c5d6e7f-8a9b-0c1d-2e3f-4a5b6c7d8e9f
+    def get_by_category(self, category: ActionCategory) -> list[ActionDefinition]:
+        """Get all actions in a category."""
+        return [a for a in self._actions.values() if a.category == category]
+
+    # ID: 5d6e7f8a-9b0c-1d2e-3f4a-5b6c7d8e9f0a
+    def list_all(self) -> list[ActionDefinition]:
+        """List all registered actions."""
+        return list(self._actions.values())
+
+    # ID: 7f1e3a8c-2b9d-4f6e-a5c1-3b7e9d2f4a6b
+    def apply_risk_config(self, mapping: dict[str, str]) -> None:
+        """
+        Overlay impact_level on every registered action from the policy
+        mapping loaded from .intent/enforcement/config/action_risk.yaml.
+
+        Raises ConstitutionalError if any registered action_id is absent
+        from the mapping — every action must have a governed
+        classification.
+        """
+        missing: list[str] = [
+            action_id for action_id in self._actions if action_id not in mapping
+        ]
+        if missing:
+            raise ConstitutionalError(
+                f"action_risk policy is missing impact_level for "
+                f"registered actions: {sorted(missing)}. "
+                f"Add them to .intent/enforcement/config/action_risk.yaml."
+            )
+
+        for action_id, definition in self._actions.items():
+            definition.impact_level = mapping[action_id]
+
+
+# Global singleton registry
+action_registry = ActionRegistry()
+
+
+# ID: a516c041-becf-4f13-b970-b1a2e31631dc
+def _validate_action_signature(func: Callable[..., Awaitable[ActionResult]]) -> None:
+    """
+    Validate function signature against constitutional requirements.
+
+    Enforces .intent/rules/architecture/atomic_actions.json:
+    - atomic_actions.must_return_action_result
+    - atomic_actions.must_have_decorator
+    - atomic_actions.no_governance_bypass
+
+    Note: the **kwargs absorption invariant (issue #448) is enforced inside
+    the @atomic_action decorator itself, not here — since must_have_decorator
+    above guarantees @atomic_action has already run on every registered
+    function, the kwargs check has already fired by the time control
+    reaches this validator.
+
+    Raises:
+        TypeError: If function signature violates constitutional rules
+    """
+    func_name = func.__name__
+
+    sig = inspect.signature(func)
+    return_annotation = sig.return_annotation
+
+    if return_annotation is inspect.Signature.empty:
+        raise TypeError(
+            f"Constitutional violation in '{func_name}': "
+            f"Missing return type annotation. "
+            f"Rule: atomic_actions.must_return_action_result. "
+            f"Required: '-> ActionResult'"
+        )
+
+    is_action_result = False
+
+    if return_annotation is ActionResult:
+        is_action_result = True
+    elif isinstance(return_annotation, str):
+        if return_annotation == "ActionResult":
+            is_action_result = True
+    elif hasattr(return_annotation, "__name__"):
+        if return_annotation.__name__ == "ActionResult":
+            is_action_result = True
+
+    if not is_action_result:
+        raise TypeError(
+            f"Constitutional violation in '{func_name}': "
+            f"Return type must be 'ActionResult', got '{return_annotation}'. "
+            f"Rule: atomic_actions.must_return_action_result. "
+            f"Tuple returns like (bool, str) are explicitly forbidden."
+        )
+
+    has_atomic_decorator = hasattr(func, "_atomic_action_metadata")
+
+    if not has_atomic_decorator:
+        raise TypeError(
+            f"Constitutional violation in '{func_name}': "
+            f"Missing @atomic_action decorator. "
+            f"Rule: atomic_actions.must_have_decorator. "
+            f"Required: @atomic_action(action_id=..., intent=..., impact=..., policies=[...])"
+        )
+
+    logger.debug(
+        "Constitutional validation passed for action '%s': "
+        "return type=ActionResult, has @atomic_action decorator",
+        func_name,
+    )
+
+
+# ID: 6e7f8a9b-0c1d-2e3f-4a5b-6c7d8e9f0a1b
+def register_action(
+    action_id: str,
+    description: str,
+    category: ActionCategory,
+    policies: list[str],
+    requires_db: bool = False,
+    requires_vectors: bool = False,
+    remediates: list[str] | None = None,
+):
+    """
+    Decorator to register an action with constitutional enforcement.
+
+    CONSTITUTIONAL ENFORCEMENT:
+    This decorator enforces .intent/rules/architecture/atomic_actions.json at
+    module import time. Functions that violate constitutional rules will cause
+    the module import to fail with a TypeError.
+
+    Impact level is NOT a parameter here. It is governed externally via
+    .intent/enforcement/config/action_risk.yaml and overlaid onto each
+    ActionDefinition at executor init by ActionRegistry.apply_risk_config().
+    See ADR-008.
+
+    Args:
+        remediates: List of audit check_ids this action can fix autonomously.
+                    ViolationRemediatorWorker uses this to close the audit loop
+                    without any static YAML mapping. Example:
+                    remediates=["purity.stable_id_anchor", "linkage.assign_ids"]
+    """
+
+    # ID: 5352e0e1-0d42-40e8-8ccb-7437a5c5fa18
+    def decorator(func: Callable[..., Awaitable[ActionResult]]):
+        try:
+            _validate_action_signature(func)
+        except TypeError as e:
+            raise TypeError(f"Cannot register action '{action_id}': {e}") from e
+
+        definition = ActionDefinition(
+            action_id=action_id,
+            description=description,
+            category=category,
+            policies=policies,
+            executor=func,
+            requires_db=requires_db,
+            requires_vectors=requires_vectors,
+            remediates=remediates or [],
+        )
+        action_registry.register(definition)
+
+        logger.info(
+            "Action '%s' registered successfully with constitutional compliance",
+            action_id,
+        )
+
+        return func
+
+    return decorator

body/atomic/remediate_cognitive_role.py

@@ -0,0 +1,104 @@
+# src/body/atomic/remediate_cognitive_role.py
+"""
+Atomic action for remediating ai.cognitive_role.no_hardcoded_string violations.
+
+This action bridges audit findings to the CallSiteRewriter worker by:
+1. Taking audit.violation findings for cognitive role rules
+2. Preparing prompt.artifact finding data for the calling Worker to post
+   via self.post_finding()
+3. Triggering the rewriter to fix the hardcoded strings
+
+The action does not write to the blackboard itself — ADR-011 requires
+that all blackboard writes flow through Worker attribution. The calling
+Worker (ProposalConsumerWorker) posts the finding described in
+ActionResult.data["finding_to_post"].
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from body.atomic.registry import ActionCategory, register_action
+from shared.action_types import ActionImpact, ActionResult
+from shared.atomic_action import atomic_action
+from shared.logger import getLogger
+
+
+logger = getLogger(__name__)
+
+
+@register_action(
+    action_id="remediate.cognitive_role",
+    description="Fix hardcoded cognitive role strings (Architect, Coder, etc.) in source files",
+    category=ActionCategory.FIX,
+    policies=[
+        "governance.dangerous_execution_primitives",
+        "autonomy.tracing.mandatory",
+    ],
+    requires_db=False,  # Action no longer touches the DB; caller posts the finding
+    requires_vectors=False,
+    remediates=[
+        "ai.cognitive_role.no_hardcoded_string",
+        # Add other related check_ids here if they exist
+    ],
+)
+@atomic_action(
+    action_id="remediate.cognitive_role",
+    intent="Prepare prompt.artifact finding for hardcoded cognitive-role strings",
+    impact=ActionImpact.READ_ONLY,
+    policies=["atomic_actions"],
+)
+# ID: bf9420e3-f4ca-4cdf-aa11-7a9ecfa2a050
+async def remediate_cognitive_role(
+    file_path: str | None = None,
+    line_number: int | None = None,
+    rule: str = "ai.cognitive_role.no_hardcoded_string",
+    prompt_text: str = "",
+    **kwargs: Any,
+) -> ActionResult:
+    """
+    Prepare prompt.artifact finding data for the calling Worker to post.
+
+    This action is called by the proposal system when violations are found.
+    It does NOT write to the blackboard itself — per ADR-011, all blackboard
+    writes must flow through Worker attribution. The action constructs the
+    finding shape (subject + payload) and returns it in
+    ActionResult.data["finding_to_post"]; ProposalConsumerWorker posts via
+    self.post_finding() as part of its post-execution handling.
+
+    Args:
+        file_path: Path to the file containing the violation
+        line_number: Line number where violation occurs (optional)
+        rule: The specific rule being violated
+        prompt_text: The hardcoded role string that was found
+        **kwargs: Additional parameters
+
+    Returns:
+        ActionResult with finding_to_post in data for the caller to post.
+    """
+    if not file_path:
+        return ActionResult.failure(
+            message="Missing required parameter: file_path", data={"rule": rule}
+        )
+
+    payload = {
+        "file_path": file_path,
+        "line_number": line_number,
+        "artifact_name": "cognitive_role_string",
+        "rule": rule,
+        "prompt_text": prompt_text,
+        "input_vars": [],  # No input vars for this type
+        "severity": "error",
+    }
+
+    return ActionResult.success(
+        message=f"Prepared prompt.artifact finding for {file_path}",
+        data={
+            "finding_to_post": {
+                "subject": f"prompt.artifact::{file_path}",
+                "payload": payload,
+            },
+            "file_path": file_path,
+            "rule": rule,
+        },
+    )

body/atomic/sandbox_lifecycle.py

@@ -0,0 +1,252 @@
+# src/body/atomic/sandbox_lifecycle.py
+"""
+SandboxLifecycle — ADR-071 D2.2 sandbox decision + copy-back subsystem.
+
+Extracted from ActionExecutor (2026-06-01). The "decide whether to sandbox
+this execution" logic and the "copy worktree mutations back to main tree"
+logic are one cohesive subsystem — both gated on the same ADR-071 D2.2
+conditions, both operating on the same `ScopedGitService` instance, both
+sharing the same conflict/no-deletion safety contract.
+
+Co-locating them here keeps ActionExecutor focused on its single
+constitutional responsibility — orchestrating the policy/auth/exec/hooks/
+audit pipeline — and gives the sandbox subsystem a name that matches what
+it is. No behavioral change vs. the in-class implementation; ActionExecutor
+constructs one SandboxLifecycle and delegates two call sites to it.
+
+LAYER: body/atomic — execution-infrastructure helper. No LLM, no rule
+evaluation. Reads from CoreContext (git_service, file_handler); writes
+only through FileHandler.write_validated_bytes (ADR-021 commit_paths
+boundary preserved).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING, Any
+
+from body.atomic.registry import ActionDefinition
+from shared.action_types import ActionImpact
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.context import CoreContext
+
+logger = getLogger(__name__)
+
+# ADR-071 D2.2 Phase 2: action impacts that warrant hermetic worktree
+# sandboxing. WRITE_DATA targets databases/external systems (not the
+# source tree), so the worktree isolation does nothing for it.
+_SANDBOXED_IMPACTS = frozenset({ActionImpact.WRITE_CODE, ActionImpact.WRITE_METADATA})
+
+
+# ID: 8c112a60-ad77-431b-9825-dcdcc63afb55
+class SandboxLifecycle:
+    """
+    ADR-071 D2.2 sandbox decision + copy-back subsystem.
+
+    Two public methods, both operating on the same scoped-git instance:
+
+    - `build_execution_context` — decide whether to sandbox the about-to-run
+      action, and if so produce a scoped CoreContext with `git_service` and
+      `file_handler` repointed at a fresh ScopedGitService worktree.
+
+    - `propagate_changes` — after a successful sandboxed run, copy the
+      worktree's modified/untracked files back to the main tree through
+      `FileHandler.write_validated_bytes`, with a conflict check that
+      refuses to overwrite uncommitted main-tree changes (loud-failure
+      contract).
+
+    Both methods are pure delegations of subsystem state — they share no
+    in-flight state between calls. ActionExecutor holds the instance and
+    drives both call sites within a single `execute()` invocation, passing
+    the `scoped_git` handle between them.
+    """
+
+    def __init__(self, core_context: CoreContext):
+        """
+        Initialize the sandbox subsystem against the main CoreContext.
+
+        Args:
+            core_context: The main (unsandboxed) CoreContext. Used to
+                read `git_service` (worktree creation), `file_handler`
+                (copy-back target), and as the base for the scoped
+                context built per execution.
+        """
+        self.core_context = core_context
+
+    # ID: a9b3e7c1-4d2f-4e85-9a17-6b8c3d5e7f12
+    def build_execution_context(
+        self,
+        definition: ActionDefinition,
+        write: bool,
+        pre_execution_sha: str | None,
+    ) -> tuple[CoreContext, Any]:
+        """Decide whether to sandbox this execution and build the context.
+
+        Returns (context_to_pass_to_action, scoped_git_or_None). When
+        sandboxing applies, the returned context is a shallow copy of
+        self.core_context with `git_service` and `file_handler` repointed
+        at a fresh ScopedGitService rooted at `pre_execution_sha`. The
+        caller MUST call `scoped_git.cleanup()` in a finally block.
+
+        Gate (all required):
+          - pre_execution_sha is not None (autonomous call path)
+          - write is True (dry-runs need no isolation)
+          - the action's @atomic_action metadata declares impact ∈
+            {WRITE_CODE, WRITE_METADATA}
+
+        Note on IntentGuard: the FileHandler constructor wires an
+        IntentGuard via get_intent_guard(), which is a process singleton
+        bound to the first repo_path it sees. A scoped FileHandler reuses
+        that singleton — paths are still validated against governance,
+        but using main-repo .intent/ state (the current governance frame)
+        rather than the worktree's snapshot. That's the correct default:
+        we want to honour governance as-of-now, not as-of-proposal.
+        """
+        if (
+            pre_execution_sha is None
+            or not write
+            or self.core_context.git_service is None
+        ):
+            return self.core_context, None
+
+        metadata = getattr(definition.executor, "_atomic_action_metadata", None)
+        if metadata is None or metadata.impact not in _SANDBOXED_IMPACTS:
+            return self.core_context, None
+
+        from shared.infrastructure.storage.file_handler import FileHandler
+
+        scoped_git = self.core_context.git_service.create_worktree(pre_execution_sha)
+        try:
+            scoped_file_handler = FileHandler(str(scoped_git.repo_path))
+        except Exception:
+            scoped_git.cleanup()
+            raise
+
+        scoped_context = dataclasses.replace(
+            self.core_context,
+            git_service=scoped_git,
+            file_handler=scoped_file_handler,
+        )
+        logger.info(
+            "SandboxLifecycle: %s sandboxed in %s at sha %s",
+            definition.action_id,
+            scoped_git.repo_path,
+            pre_execution_sha[:12],
+        )
+        return scoped_context, scoped_git
+
+    # ID: b1d2c5f9-3a48-4e67-8b91-2c5f8a3d6e90
+    def propagate_changes(self, scoped_git: Any) -> None:
+        """Copy files modified inside the sandbox back to the main tree.
+
+        Walks `scoped_git.status_porcelain()` and for each modified or
+        untracked entry, copies the worktree-side bytes through the main
+        FileHandler's write_runtime_bytes surface (canonical write path,
+        no re-syntax-check, no auto-newline injection — byte-identical).
+
+        Before copying anything, checks the main tree for uncommitted
+        modifications in the sandbox's target paths. If any overlap, raises
+        — the exception bubbles into execute()'s outer try and turns the
+        action result into a loud failure, rather than silently overwriting
+        the governor's concurrent edits. This is the safety mechanism the
+        ADR-071 D2.2 plan describes as "loud failure rather than silent
+        contamination". The b11f4dba race shape is closed: worker either
+        propagates cleanly (no overlap) or refuses (overlap detected).
+
+        Deletions are not propagated: the no_direct_writes rule (#451)
+        forbids @atomic_action functions from invoking unlink/rmdir, so
+        a `D`-status entry here would itself be a constitutional
+        violation. We log and skip rather than silently deleting from
+        the main tree.
+        """
+        sandbox_root = scoped_git.repo_path
+        file_handler = self.core_context.file_handler
+
+        try:
+            porcelain = scoped_git.status_porcelain()
+        except Exception as exc:
+            logger.error(
+                "SandboxLifecycle: sandbox status read failed (%s); "
+                "main tree NOT updated to avoid partial propagation",
+                exc,
+            )
+            return
+
+        if not porcelain:
+            logger.debug(
+                "SandboxLifecycle: sandbox produced no changes for %s", sandbox_root
+            )
+            return
+
+        # Collect intended target paths. Porcelain v1 format is "XY path"
+        # but GitService.status_porcelain strips the wrapping stdout, which
+        # eats the leading space of the first line when X (staged) is
+        # unmodified — so " M foo" arrives as "M foo". Split on first
+        # whitespace to recover {status_token, path} regardless.
+        target_paths: set[str] = set()
+        for line in porcelain.splitlines():
+            parts = line.split(None, 1)
+            if len(parts) != 2:
+                continue
+            status_token, rel = parts[0], parts[1].strip().strip('"')
+            if "D" in status_token:
+                logger.warning(
+                    "SandboxLifecycle: sandbox reports deletion of %s — "
+                    "atomic actions cannot delete files (#451); skipping",
+                    rel,
+                )
+                continue
+            target_paths.add(rel)
+
+        if not target_paths:
+            return
+
+        # Conflict check: is the main tree dirty on any target path?
+        try:
+            main_porcelain = self.core_context.git_service.status_porcelain()
+        except Exception as exc:
+            logger.error(
+                "SandboxLifecycle: main tree status read failed (%s); "
+                "refusing to propagate without a conflict check",
+                exc,
+            )
+            raise RuntimeError(
+                f"ADR-071 D2.2: cannot verify main tree cleanliness ({exc}); "
+                "refusing to propagate sandbox changes"
+            ) from exc
+
+        main_dirty: set[str] = set()
+        for line in main_porcelain.splitlines():
+            parts = line.split(None, 1)
+            if len(parts) == 2:
+                main_dirty.add(parts[1].strip().strip('"'))
+
+        conflict = sorted(target_paths & main_dirty)
+        if conflict:
+            raise RuntimeError(
+                "ADR-071 D2.2: refusing to propagate sandbox changes — "
+                f"main tree has uncommitted changes in {len(conflict)} "
+                f"sandbox target file(s): {conflict[:5]}"
+                f"{' ...' if len(conflict) > 5 else ''}. "
+                "Commit or revert those changes, then re-run."
+            )
+
+        copied = 0
+        for rel in sorted(target_paths):
+            src = sandbox_root / rel
+            if not src.exists():
+                logger.warning(
+                    "SandboxLifecycle: sandbox entry %s missing on disk; skipping",
+                    rel,
+                )
+                continue
+            file_handler.write_validated_bytes(rel, src.read_bytes())
+            copied += 1
+
+        logger.info(
+            "SandboxLifecycle: propagated %d file(s) from sandbox to main tree",
+            copied,
+        )