agent-operating-substrate 0.1.0__py3-none-any.whl

aos/curator.py

@@ -0,0 +1,143 @@
+"""Evolutionary rule curator for pruning, subsumption, and substrate hygiene."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+import yaml
+
+from aos.blackboard import post_event
+from aos.discovery import discover_rules
+from aos.models import InvariantRule, Scope
+from aos.validator import validate_rule_dict
+
+
+@dataclass
+class CurationAction:
+    rule_id: str
+    action_type: str
+    reason: str
+    superseded_by: Optional[str] = None
+
+
+def is_path_subsumed(sub_pattern: str, super_pattern: str) -> bool:
+    """Check if super_pattern universally covers sub_pattern."""
+    if super_pattern in ("**/*", "**", "*"):
+        return True
+    if sub_pattern == super_pattern:
+        return True
+    if super_pattern.endswith("/**") and sub_pattern.startswith(super_pattern[:-3]):
+        return True
+    return False
+
+
+def is_scope_subsumed(sub_scope: Scope, super_scope: Scope) -> bool:
+    """Determine whether sub_scope is a strict subset of super_scope."""
+    # Language coverage check
+    if super_scope.languages:
+        if not sub_scope.languages:
+            return False
+        super_langs = {l.lower() for l in super_scope.languages}
+        sub_langs = {l.lower() for l in sub_scope.languages}
+        if not sub_langs.issubset(super_langs):
+            return False
+
+    # Path coverage check
+    if super_scope.paths:
+        if not sub_scope.paths:
+            return False
+        for sub_p in sub_scope.paths:
+            covered = any(is_path_subsumed(sub_p, sup_p) for sup_p in super_scope.paths)
+            if not covered:
+                return False
+
+    return True
+
+
+def archive_rule(
+    rule: InvariantRule,
+    reason: str,
+    substrate_dir: Path | str = ".agents/substrate",
+    event_log_path: Optional[Path | str] = None,
+) -> Path:
+    """Move a rule to archive status and log a blackboard event."""
+    sub_path = Path(substrate_dir)
+    if (sub_path / ".agents" / "substrate").is_dir():
+        sub_path = sub_path / ".agents" / "substrate"
+
+    archive_dir = sub_path / "archive"
+    archive_dir.mkdir(parents=True, exist_ok=True)
+
+    rule_dict = rule.to_dict()
+    rule_dict["status"] = "archive"
+    if "provenance" not in rule_dict:
+        rule_dict["provenance"] = {}
+    rule_dict["provenance"]["last_verified_at"] = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    target_file = archive_dir / f"{rule.id}.yaml"
+    with open(target_file, "w", encoding="utf-8") as f:
+        yaml.safe_dump(rule_dict, f, sort_keys=False)
+
+    if rule.file_path and rule.file_path.is_file():
+        rule.file_path.unlink()
+
+    rule.file_path = target_file
+    rule.status = "archive"
+
+    post_event(
+        {
+            "type": "RULE_ARCHIVED",
+            "sender": "evolutionary-curator-v1",
+            "payload": {
+                "rule_id": rule.id,
+                "reason": reason,
+            },
+        },
+        event_log_path=event_log_path,
+    )
+
+    return target_file
+
+
+def curate_substrate(
+    substrate_dir: Path | str = ".agents/substrate",
+    dry_run: bool = False,
+    event_log_path: Optional[Path | str] = None,
+) -> list[CurationAction]:
+    """Inspect active rules for duplicate or subsumed invariants and prune them."""
+    rules, _ = discover_rules(substrate_dir, statuses={"active"})
+    actions: list[CurationAction] = []
+
+    # Sort rules deterministically by id
+    rules = sorted(rules, key=lambda r: r.id)
+
+    # Detect subsumption: Rule B has identical statement but narrower scope than Rule A
+    archived_ids: set[str] = set()
+    for i, r_super in enumerate(rules):
+        if r_super.id in archived_ids:
+            continue
+        for j, r_sub in enumerate(rules):
+            if i == j or r_sub.id in archived_ids:
+                continue
+            # Compare statements
+            same_statement = r_super.invariant.statement.strip().lower() == r_sub.invariant.statement.strip().lower()
+            if same_statement and is_scope_subsumed(r_sub.scope, r_super.scope):
+                reason = f"Subsumed by broader rule '{r_super.id}' with identical invariant statement."
+                action = CurationAction(
+                    rule_id=r_sub.id,
+                    action_type="ARCHIVE_SUBSUMED",
+                    reason=reason,
+                    superseded_by=r_super.id,
+                )
+                actions.append(action)
+                archived_ids.add(r_sub.id)
+                if not dry_run:
+                    archive_rule(
+                        r_sub,
+                        reason=reason,
+                        substrate_dir=substrate_dir,
+                        event_log_path=event_log_path,
+                    )
+
+    return actions

aos/daemon.py

@@ -0,0 +1,121 @@
+"""Autonomous background daemon for reactive auditing, event interception, and curation."""
+
+from __future__ import annotations
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from aos.blackboard import BlackboardEvent, get_default_event_log, post_event, read_events
+from aos.curator import curate_substrate
+from aos.engine import RuleEngine
+
+
+@dataclass
+class DaemonState:
+    processed_event_ids: set[str] = field(default_factory=set)
+    injected_intent_ids: set[str] = field(default_factory=set)
+    curation_interval_seconds: float = 300.0
+    last_curation_timestamp: float = 0.0
+
+
+class SubstrateDaemon:
+    """Continuous background engine that audits announced intents and curates rules."""
+
+    def __init__(
+        self,
+        root_dir: Path | str = ".",
+        event_log_path: Optional[Path | str] = None,
+        poll_interval: float = 2.0,
+        curation_interval: float = 60.0,
+    ) -> None:
+        self.root_dir = Path(root_dir)
+        self.event_log_path = Path(event_log_path) if event_log_path else get_default_event_log(self.root_dir)
+        self.poll_interval = poll_interval
+        self.state = DaemonState(curation_interval_seconds=curation_interval)
+        self.engine = RuleEngine(root_dir=self.root_dir)
+
+    def process_event(self, event: BlackboardEvent) -> Optional[BlackboardEvent]:
+        """Inspect a single event and generate autonomous reactions if required."""
+        if event.event_id in self.state.processed_event_ids:
+            return None
+
+        self.state.processed_event_ids.add(event.event_id)
+
+        # Reactive Auditor: intercept INTENT_ANNOUNCEMENT
+        if event.type == "INTENT_ANNOUNCEMENT":
+            payload = event.payload
+            intent_id = payload.get("intent_id", "")
+            target_files = payload.get("target_files", [])
+
+            if intent_id and intent_id not in self.state.injected_intent_ids and target_files:
+                self.engine.reload()
+                matched_rules_map = self.engine.match_files(target_files, status="active")
+
+                # Collect unique rules
+                applicable_rule_ids: list[str] = []
+                required_checks: list[str] = []
+                seen_rules: set[str] = set()
+
+                for f_path, rules in matched_rules_map.items():
+                    for r in rules:
+                        if r.id not in seen_rules:
+                            seen_rules.add(r.id)
+                            applicable_rule_ids.append(r.id)
+                            check_desc = f"rule:{r.id} ({r.invariant.enforcement})"
+                            if r.invariant.max_blast_radius_lines is not None:
+                                check_desc += f", max_diff_lines:{r.invariant.max_blast_radius_lines}"
+                            required_checks.append(check_desc)
+
+                injection_event = post_event(
+                    {
+                        "type": "INVARIANT_INJECTION",
+                        "sender": "daemon-auditor-agent",
+                        "payload": {
+                            "intent_id": intent_id,
+                            "applicable_rules": applicable_rule_ids,
+                            "required_checks": required_checks,
+                            "target_files": target_files,
+                        },
+                    },
+                    event_log_path=self.event_log_path,
+                )
+
+                self.state.injected_intent_ids.add(intent_id)
+                self.state.processed_event_ids.add(injection_event.event_id)
+                return injection_event
+
+        return None
+
+    def tick(self) -> list[BlackboardEvent]:
+        """Execute a single polling step: process new events and check curation schedule."""
+        generated: list[BlackboardEvent] = []
+
+        # 1. Read existing events and process unprocessed ones
+        events = read_events(event_log_path=self.event_log_path)
+        for ev in events:
+            reaction = self.process_event(ev)
+            if reaction is not None:
+                generated.append(reaction)
+
+        # 2. Check periodic curation tick
+        now = time.time()
+        if (now - self.state.last_curation_timestamp) >= self.state.curation_interval_seconds:
+            self.state.last_curation_timestamp = now
+            curate_substrate(
+                substrate_dir=self.root_dir / ".agents" / "substrate",
+                event_log_path=self.event_log_path,
+            )
+
+        return generated
+
+    def run(self, max_ticks: Optional[int] = None) -> None:
+        """Run the daemon loop until interrupted or max_ticks reached."""
+        ticks_done = 0
+        try:
+            while max_ticks is None or ticks_done < max_ticks:
+                self.tick()
+                ticks_done += 1
+                time.sleep(self.poll_interval)
+        except KeyboardInterrupt:
+            pass

aos/discovery.py

@@ -0,0 +1,72 @@
+"""Rule discovery and loading from the substrate filesystem."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+import yaml
+
+from aos.models import InvariantRule
+from aos.validator import validate_rule_dict
+
+
+def load_rule_file(file_path: Path) -> tuple[Optional[InvariantRule], list[str]]:
+    """Load, parse, and validate a single rule file from disk."""
+    if not file_path.is_file():
+        return None, [f"File not found: {file_path}"]
+
+    try:
+        content = file_path.read_text(encoding="utf-8")
+        data = yaml.safe_load(content)
+    except Exception as exc:
+        return None, [f"Failed to parse YAML in {file_path}: {exc}"]
+
+    if not isinstance(data, dict):
+        return None, [f"Expected mapping in {file_path}, got {type(data).__name__}"]
+
+    is_valid, errors = validate_rule_dict(data)
+    if not is_valid:
+        prefixed = [f"Validation failure in {file_path}: {err}" for err in errors]
+        return None, prefixed
+
+    rule = InvariantRule.from_dict(data, file_path=file_path)
+    return rule, []
+
+
+def discover_rules(
+    substrate_dir: Path | str,
+    statuses: Optional[set[str]] = None,
+) -> tuple[list[InvariantRule], list[str]]:
+    """Discover all invariant rules in the substrate directory tree.
+
+    Args:
+        substrate_dir: Path to .agents/substrate/ or repository root.
+        statuses: Optional filter for rule status (e.g. {'active'}).
+
+    Returns:
+        tuple: (list of valid InvariantRule instances, list of error messages)
+    """
+    base = Path(substrate_dir)
+    if (base / ".agents" / "substrate").is_dir():
+        base = base / ".agents" / "substrate"
+
+    rules: list[InvariantRule] = []
+    diagnostics: list[str] = []
+
+    subdirs = ["active", "candidate", "archive"]
+    target_dirs = [base / sub for sub in subdirs if (base / sub).is_dir()]
+
+    # If none of the subdirs exist, inspect base itself
+    if not target_dirs and base.is_dir():
+        target_dirs = [base]
+
+    for directory in target_dirs:
+        for ext in ("*.yaml", "*.yml"):
+            for file_path in sorted(directory.glob(ext)):
+                rule, errors = load_rule_file(file_path)
+                if errors:
+                    diagnostics.extend(errors)
+                if rule is not None:
+                    if statuses is None or rule.status in statuses:
+                        rules.append(rule)
+
+    return rules, diagnostics