cortex-loop 0.1.0a1__py3-none-any.whl

cortex/stop_policy.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class StopVerdict:
+    session_status: str
+    recommend_revert: bool
+    proceed: bool
+    feedback_mode: str
+
+
+def compute_stop_outcome(
+    *,
+    mode: str,
+    fail_on_missing_challenge_coverage: bool,
+    fail_on_requirement_audit_gap: bool,
+    require_requirement_audit: bool,
+    challenge_ok: bool | None,
+    invariant_ok: bool | None,
+    invariant_recommend_revert: bool,
+    missing_challenge_coverage: bool,
+    requirements_gate_gap: bool,
+    requirement_audit_missing: bool,
+    structured_stop_violation: bool,
+    loop_detected: bool = False,
+    stuck_declared: bool = False,
+) -> StopVerdict:
+    strict_mode = mode == "strict"
+    strict_challenge_gate = strict_mode and fail_on_missing_challenge_coverage
+    challenge_gate_violation = _challenge_gate_violation(
+        strict_challenge_gate=strict_challenge_gate,
+        missing_challenge_coverage=missing_challenge_coverage,
+        challenge_ok=challenge_ok,
+    )
+    requirement_audit_violation = _requirement_audit_violation(
+        strict_mode=strict_mode,
+        fail_on_requirement_audit_gap=fail_on_requirement_audit_gap,
+        requirements_gate_gap=requirements_gate_gap,
+        requirement_audit_missing=requirement_audit_missing,
+        require_requirement_audit=require_requirement_audit,
+    )
+
+    base_status = "completed"
+    if invariant_ok is False:
+        base_status = "failed_invariants"
+    elif structured_stop_violation:
+        base_status = "failed_stop_contract"
+    elif requirement_audit_violation:
+        base_status = "failed_requirements"
+    elif challenge_ok is False:
+        base_status = "failed_challenges"
+    elif missing_challenge_coverage and strict_challenge_gate:
+        base_status = "missing_challenge_coverage"
+
+    if base_status != "completed" and stuck_declared:
+        return StopVerdict(
+            session_status="stuck",
+            recommend_revert=False,
+            proceed=False,
+            feedback_mode="stuck",
+        )
+
+    recommend_revert = bool(
+        invariant_recommend_revert
+        or challenge_gate_violation
+        or requirement_audit_violation
+        or (strict_mode and structured_stop_violation)
+    )
+    return StopVerdict(
+        session_status=base_status,
+        recommend_revert=recommend_revert,
+        proceed=not recommend_revert,
+        feedback_mode="reconsider_approach" if base_status != "completed" and loop_detected else "normal",
+    )
+
+
+def _challenge_gate_violation(
+    *,
+    strict_challenge_gate: bool,
+    missing_challenge_coverage: bool,
+    challenge_ok: bool | None,
+) -> bool:
+    return strict_challenge_gate and (missing_challenge_coverage or challenge_ok is False)
+
+
+def _requirement_audit_violation(
+    *,
+    strict_mode: bool,
+    fail_on_requirement_audit_gap: bool,
+    requirements_gate_gap: bool,
+    requirement_audit_missing: bool,
+    require_requirement_audit: bool,
+) -> bool:
+    return bool(
+        strict_mode
+        and fail_on_requirement_audit_gap
+        and (requirements_gate_gap or (requirement_audit_missing and require_requirement_audit))
+    )

