briefloop 0.11.12__py3-none-any.whl

multi_agent_brief/orchestrator/runtime_state/contracts_loader.py

@@ -0,0 +1,66 @@
+"""Runtime-state contract loading helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.orchestrator.runtime_state._io import _load_yaml
+from multi_agent_brief.orchestrator.runtime_state.errors import RuntimeStateError
+from multi_agent_brief.orchestrator_contract import CONTRACT_REFERENCES
+
+
+def _contract_file(repo_workdir: Path, rel_path: str) -> Path:
+    path = repo_workdir / rel_path
+    if not path.exists():
+        raise RuntimeStateError(
+            f"Contract file not found: {path}",
+            details={"contract": rel_path, "repo_workdir": str(repo_workdir)},
+        )
+    return path
+
+
+def load_stage_specs(repo_workdir: str | Path) -> list[dict[str, Any]]:
+    repo = Path(repo_workdir).expanduser().resolve()
+    data = _load_yaml(_contract_file(repo, CONTRACT_REFERENCES["stage_specs"]))
+    stages = ((data.get("workflow") or {}).get("stages") or [])
+    if not isinstance(stages, list):
+        raise RuntimeStateError("stage_specs.yaml workflow.stages must be a list")
+    return [stage for stage in stages if isinstance(stage, dict)]
+
+
+def load_artifact_contracts(repo_workdir: str | Path) -> list[dict[str, Any]]:
+    repo = Path(repo_workdir).expanduser().resolve()
+    data = _load_yaml(_contract_file(repo, CONTRACT_REFERENCES["artifact_contracts"]))
+    artifacts = data.get("artifacts") or []
+    if not isinstance(artifacts, list):
+        raise RuntimeStateError("artifact_contracts.yaml artifacts must be a list")
+    return [artifact for artifact in artifacts if isinstance(artifact, dict)]
+
+
+def load_default_policy_pack(repo_workdir: str | Path) -> dict[str, Any]:
+    repo = Path(repo_workdir).expanduser().resolve()
+    data = _load_yaml(_contract_file(repo, CONTRACT_REFERENCES["default_policy_pack"]))
+    if not isinstance(data, dict):
+        raise RuntimeStateError("policy_packs/default.yaml must contain an object")
+    return data
+
+
+def _stage_ids(stages: list[dict[str, Any]]) -> list[str]:
+    return [str(stage["stage_id"]) for stage in stages if stage.get("stage_id")]
+
+
+def _artifact_ids(artifacts: list[dict[str, Any]]) -> set[str]:
+    return {
+        str(artifact["artifact_id"])
+        for artifact in artifacts
+        if artifact.get("artifact_id")
+    }
+
+
+def _artifact_map(artifacts: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
+    return {
+        str(artifact["artifact_id"]): artifact
+        for artifact in artifacts
+        if artifact.get("artifact_id")
+    }

multi_agent_brief/orchestrator/runtime_state/decisions.py

@@ -0,0 +1,239 @@
+"""Decision recording for runtime workflow state."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.orchestrator_contract import DECISION_VOCABULARY, resolve_repo_workdir
+from multi_agent_brief.orchestrator.runtime_state._io import _write_json_atomic
+from multi_agent_brief.orchestrator.runtime_state._transactions import _load_manifest_and_workflow
+from multi_agent_brief.orchestrator.runtime_state.contracts_loader import (
+    load_artifact_contracts,
+    load_stage_specs,
+)
+from multi_agent_brief.orchestrator.runtime_state.errors import (
+    E_COMPLETION_TRANSACTION_REQUIRED,
+    E_ILLEGAL_TRANSITION,
+    RuntimeStateError,
+)
+from multi_agent_brief.orchestrator.runtime_state.event_log import (
+    _read_event_log_records,
+    append_event,
+)
+from multi_agent_brief.orchestrator.runtime_state.identity import utc_now
+from multi_agent_brief.orchestrator.runtime_state.lifecycle import (
+    initialize_runtime_state,
+    show_runtime_state,
+)
+from multi_agent_brief.orchestrator.runtime_state.paths import (
+    _require_workspace,
+    runtime_state_paths,
+)
+from multi_agent_brief.orchestrator.runtime_state.repair import _delegate_repair_transaction_required_error
+from multi_agent_brief.orchestrator.runtime_state.trajectory import (
+    TRAJECTORY_DECISION_NARROWING_STATUS,
+    TRAJECTORY_NARROWED_DECISIONS,
+    _trajectory_decision_narrowing,
+    _trajectory_narrowing_changed,
+    _workflow_with_trajectory_decision_narrowing,
+)
+from multi_agent_brief.orchestrator.runtime_state.workflow import (
+    STAGE_BLOCKED,
+    STAGE_COMPLETE,
+    STAGE_READY,
+    _allowed_decisions_for_stage,
+    _next_stage_id,
+    _status_entry,
+)
+
+
+def record_decision(
+    *,
+    workspace: str | Path,
+    stage_id: str,
+    decision: str,
+    reason: str,
+    repo_workdir: str | Path | None = None,
+    actor: str = "orchestrator",
+) -> dict[str, Any]:
+    ws = _require_workspace(workspace)
+    paths = runtime_state_paths(ws)
+    if not paths["runtime_manifest"].exists() or not paths["workflow_state"].exists():
+        initialize_runtime_state(workspace=ws, repo_workdir=repo_workdir, actor=actor)
+
+    ws, paths, manifest, workflow = _load_manifest_and_workflow(ws)
+    workflow_before_decision = dict(workflow)
+    repo = resolve_repo_workdir(repo_workdir, workspace=ws)
+    stages = load_stage_specs(repo)
+    artifacts = load_artifact_contracts(repo)
+    stage_by_id = {str(stage.get("stage_id")): stage for stage in stages}
+    if stage_id not in stage_by_id:
+        raise RuntimeStateError(
+            f"Unknown stage: {stage_id}",
+            details={"stage_id": stage_id, "known_stages": list(stage_by_id)},
+        )
+    if decision not in DECISION_VOCABULARY:
+        raise RuntimeStateError(
+            f"Unknown Orchestrator decision: {decision}",
+            details={
+                "decision": decision,
+                "allowed_decisions": list(DECISION_VOCABULARY),
+            },
+        )
+    stage_allowed = [
+        str(item) for item in (stage_by_id[stage_id].get("allowed_decisions") or [])
+    ]
+    if decision not in stage_allowed:
+        raise RuntimeStateError(
+            f"Decision '{decision}' is not allowed for stage '{stage_id}'.",
+            details={
+                "stage_id": stage_id,
+                "decision": decision,
+                "stage_allowed_decisions": stage_allowed,
+            },
+        )
+    current_stage_before = workflow.get("current_stage")
+    if current_stage_before is None:
+        raise RuntimeStateError(
+            "Cannot record a decision because the workflow has no current stage.",
+            details={"stage_id": stage_id, "decision": decision},
+        )
+    if stage_id != current_stage_before:
+        raise RuntimeStateError(
+            f"Decision stage '{stage_id}' does not match current stage '{current_stage_before}'.",
+            details={
+                "stage_id": stage_id,
+                "current_stage": current_stage_before,
+                "decision": decision,
+            },
+        )
+
+    run_id = str(manifest["run_id"])
+    event_records = _read_event_log_records(paths["event_log"])
+    existing_narrowing = _trajectory_decision_narrowing(
+        workspace=ws,
+        workflow=workflow,
+        event_records=event_records,
+        run_id=run_id,
+    )
+    if existing_narrowing and decision not in TRAJECTORY_NARROWED_DECISIONS:
+        raise RuntimeStateError(
+            f"Decision '{decision}' is blocked because trajectory regulation narrowed current-stage decisions.",
+            details={
+                "stage_id": stage_id,
+                "decision": decision,
+                "allowed_decisions": list(TRAJECTORY_NARROWED_DECISIONS),
+                "trajectory_regulation": existing_narrowing,
+            },
+            error_code=E_ILLEGAL_TRANSITION,
+        )
+
+    if decision == "delegate_repair":
+        raise _delegate_repair_transaction_required_error(
+            workspace=ws,
+            stage_id=stage_id,
+            decision=decision,
+        )
+
+    if decision in {"continue", "finalize"}:
+        command = "finalize-complete" if decision == "finalize" else "stage-complete"
+        raise RuntimeStateError(
+            (
+                f"Decision '{decision}' must be recorded with `multi-agent-brief state {command}`. "
+                "`state decide` is reserved for retry_stage, delegate_repair, request_human_review, and block_run."
+            ),
+            details={
+                "stage_id": stage_id,
+                "decision": decision,
+                "required_command": command,
+            },
+            error_code=E_COMPLETION_TRANSACTION_REQUIRED,
+        )
+
+    now = utc_now()
+    statuses = dict(workflow.get("stage_statuses") or {})
+    blocked = False
+    blocking_reason = ""
+    current_stage: str | None = stage_id
+
+    if decision in {"continue", "finalize"}:
+        statuses[stage_id] = _status_entry(STAGE_COMPLETE, reason, now)
+        next_stage = _next_stage_id(stages, stage_id)
+        if next_stage and decision != "finalize":
+            statuses[next_stage] = _status_entry(STAGE_READY, "", now)
+            current_stage = next_stage
+        else:
+            current_stage = None
+    elif decision == "retry_stage":
+        statuses[stage_id] = _status_entry(STAGE_READY, reason, now)
+    elif decision in {"request_human_review", "block_run"}:
+        statuses[stage_id] = _status_entry(STAGE_BLOCKED, reason, now)
+        blocked = True
+        blocking_reason = reason
+
+    workflow["updated_at"] = now
+    workflow["current_stage"] = current_stage
+    workflow["blocked"] = blocked
+    workflow["blocking_reason"] = blocking_reason
+    workflow["stage_statuses"] = statuses
+    workflow["last_decision"] = {
+        "stage_id": stage_id,
+        "decision": decision,
+        "reason": reason,
+        "created_at": now,
+    }
+    decision_metadata = {"next_stage": current_stage}
+    post_decision_events = [
+        *event_records,
+        {
+            "run_id": run_id,
+            "event_type": "decision_recorded",
+            "stage_id": stage_id,
+            "decision": decision,
+            "reason": reason,
+            "metadata": decision_metadata,
+        },
+    ]
+    workflow = _workflow_with_trajectory_decision_narrowing(
+        workspace=ws,
+        workflow=workflow,
+        stages=stages,
+        event_records=post_decision_events,
+        run_id=run_id,
+    )
+    trajectory_narrowing_changed = _trajectory_narrowing_changed(
+        workflow_before_decision,
+        workflow,
+    )
+
+    append_event(
+        workspace=ws,
+        run_id=run_id,
+        event_type="decision_recorded",
+        actor=actor,
+        stage_id=stage_id,
+        decision=decision,
+        reason=reason,
+        metadata=decision_metadata,
+    )
+    narrowing = workflow.get("trajectory_regulation")
+    if (
+        trajectory_narrowing_changed
+        and isinstance(narrowing, dict)
+        and narrowing.get("status") == TRAJECTORY_DECISION_NARROWING_STATUS
+    ):
+        append_event(
+            workspace=ws,
+            run_id=run_id,
+            event_type="trajectory_decision_narrowed",
+            actor=actor,
+            stage_id=str(narrowing.get("stage_id") or stage_id),
+            reason=", ".join(str(item) for item in narrowing.get("reasons") or []),
+            metadata={
+                "allowed_decisions": list(narrowing.get("allowed_decisions") or []),
+                "recommended_actions": list(narrowing.get("recommended_actions") or []),
+            },
+        )
+    _write_json_atomic(paths["workflow_state"], workflow)
+    return show_runtime_state(workspace=ws)