cortex/stop_runtime.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .challenges import ChallengeEnforcer, ChallengeReport
+from .core_helpers import (
+    session_changed_files_since_baseline,
+    session_git_snapshot,
+    session_metadata,
+    session_required_requirement_ids,
+    session_witness_context,
+)
+from .genome import CortexGenome
+from .graveyard import Graveyard
+from .invariants import InvariantReport, InvariantRunner
+from .requirements import (
+    RequirementAuditEvaluation,
+    TruthClaimsEvaluation,
+    evaluate_requirement_audit_payload,
+    evaluate_truth_claims_payload,
+)
+from .stop_contract import (
+    StopContract,
+    reconcile_required_requirement_ids,
+    structured_stop_contract_diagnostic,
+)
+from .stop_policy import compute_stop_outcome
+from .stop_signals import build_stop_attempt_signature, stop_attempt_similarity
+from .store import SQLiteStore
+from .utils import _as_bool, _as_string_list
+
+LOOP_WARNING = (
+    "Stop attempt is highly similar to the previous failed Stop; reconsider the approach "
+    "instead of refining the same attempt."
+)
+
+
+@dataclass(slots=True)
+class StopPathOutcome:
+    warnings: list[str]
+    challenge_report: ChallengeReport | None
+    challenge_diagnostics: list[dict[str, Any]]
+    missing_challenge_coverage: bool
+    invariant_report: InvariantReport | None
+    requirement_audit: RequirementAuditEvaluation
+    truth_claims: TruthClaimsEvaluation
+    required_requirement_ids: list[str]
+    required_requirement_ids_source: str
+    contract_diagnostic: dict[str, Any] | None
+    git_snapshot: dict[str, Any] | None
+    stuck_declaration: dict[str, Any] | None
+    structured_stop_violation: bool
+    strict_message_fallback_violation: bool
+    enforcement_pass: bool
+    session_status: str
+    recommend_revert: bool
+    proceed: bool
+    feedback_mode: str
+    stop_attempt_signature: dict[str, Any]
+    loop_detected: bool
+    loop_similarity: float | None
+
+
+class StopPathRunner:
+    def __init__(
+        self,
+        *,
+        root: Path,
+        store: SQLiteStore,
+        genome: CortexGenome,
+        challenges: ChallengeEnforcer,
+        invariants: InvariantRunner,
+        graveyard: Graveyard,
+        session_metadata_loader: Callable[[SQLiteStore, str], dict[str, Any]] = session_metadata,
+        session_git_snapshotter: Callable[[Path], dict[str, Any]] = session_git_snapshot,
+        session_changed_files_since_baseline_fn: Callable[
+            ..., tuple[list[str] | None, str | None]
+        ] = session_changed_files_since_baseline,
+        session_required_requirement_ids_loader: Callable[
+            [SQLiteStore, str], list[str]
+        ] = session_required_requirement_ids,
+        session_witness_context_loader: Callable[
+            [SQLiteStore, str], Mapping[str, list[str]]
+        ] = session_witness_context,
+    ) -> None:
+        self.root = root
+        self.store = store
+        self.genome = genome
+        self.challenges = challenges
+        self.invariants = invariants
+        self.graveyard = graveyard
+        self._session_metadata = session_metadata_loader
+        self._session_git_snapshot = session_git_snapshotter
+        self._session_changed_files_since_baseline = session_changed_files_since_baseline_fn
+        self._session_required_requirement_ids = session_required_requirement_ids_loader
+        self._session_witness_context = session_witness_context_loader
+
+    def run(
+        self,
+        *,
+        session_id: str,
+        payload: Mapping[str, Any],
+        stop_contract: StopContract,
+    ) -> StopPathOutcome:
+        session_meta = self._session_metadata(self.store, session_id)
+        warnings = list(stop_contract.warnings)
+        baseline_git_snapshot = (
+            dict(session_meta.get("git_snapshot"))
+            if isinstance(session_meta.get("git_snapshot"), Mapping)
+            else None
+        )
+        strict_message_fallback_violation = (
+            self.genome.hooks.mode == "strict" and stop_contract.stop_source == "message_fallback"
+        )
+        contract_diagnostic = stop_contract.contract_diagnostic
+        if strict_message_fallback_violation:
+            warnings.append(
+                "Strict mode rejects Stop message-fallback payloads; send stop fields natively or via payload.stop_fields."
+            )
+            if contract_diagnostic is None:
+                contract_diagnostic = structured_stop_contract_diagnostic(
+                    "strict_message_fallback_rejected"
+                )
+
+        coverage_payload = stop_contract.challenge_coverage
+        challenge_report: ChallengeReport | None = None
+        challenge_diagnostics: list[dict[str, Any]] = []
+        missing_challenge_coverage = False
+        require_verifiable_challenge_coverage = (
+            self.genome.hooks.mode == "strict"
+            and self.genome.hooks.fail_on_missing_challenge_coverage
+        )
+        needs_witness = bool(
+            (require_verifiable_challenge_coverage and isinstance(coverage_payload, Mapping))
+            or stop_contract.requirement_audit is not None
+            or stop_contract.truth_claims is not None
+        )
+        witness = (
+            self._session_witness_context(self.store, session_id)
+            if needs_witness
+            else {"commands": [], "tools": []}
+        )
+        if isinstance(coverage_payload, Mapping):
+            challenge_report = self.challenges.evaluate(
+                session_id=session_id,
+                coverage_payload=coverage_payload,
+                require_verifiable_coverage=require_verifiable_challenge_coverage,
+                root=self.root,
+                witness=witness,
+            )
+            if not challenge_report.ok:
+                warnings.append(
+                    "Missing challenge coverage for categories: "
+                    + ", ".join(challenge_report.missing_categories)
+                )
+            warnings.extend(challenge_report.config_warnings)
+            challenge_diagnostics = list(challenge_report.diagnostics)
+        elif coverage_payload is not None:
+            missing_challenge_coverage = self.genome.challenges.require_coverage
+            warnings.append(
+                "Invalid challenge_coverage format; expected an object mapping category names to values."
+            )
+            challenge_diagnostics = self.challenges.invalid_coverage_diagnostics(coverage_payload)
+        elif self.genome.challenges.require_coverage:
+            missing_challenge_coverage = True
+            message = (
+                "No challenge_coverage provided in Stop payload; skipping challenge gate recording. "
+                "Include challenge_coverage directly or via payload.stop_fields"
+            )
+            if self.genome.hooks.allow_message_stop_fallback:
+                message += ", or as a STOP_FIELDS_JSON trailer"
+            warnings.append(message + ".")
+            challenge_diagnostics = self.challenges.missing_coverage_diagnostics()
+
+        required_requirement_ids, requirement_ids_source, required_ids_warning = (
+            reconcile_required_requirement_ids(
+                self._session_required_requirement_ids(self.store, session_id),
+                list(stop_contract.required_requirement_ids),
+            )
+        )
+        if required_ids_warning:
+            warnings.append(required_ids_warning)
+
+        truth_claims_payload = (
+            stop_contract.truth_claims if isinstance(stop_contract.truth_claims, Mapping) else None
+        )
+        has_modified_files_claim = bool(
+            truth_claims_payload and _as_string_list(truth_claims_payload.get("modified_files"))
+        )
+        observed_modified_files: list[str] | None = None
+        modified_files_error: str | None = None
+        if has_modified_files_claim:
+            current_git_snapshot = self._session_git_snapshot(self.root)
+            observed_modified_files, modified_files_error = self._session_changed_files_since_baseline(
+                baseline_snapshot=baseline_git_snapshot,
+                current_snapshot=current_git_snapshot,
+            )
+
+        requirement_audit = evaluate_requirement_audit_payload(
+            stop_contract.requirement_audit,
+            require_requirement_audit=self.genome.hooks.require_requirement_audit,
+            require_evidence_for_passed_requirement=self.genome.hooks.require_evidence_for_passed_requirement,
+            required_requirement_ids=required_requirement_ids,
+            root=self.root,
+            witness=witness,
+        )
+        warnings.extend(requirement_audit.warnings)
+        truth_claims = evaluate_truth_claims_payload(
+            stop_contract.truth_claims,
+            root=self.root,
+            witness=witness,
+            observed_modified_files=observed_modified_files,
+            modified_files_error=modified_files_error,
+        )
+        warnings.extend(truth_claims.warnings)
+
+        invariant_report = None
+        if self.genome.invariants.run_on_stop and _as_bool(payload.get("run_invariants"), True):
+            invariant_report = self.invariants.run(
+                session_id=session_id,
+                extra_pytest_args=_as_string_list(payload.get("pytest_args")),
+            )
+            if not invariant_report.ok:
+                warnings.append("Invariant suite reported failures.")
+
+        if stop_contract.failed_approach:
+            self.graveyard.record_failure(
+                session_id=session_id,
+                summary=str(stop_contract.failed_approach["summary"]),
+                reason=str(stop_contract.failed_approach["reason"]),
+                files=_as_string_list(stop_contract.failed_approach.get("files")),
+            )
+
+        structured_stop_violation = (
+            stop_contract.structured_stop_violation or strict_message_fallback_violation
+        )
+        challenge_ok = None if challenge_report is None else challenge_report.ok
+        invariant_ok = None if invariant_report is None else invariant_report.ok
+        requirements_gate_gap = requirement_audit.gap or truth_claims.gap
+        stop_attempt_signature = build_stop_attempt_signature(
+            challenge_coverage=coverage_payload if isinstance(coverage_payload, Mapping) else None,
+            witness=witness,
+            truth_claims_payload=truth_claims_payload,
+            failed_approach=stop_contract.failed_approach,
+            observed_modified_files=observed_modified_files,
+        )
+        previous_signature = session_meta.get("stop_attempt_signature")
+        loop_similarity = stop_attempt_similarity(
+            previous_signature if isinstance(previous_signature, Mapping) else None,
+            stop_attempt_signature,
+        )
+        loop_detected = bool(loop_similarity is not None and loop_similarity >= 0.85)
+        verdict = compute_stop_outcome(
+            mode=self.genome.hooks.mode,
+            fail_on_missing_challenge_coverage=self.genome.hooks.fail_on_missing_challenge_coverage,
+            fail_on_requirement_audit_gap=self.genome.hooks.fail_on_requirement_audit_gap,
+            require_requirement_audit=self.genome.hooks.require_requirement_audit,
+            challenge_ok=challenge_ok,
+            invariant_ok=invariant_ok,
+            invariant_recommend_revert=bool(invariant_report and invariant_report.recommend_revert),
+            missing_challenge_coverage=missing_challenge_coverage,
+            requirements_gate_gap=requirements_gate_gap,
+            requirement_audit_missing=requirement_audit.missing,
+            structured_stop_violation=structured_stop_violation,
+            loop_detected=loop_detected,
+            stuck_declared=stop_contract.stuck_declaration is not None,
+        )
+        if loop_detected and verdict.session_status != "completed":
+            warnings.append(LOOP_WARNING)
+        enforcement_pass = verdict.session_status == "completed"
+
+        return StopPathOutcome(
+            warnings=warnings,
+            challenge_report=challenge_report,
+            challenge_diagnostics=challenge_diagnostics,
+            missing_challenge_coverage=missing_challenge_coverage,
+            invariant_report=invariant_report,
+            requirement_audit=requirement_audit,
+            truth_claims=truth_claims,
+            required_requirement_ids=required_requirement_ids,
+            required_requirement_ids_source=requirement_ids_source,
+            contract_diagnostic=contract_diagnostic,
+            git_snapshot=baseline_git_snapshot,
+            stuck_declaration=stop_contract.stuck_declaration,
+            structured_stop_violation=structured_stop_violation,
+            strict_message_fallback_violation=strict_message_fallback_violation,
+            enforcement_pass=enforcement_pass,
+            session_status=verdict.session_status,
+            recommend_revert=verdict.recommend_revert,
+            proceed=verdict.proceed,
+            feedback_mode=verdict.feedback_mode,
+            stop_attempt_signature=stop_attempt_signature,
+            loop_detected=loop_detected,
+            loop_similarity=loop_similarity,
+        )
+
+    @staticmethod
+    def close_session_metadata(
+        *,
+        outcome: StopPathOutcome,
+        stop_contract: StopContract,
+        executive_signature: str | None,
+        executive_record: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        challenge_report = outcome.challenge_report
+        invariant_report = outcome.invariant_report
+        requirement_audit = outcome.requirement_audit
+        truth_claims = outcome.truth_claims
+        requirement_audit_gap = requirement_audit.gap
+        truth_claims_gap = truth_claims.gap
+        requirements_gate_gap = requirement_audit_gap or truth_claims_gap
+        challenge_ok = None if challenge_report is None else challenge_report.ok
+        invariant_ok = None if invariant_report is None else invariant_report.ok
+        return {
+            "hook": "Stop",
+            "enforcement_pass": outcome.enforcement_pass,
+            "challenge_ok": challenge_ok,
+            "challenge_diagnostics": outcome.challenge_diagnostics,
+            "challenge_coverage_missing": outcome.missing_challenge_coverage,
+            "challenge_unverified_categories": (
+                [] if challenge_report is None else challenge_report.unverified_categories
+            ),
+            "challenge_uncheckable_categories": (
+                [] if challenge_report is None else challenge_report.uncheckable_categories
+            ),
+            "invariant_ok": invariant_ok,
+            "requirement_audit_ok": (
+                None if requirement_audit.details is None else requirement_audit.details["ok"]
+            ),
+            "requirement_audit_diagnostics": requirement_audit.diagnostics,
+            "requirement_audit_missing": requirement_audit.missing,
+            "requirement_audit_gap": requirement_audit_gap,
+            "truth_claims_ok": None if truth_claims.report is None else truth_claims.report["ok"],
+            "truth_claims_diagnostics": truth_claims.diagnostics,
+            "truth_claims_gap": truth_claims_gap,
+            "requirements_gate_gap": requirements_gate_gap,
+            "required_requirement_ids": outcome.required_requirement_ids,
+            "required_requirement_ids_source": outcome.required_requirement_ids_source,
+            "contract_diagnostic": outcome.contract_diagnostic,
+            "git_snapshot": outcome.git_snapshot,
+            "stuck_declared": outcome.stuck_declaration is not None,
+            "stuck_declaration": outcome.stuck_declaration,
+            "structured_stop_violation": outcome.structured_stop_violation,
+            "stop_source": stop_contract.stop_source,
+            "stop_fields_source": stop_contract.stop_fields_source,
+            "stop_fields_fallback_used": stop_contract.stop_fields_fallback_used,
+            "stop_key_normalization_count": stop_contract.stop_key_normalization_count,
+            "strict_message_fallback_violation": outcome.strict_message_fallback_violation,
+            "feedback_mode": outcome.feedback_mode,
+            "stop_attempt_signature": outcome.stop_attempt_signature,
+            "loop_detected": outcome.loop_detected,
+            "loop_similarity": outcome.loop_similarity,
+            "executive_last_stop_signature": executive_signature,
+            "executive_memory_recorded": bool(executive_record),
+            "executive_memory_record_id": None if executive_record is None else executive_record["id"],
+        }
+
+    @staticmethod
+    def response_payload(
+        *,
+        outcome: StopPathOutcome,
+        stop_contract: StopContract,
+    ) -> dict[str, Any]:
+        challenge_report = outcome.challenge_report
+        requirement_audit = outcome.requirement_audit
+        truth_claims = outcome.truth_claims
+        return {
+            "session_status": outcome.session_status,
+            "challenge_report": None if challenge_report is None else challenge_report.to_dict(),
+            "challenge_diagnostics": outcome.challenge_diagnostics,
+            "challenge_coverage_missing": outcome.missing_challenge_coverage,
+            "invariant_report": None if outcome.invariant_report is None else outcome.invariant_report.to_dict(),
+            "requirement_audit_report": requirement_audit.report,
+            "requirement_audit_diagnostics": requirement_audit.diagnostics,
+            "truth_claims_report": truth_claims.report,
+            "truth_claims_diagnostics": truth_claims.diagnostics,
+            "required_requirement_ids": outcome.required_requirement_ids,
+            "requirement_audit_missing": requirement_audit.missing,
+            "requirement_audit_gap": requirement_audit.gap,
+            "truth_claims_gap": truth_claims.gap,
+            "requirements_gate_gap": requirement_audit.gap or truth_claims.gap,
+            "enforcement_pass": outcome.enforcement_pass,
+            "contract_diagnostic": outcome.contract_diagnostic,
+            "stuck_declared": outcome.stuck_declaration is not None,
+            "stuck_declaration": outcome.stuck_declaration,
+            "structured_stop_violation": outcome.structured_stop_violation,
+            "stop_source": stop_contract.stop_source,
+            "stop_fields_source": stop_contract.stop_fields_source,
+            "stop_fields_fallback_used": stop_contract.stop_fields_fallback_used,
+            "stop_key_normalization_count": stop_contract.stop_key_normalization_count,
+            "feedback_mode": outcome.feedback_mode,
+            "stop_attempt_signature": outcome.stop_attempt_signature,
+            "loop_detected": outcome.loop_detected,
+            "loop_similarity": outcome.loop_similarity,
+            "recommend_revert": outcome.recommend_revert,
+            "proceed": outcome.proceed,
+        }

cortex/stop_signals.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .utils import _as_string_list
+
+
+def build_stop_attempt_signature(
+    *,
+    challenge_coverage: Mapping[str, Any] | None,
+    witness: Mapping[str, list[str]] | None,
+    truth_claims_payload: Mapping[str, Any] | None,
+    failed_approach: Mapping[str, Any] | None,
+    observed_modified_files: list[str] | None,
+) -> dict[str, Any]:
+    challenge_shape: list[str] = []
+    if isinstance(challenge_coverage, Mapping):
+        for category in sorted(str(key).strip() for key in challenge_coverage.keys()):
+            raw = challenge_coverage.get(category)
+            if isinstance(raw, Mapping):
+                challenge_shape.append(f"{category}:covered={bool(raw.get('covered', False))}")
+            else:
+                challenge_shape.append(f"{category}:covered={bool(raw)}")
+
+    witnessed_commands = sorted(
+        {
+            normalize_stop_command_signal(command)
+            for command in _as_string_list((witness or {}).get("commands"))
+            if normalize_stop_command_signal(command)
+        }
+    )
+    file_signal = sorted(
+        {
+            path
+            for path in (
+                _as_string_list((truth_claims_payload or {}).get("modified_files"))
+                + _as_string_list((failed_approach or {}).get("files"))
+                + _as_string_list(observed_modified_files)
+            )
+            if path
+        }
+    )
+    return {
+        "challenge_shape": challenge_shape,
+        "witnessed_commands": witnessed_commands,
+        "file_signal": file_signal,
+    }
+
+
+def stop_attempt_similarity(previous: Mapping[str, Any] | None, current: Mapping[str, Any]) -> float | None:
+    if not isinstance(previous, Mapping):
+        return None
+    scores = [
+        _signal_jaccard(previous.get("challenge_shape"), current.get("challenge_shape")),
+        _signal_jaccard(previous.get("witnessed_commands"), current.get("witnessed_commands")),
+        _signal_jaccard(previous.get("file_signal"), current.get("file_signal")),
+    ]
+    present_scores = [score for score in scores if score is not None]
+    return round(sum(present_scores) / len(present_scores), 3) if present_scores else None
+
+
+def normalize_stop_command_signal(command: str) -> str:
+    return " ".join(str(command).strip().lower().split())
+
+
+def _signal_jaccard(left: Any, right: Any) -> float | None:
+    left_set = set(_as_string_list(left))
+    right_set = set(_as_string_list(right))
+    if not left_set and not right_set:
+        return None
+    union = left_set | right_set
+    if not union:
+        return None
+    return len(left_set & right_set) / len(union)