multi_agent_brief/orchestrator/runtime_state/errors.py

@@ -0,0 +1,61 @@
+"""Runtime-state errors and error-code constants."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+E_STAGE_ALREADY_COMPLETED = "E_STAGE_ALREADY_COMPLETED"
+E_STAGE_MISMATCH = "E_STAGE_MISMATCH"
+E_REQUIRED_ARTIFACT_MISSING = "E_REQUIRED_ARTIFACT_MISSING"
+E_ARTIFACT_INVALID = "E_ARTIFACT_INVALID"
+E_CLAIM_DRAFT_CONTRACT_INVALID = "E_CLAIM_DRAFT_CONTRACT_INVALID"
+E_ILLEGAL_TRANSITION = "E_ILLEGAL_TRANSITION"
+E_MANIFEST_EXTENSION_LOST = "E_MANIFEST_EXTENSION_LOST"
+E_TRANSACTION_PARTIAL_WRITE = "E_TRANSACTION_PARTIAL_WRITE"
+E_TRANSACTION_INTEGRITY = "E_TRANSACTION_INTEGRITY"
+E_RUNTIME_STATE_NOT_INITIALIZED = "E_RUNTIME_STATE_NOT_INITIALIZED"
+E_RUN_ARCHIVE_FAILED = "E_RUN_ARCHIVE_FAILED"
+E_FACT_LAYER_IMPORT_INVALID = "E_FACT_LAYER_IMPORT_INVALID"
+E_QUALITY_GATE_REQUIRED = "E_QUALITY_GATE_REQUIRED"
+E_READER_FINAL_GATE_FAILED = "E_READER_FINAL_GATE_FAILED"
+E_COMPLETION_TRANSACTION_REQUIRED = "E_COMPLETION_TRANSACTION_REQUIRED"
+E_REPAIR_TRANSACTION_REQUIRED = "E_REPAIR_TRANSACTION_REQUIRED"
+E_REPAIR_IMPORTED_FACT_LAYER_FORBIDDEN = "E_REPAIR_IMPORTED_FACT_LAYER_FORBIDDEN"
+E_REPAIR_NO_LEGAL_ROUTE = "E_REPAIR_NO_LEGAL_ROUTE"
+E_FROZEN_GATE_REPORT_ALREADY_EXISTS = "E_FROZEN_GATE_REPORT_ALREADY_EXISTS"
+E_ACTIVE_REPAIR_OPEN = "E_ACTIVE_REPAIR_OPEN"
+E_ASSESSMENT_TARGET_COMPLETE = "E_ASSESSMENT_TARGET_COMPLETE"
+
+
+class RuntimeStateError(Exception):
+    """Raised when runtime state cannot be read or written safely."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        details: dict[str, Any] | None = None,
+        error_code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.details = details or {}
+        self.error_code = error_code
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "ok": False,
+            "error": str(self),
+            "details": self.details,
+        }
+        if self.error_code:
+            payload["error_code"] = self.error_code
+        return payload
+
+
+def _wrap_archive_error(exc: Any) -> RuntimeStateError:
+    return RuntimeStateError(
+        str(exc),
+        details=getattr(exc, "details", {}),
+        error_code=getattr(exc, "error_code", None) or E_RUN_ARCHIVE_FAILED,
+    )

multi_agent_brief/orchestrator/runtime_state/event_log.py

@@ -0,0 +1,256 @@
+"""Event-log helpers for Orchestrator runtime state."""
+
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+from typing import Any
+
+from multi_agent_brief.orchestrator.run_integrity import (
+    workflow_with_persistable_run_integrity as _workflow_with_persistable_run_integrity,
+)
+from multi_agent_brief.orchestrator.runtime_state._io import (
+    _append_jsonl,
+    _read_json_if_exists,
+)
+from multi_agent_brief.orchestrator.runtime_state.errors import (
+    E_RUNTIME_STATE_NOT_INITIALIZED,
+    E_TRANSACTION_INTEGRITY,
+    RuntimeStateError,
+)
+from multi_agent_brief.orchestrator.runtime_state.identity import _validate_runtime_run_id, utc_now
+from multi_agent_brief.orchestrator.runtime_state.manifest import RUNTIME_MANIFEST_SCHEMA
+from multi_agent_brief.orchestrator.runtime_state.paths import (
+    _require_workspace,
+    _workspace_relative,
+    runtime_state_paths,
+)
+from multi_agent_brief.orchestrator.runtime_state.workflow import WORKFLOW_STATE_SCHEMA
+
+
+EVENT_LOG_SCHEMA = "multi-agent-brief-event-log/v1"
+
+EVENT_TYPES = {
+    "run_initialized",
+    "handoff_written",
+    "artifact_observed",
+    "artifact_validated",
+    "stage_status_changed",
+    "stage_satisfied_by_topology",
+    "decision_recorded",
+    "feedback_issue_created",
+    "feedback_issue_planned",
+    "feedback_issue_resolved",
+    "repair_plan_created",
+    "repair_plan_completed",
+    "repair_started",
+    "repair_completed",
+    "quality_gate_checked",
+    "quality_gate_blocked",
+    "quality_gate_passed",
+    "provenance_graph_built",
+    "provenance_graph_validated",
+    "provenance_graph_invalid",
+    "audience_profile_snapshot_created",
+    "control_switchboard_built",
+    "control_switchboard_warning",
+    "control_selection_recorded",
+    "control_selection_validated",
+    "improvement_proposed",
+    "improvement_approved",
+    "improvement_rejected",
+    "improvement_reverted",
+    "improvement_memory_snapshot_created",
+    "delivery_attempted",
+    "delivery_draft_created",
+    "delivery_succeeded",
+    "delivery_failed",
+    "human_approval_ledger_initialized",
+    "human_approval_recorded",
+    "release_readiness_checked",
+    "fact_layer_imported",
+    "claim_ledger_frozen",
+    "claim_ledger_metadata_enriched",
+    "trajectory_decision_narrowed",
+    "run_archived",
+    "run_blocked",
+    "run_integrity_contaminated",
+    "run_reset",
+    "semantic_assessment_checked_inputs_bound",
+    "semantic_support_finding_adjudicated",
+}
+
+ACTORS = {"cli", "orchestrator", "runtime", "system"}
+
+
+def _read_event_log_records(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise RuntimeStateError(
+            f"Failed to read event log: {path}",
+            details={"path": str(path), "reason": str(exc)},
+        ) from exc
+    if raw and not raw.endswith(b"\n"):
+        raise RuntimeStateError(
+            f"Event log is not newline-terminated: {path}",
+            details={"path": str(path)},
+            error_code=E_TRANSACTION_INTEGRITY,
+        )
+
+    try:
+        decoded = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise RuntimeStateError(
+            f"Event log is not valid UTF-8: {path}",
+            details={"path": str(path), "reason": str(exc)},
+            error_code=E_TRANSACTION_INTEGRITY,
+        ) from exc
+
+    records: list[dict[str, Any]] = []
+    for lineno, line in enumerate(decoded.splitlines(), start=1):
+        if not line.strip():
+            continue
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise RuntimeStateError(
+                f"Invalid JSON event log line {lineno}: {path}",
+                details={"path": str(path), "line": lineno, "reason": str(exc)},
+                error_code=E_TRANSACTION_INTEGRITY,
+            ) from exc
+        if not isinstance(payload, dict):
+            raise RuntimeStateError(
+                f"Event log line {lineno} must contain an object: {path}",
+                details={"path": str(path), "line": lineno},
+                error_code=E_TRANSACTION_INTEGRITY,
+            )
+        schema_version = payload.get("schema_version")
+        if schema_version != EVENT_LOG_SCHEMA:
+            raise RuntimeStateError(
+                f"Unsupported event log schema on line {lineno}: {schema_version}",
+                details={"path": str(path), "line": lineno, "schema_version": schema_version},
+                error_code=E_TRANSACTION_INTEGRITY,
+            )
+        event_type = payload.get("event_type")
+        if event_type not in EVENT_TYPES:
+            raise RuntimeStateError(
+                f"Unknown event type on event log line {lineno}: {event_type}",
+                details={"path": str(path), "line": lineno, "event_type": event_type},
+                error_code=E_TRANSACTION_INTEGRITY,
+            )
+        actor = payload.get("actor")
+        if actor not in ACTORS:
+            raise RuntimeStateError(
+                f"Unknown event actor on event log line {lineno}: {actor}",
+                details={"path": str(path), "line": lineno, "actor": actor},
+                error_code=E_TRANSACTION_INTEGRITY,
+            )
+        records.append(payload)
+    return records
+
+
+def read_event_log_records_strict(path: str | Path) -> list[dict[str, Any]]:
+    """Read event log records with the runtime transaction-integrity checks."""
+
+    return _read_event_log_records(Path(path))
+
+
+def append_event(
+    *,
+    workspace: str | Path,
+    run_id: str,
+    event_type: str,
+    actor: str,
+    stage_id: str | None = None,
+    artifact_id: str | None = None,
+    decision: str | None = None,
+    reason: str = "",
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if event_type not in EVENT_TYPES:
+        raise RuntimeStateError(
+            f"Unknown event type: {event_type}",
+            details={"event_type": event_type},
+        )
+    if actor not in ACTORS:
+        raise RuntimeStateError(
+            f"Unknown event actor: {actor}",
+            details={"actor": actor},
+        )
+    safe_run_id = _validate_runtime_run_id(run_id)
+    ws = Path(workspace).expanduser().resolve()
+    event = {
+        "schema_version": EVENT_LOG_SCHEMA,
+        "event_id": uuid.uuid4().hex,
+        "run_id": safe_run_id,
+        "created_at": utc_now(),
+        "event_type": event_type,
+        "actor": actor,
+        "stage_id": stage_id,
+        "artifact_id": artifact_id,
+        "decision": decision,
+        "reason": reason,
+        "metadata": metadata or {},
+    }
+    _append_jsonl(runtime_state_paths(ws)["event_log"], event)
+    return event
+
+
+def _load_handoff_runtime_state(workspace: str | Path) -> tuple[Path, dict[str, Path], dict[str, Any]]:
+    ws = _require_workspace(workspace)
+    paths = runtime_state_paths(ws)
+    manifest = _read_json_if_exists(paths["runtime_manifest"])
+    workflow = _read_json_if_exists(paths["workflow_state"])
+    if manifest is None or workflow is None:
+        raise RuntimeStateError(
+            "Runtime state is not initialized. Run `multi-agent-brief state init --workspace <workspace>` first.",
+            details={"workspace": str(ws)},
+            error_code=E_RUNTIME_STATE_NOT_INITIALIZED,
+        )
+    if manifest.get("schema_version") != RUNTIME_MANIFEST_SCHEMA:
+        raise RuntimeStateError(
+            "runtime_manifest.json has an unsupported schema.",
+            details={"path": str(paths["runtime_manifest"]), "schema_version": manifest.get("schema_version")},
+        )
+    manifest["run_id"] = _validate_runtime_run_id(
+        manifest.get("run_id"),
+        path=paths["runtime_manifest"],
+    )
+    if workflow.get("schema_version") != WORKFLOW_STATE_SCHEMA:
+        raise RuntimeStateError(
+            "workflow_state.json has an unsupported schema.",
+            details={"path": str(paths["workflow_state"]), "schema_version": workflow.get("schema_version")},
+        )
+    _workflow_with_persistable_run_integrity(workflow, path=paths["workflow_state"])
+    if workflow.get("run_id") is not None:
+        _validate_runtime_run_id(
+            workflow.get("run_id"),
+            path=paths["workflow_state"],
+        )
+    return ws, paths, manifest
+
+
+def record_handoff_written(
+    *,
+    workspace: str | Path,
+    handoff_markdown: str | Path,
+    handoff_json: str | Path,
+    actor: str = "cli",
+) -> dict[str, Any]:
+    ws, _paths, manifest = _load_handoff_runtime_state(workspace)
+    run_id = str(manifest["run_id"])
+    return append_event(
+        workspace=ws,
+        run_id=run_id,
+        event_type="handoff_written",
+        actor=actor,
+        reason="Runtime handoff artifacts written.",
+        metadata={
+            "handoff_markdown": _workspace_relative(ws, Path(handoff_markdown)),
+            "handoff_json": _workspace_relative(ws, Path(handoff_json)),
+        },
+    )