cognition-system-behavior-contracts 0.7.0__tar.gz

cognition_system_behavior_contracts-0.7.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: cognition-system-behavior-contracts
+Version: 0.7.0
+Summary: Behavior contracts for Cognition System.
+Requires-Python: >=3.14
+Requires-Dist: cognition-system-schemas==0.7.0
+Description-Content-Type: text/markdown
+
+Cognition System v0.7.0 public package. See the version-specific public README in the release repository for usage and boundary notes.

cognition_system_behavior_contracts-0.7.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "cognition-system-behavior-contracts"
+version = "0.7.0"
+readme = { text = "Cognition System v0.7.0 public package. See the version-specific public README in the release repository for usage and boundary notes.", content-type = "text/markdown" }
+description = "Behavior contracts for Cognition System."
+requires-python = ">=3.14"
+dependencies = [
+  "cognition-system-schemas==0.7.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/behavior_contracts"]
+
+[tool.uv.sources]
+cognition-system-schemas = { workspace = true }

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/__init__.py

@@ -0,0 +1,67 @@
+"""Behavior contracts for Cognition Engine."""
+
+from behavior_contracts.adk_tool import (
+    assert_controlled_live_tool_requires_explicit_confirmation,
+    assert_low_risk_tool_requires_no_external_side_effects,
+    assert_no_raw_adk_or_tool_payload,
+    assert_tool_audit_is_sanitized,
+    assert_tool_consumer_is_candidate_only,
+)
+from behavior_contracts.governance_candidate import (
+    CandidateGuardResult,
+    CandidateOnlyGuard,
+    NoAdkNativeObjectLeakageGuard,
+    NoExecutionGuard,
+    NoReleaseActionGuard,
+    NoRuntimeActionGuard,
+    OperatorConfirmationRequiredGuard,
+    ReviewerExecutorSeparationGuard,
+    SensitiveOutputRedactionGuard,
+    validate_governance_candidate_guards,
+)
+from behavior_contracts.llm_invocation import GovernedLlmInvocationService
+from behavior_contracts.product_gateway_response_summary import (
+    DEFAULT_PRODUCT_GATEWAY_RESPONSE_SUMMARY_GUARDS,
+    ProductGatewayResponseBlockedRequiresReasonGuard,
+    ProductGatewayResponseNoExecutionGuard,
+    ProductGatewayResponseNoRawPayloadGuard,
+    ProductGatewayResponseNoRuntimeObjectLeakageGuard,
+    ProductGatewayResponseRefsOnlyGuard,
+    ProductGatewayResponseSummaryHeaderGuard,
+    ProductGatewayResponseSummaryOnlyGuard,
+    validate_product_gateway_response_summary_guards,
+)
+from behavior_contracts.runtime import (
+    AdkServiceFactsProvider,
+    RecordedRunEvidenceProvider,
+)
+
+__all__ = [
+    "assert_controlled_live_tool_requires_explicit_confirmation",
+    "assert_low_risk_tool_requires_no_external_side_effects",
+    "assert_no_raw_adk_or_tool_payload",
+    "assert_tool_audit_is_sanitized",
+    "assert_tool_consumer_is_candidate_only",
+    "CandidateGuardResult",
+    "CandidateOnlyGuard",
+    "DEFAULT_PRODUCT_GATEWAY_RESPONSE_SUMMARY_GUARDS",
+    "GovernedLlmInvocationService",
+    "NoAdkNativeObjectLeakageGuard",
+    "NoExecutionGuard",
+    "NoReleaseActionGuard",
+    "NoRuntimeActionGuard",
+    "OperatorConfirmationRequiredGuard",
+    "ProductGatewayResponseBlockedRequiresReasonGuard",
+    "ProductGatewayResponseNoExecutionGuard",
+    "ProductGatewayResponseNoRawPayloadGuard",
+    "ProductGatewayResponseNoRuntimeObjectLeakageGuard",
+    "ProductGatewayResponseRefsOnlyGuard",
+    "ProductGatewayResponseSummaryHeaderGuard",
+    "ProductGatewayResponseSummaryOnlyGuard",
+    "ReviewerExecutorSeparationGuard",
+    "AdkServiceFactsProvider",
+    "RecordedRunEvidenceProvider",
+    "SensitiveOutputRedactionGuard",
+    "validate_product_gateway_response_summary_guards",
+    "validate_governance_candidate_guards",
+]

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/adk_tool.py

@@ -0,0 +1,127 @@
+"""Behavior contracts for ADK native FunctionTool product boundaries."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from behavior_contracts.governance_candidate import CandidateGuardResult
+from schemas.adk_tool import (
+    AdkFunctionToolAuditContract,
+    AdkFunctionToolAuditStatus,
+    AdkFunctionToolRiskProfile,
+    ToolRiskLevel,
+)
+
+
+def assert_tool_audit_is_sanitized(
+    audit: AdkFunctionToolAuditContract | Mapping[str, Any],
+) -> CandidateGuardResult:
+    """Validate that public Tool audit facts do not expose raw runtime payloads."""
+
+    try:
+        AdkFunctionToolAuditContract.model_validate(audit)
+    except ValueError as exc:
+        return CandidateGuardResult(False, (str(exc),))
+    return CandidateGuardResult(True)
+
+
+def assert_low_risk_tool_requires_no_external_side_effects(
+    risk_profile: AdkFunctionToolRiskProfile | Mapping[str, Any],
+) -> CandidateGuardResult:
+    """Validate the low-risk Tool profile boundary."""
+
+    try:
+        profile = AdkFunctionToolRiskProfile.model_validate(risk_profile)
+    except ValueError as exc:
+        return CandidateGuardResult(False, (str(exc),))
+    if profile.risk_level is not ToolRiskLevel.LOW:
+        return CandidateGuardResult(False, ("risk_level must be low.",))
+    return CandidateGuardResult(True)
+
+
+def assert_controlled_live_tool_requires_explicit_confirmation(
+    audit: AdkFunctionToolAuditContract | Mapping[str, Any],
+) -> CandidateGuardResult:
+    """Require explicit confirmation before controlled-live Tool execution."""
+
+    try:
+        contract = AdkFunctionToolAuditContract.model_validate(audit)
+    except ValueError as exc:
+        return CandidateGuardResult(False, (str(exc),))
+    violations: list[str] = []
+    if contract.tool_runtime_call_performed:
+        if not contract.tool_confirmation_required:
+            violations.append("tool_confirmation_required must be true.")
+        if not contract.tool_confirmation_granted:
+            violations.append("tool_confirmation_granted must be true.")
+        if not contract.tool_confirmation_decision_source:
+            violations.append("tool_confirmation_decision_source is required.")
+    return CandidateGuardResult(not violations, tuple(violations))
+
+
+def assert_tool_consumer_is_candidate_only(
+    consumer_facts: Mapping[str, Any],
+) -> CandidateGuardResult:
+    """Require Tool consumers to remain read-only candidate consumers."""
+
+    violations: list[str] = []
+    if consumer_facts.get("candidate_only") is not True:
+        violations.append("candidate_only must be true.")
+    for field_name in (
+        "tool_execution_enabled",
+        "tool_control_plane_enabled",
+        "runtime_execution_enabled",
+        "formal_governance_decision_enabled",
+    ):
+        if consumer_facts.get(field_name) is True:
+            violations.append(f"{field_name} must not be true.")
+    return CandidateGuardResult(not violations, tuple(violations))
+
+
+def assert_no_raw_adk_or_tool_payload(
+    value: Mapping[str, Any],
+) -> CandidateGuardResult:
+    """Reject raw ADK, ToolContext, ToolConfirmation, input, and output payloads."""
+
+    violations = [
+        f"raw ADK or tool payload is forbidden at {path}."
+        for path, item in _walk(value)
+        if _is_raw_tool_payload(path, item)
+    ]
+    return CandidateGuardResult(not violations, tuple(violations))
+
+
+def _walk(value: Any, path: str = "$") -> list[tuple[str, Any]]:
+    items = [(path, value)]
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            items.extend(_walk(item, f"{path}.{key}"))
+    elif isinstance(value, (list, tuple)):
+        for index, item in enumerate(value):
+            items.extend(_walk(item, f"{path}[{index}]"))
+    return items
+
+
+def _is_raw_tool_payload(path: str, value: Any) -> bool:
+    key = path.rsplit(".", maxsplit=1)[-1].lower()
+    if key in {
+        "adk_object",
+        "function_tool",
+        "raw",
+        "raw_adk_object",
+        "raw_input",
+        "raw_output",
+        "raw_tool_input",
+        "raw_tool_output",
+        "tool_confirmation",
+        "tool_context",
+        "tool_input",
+        "tool_output",
+    }:
+        return True
+    if isinstance(value, Mapping):
+        module_name = value.get("object_module")
+        return isinstance(module_name, str) and module_name.startswith("google.adk")
+    if value is None or isinstance(value, (str, int, float, bool, list, tuple, dict)):
+        return False
+    return type(value).__module__.startswith("google.adk")

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/governance_candidate.py

@@ -0,0 +1,467 @@
+"""Governance candidate behavior guards.
+
+These guards describe safety invariants for governance candidates. They do not
+execute release, runtime, policy, or governance actions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+
+FORBIDDEN_RELEASE_ACTIONS = frozenset(
+    {
+        "release",
+        "block",
+        "pass",
+        "publish",
+        "upload",
+        "twine_upload",
+        "git_tag",
+        "git_push",
+        "github_release",
+        "trusted_publishing",
+    }
+)
+
+FORBIDDEN_RUNTIME_ACTIONS = frozenset(
+    {
+        "runtime_fix",
+        "run_config_update",
+        "service_bundle_update",
+        "execute_workflow",
+        "call_runtime_container",
+        "call_composition",
+        "call_adk_adapter",
+    }
+)
+
+FORBIDDEN_RUNTIME_OBJECT_MODULE_PREFIXES = (
+    "google.adk",
+    "adk_adapter",
+    "composition",
+    "runtime_container",
+)
+
+SENSITIVE_OUTPUT_KEYS = frozenset(
+    {
+        "command_output",
+        "command_outputs",
+        "credential",
+        "credentials",
+        "env",
+        "raw",
+        "raw_output",
+        "secret",
+        "stderr",
+        "stdout",
+        "token",
+    }
+)
+
+SENSITIVE_KEY_EXCEPTIONS = frozenset(
+    {
+        "raw_output_digest",
+        "sensitive_fields_omitted",
+        "token_presence_check_mode",
+    }
+)
+
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_POLICY_DOMAIN = "product_agent_output_governance"
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_CASE_TYPE = "product_agent_output_governance_review"
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_DECISION_CANDIDATE_SCOPE = (
+    "product_agent_output_governance_decision_candidate"
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_ALLOWED_DOMAIN_METADATA_KEYS = frozenset(
+    {
+        "product_gateway_request_id",
+        "product_gateway_entry_kind",
+        "product_gateway_status",
+        "product_gateway_exit_code",
+        "agent_advice_candidate_id",
+        "agent_advice_status",
+        "agent_advice_recommendation",
+        "ready_for_review",
+        "evidence_statuses",
+        "missing_evidence",
+        "warning_candidates",
+        "block_candidates",
+        "human_review_reasons",
+        "summary_only",
+        "refs_only",
+        "candidate_only",
+    }
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_BOUNDARY_FLAGS = frozenset(
+    {
+        "summary_only",
+        "refs_only",
+        "candidate_only",
+    }
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_KEYS = frozenset(
+    {
+        "agent_task_advice_consumption_payload",
+        "api_key",
+        "artifact_content",
+        "completion",
+        "credential",
+        "credentials",
+        "full_response",
+        "message",
+        "messages",
+        "payload",
+        "product_gateway_request",
+        "product_gateway_response",
+        "prompt",
+        "provider_payload",
+        "provider_response",
+        "raw",
+        "raw_adk_object",
+        "raw_api_payload",
+        "raw_input",
+        "raw_output",
+        "raw_payload",
+        "raw_prompt",
+        "raw_provider_payload",
+        "raw_provider_response",
+        "raw_response",
+        "raw_tool_input",
+        "raw_tool_output",
+        "raw_user_message",
+        "response",
+        "response_text",
+        "secret",
+        "system_prompt",
+        "text",
+        "token",
+        "tool_context",
+        "tool_input",
+        "tool_output",
+        "user_message",
+    }
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_ACTION_FIELDS = frozenset(
+    {
+        "action_kind",
+        "can_publish",
+        "can_release",
+        "execution_result",
+        "release_action_kind",
+        "release_action_result",
+        "runtime_action_kind",
+        "tag_release_and_publish",
+    }
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_FALSE_INVARIANT_FIELDS = (
+    "execution_enabled",
+    "formal_decision_enabled",
+    "formal_outcome_enabled",
+    "governance_outcome_enabled",
+    "policy_execution_enabled",
+    "release_action_enabled",
+    "runtime_execution_enabled",
+)
+PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_RELEASE_REASON = (
+    "Release action boundary review is pending."
+)
+
+
+@dataclass(frozen=True)
+class CandidateGuardResult:
+    """Result returned by a governance candidate guard."""
+
+    passed: bool
+    violations: tuple[str, ...] = field(default_factory=tuple)
+
+
+class CandidateGuard:
+    """Base class for non-executing governance candidate guards."""
+
+    guard_name = "candidate_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        """Validate a candidate mapping without executing any action."""
+
+        raise NotImplementedError
+
+    def _result(self, violations: list[str]) -> CandidateGuardResult:
+        return CandidateGuardResult(
+            passed=not violations,
+            violations=tuple(violations),
+        )
+
+
+class CandidateOnlyGuard(CandidateGuard):
+    """Require explicit candidate-only semantics."""
+
+    guard_name = "candidate_only_guard"
+
+    _semantic_fields = (
+        "action_semantics",
+        "decision_semantics",
+        "outcome_semantics",
+        "review_semantics",
+        "policy_status",
+    )
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        values = [candidate.get(field_name) for field_name in self._semantic_fields]
+        has_candidate_scope = bool(candidate.get("candidate_scope"))
+        is_explicit_candidate = candidate.get("candidate_only") is True
+        if "candidate_only" in values or has_candidate_scope or is_explicit_candidate:
+            return self._result([])
+        return self._result(["Candidate must declare candidate_only semantics."])
+
+
+class NoExecutionGuard(CandidateGuard):
+    """Ensure candidate objects cannot enable execution."""
+
+    guard_name = "no_execution_guard"
+
+    _false_invariant_fields = (
+        "execution_enabled",
+        "formal_decision_enabled",
+        "formal_outcome_enabled",
+        "governance_outcome_enabled",
+        "policy_execution_enabled",
+        "release_action_enabled",
+        "runtime_execution_enabled",
+    )
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"{field_name} must not be true."
+            for field_name in self._false_invariant_fields
+            if candidate.get(field_name) is True
+        ]
+        return self._result(violations)
+
+
+class OperatorConfirmationRequiredGuard(CandidateGuard):
+    """Require operator confirmation before any external action boundary."""
+
+    guard_name = "operator_confirmation_required_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        if candidate.get("requires_operator_confirmation") is True:
+            return self._result([])
+        return self._result(["requires_operator_confirmation must be true."])
+
+
+class ReviewerExecutorSeparationGuard(CandidateGuard):
+    """Require reviewer and executor identities to remain separate."""
+
+    guard_name = "reviewer_executor_separation_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        reviewer = candidate.get("reviewer")
+        executor = candidate.get("executor")
+        if reviewer and executor and reviewer == executor:
+            return self._result(["reviewer and executor must be separate."])
+        return self._result([])
+
+
+class NoReleaseActionGuard(CandidateGuard):
+    """Reject formal release, block, pass, and publishing action names."""
+
+    guard_name = "no_release_action_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        values = _candidate_action_values(candidate)
+        forbidden = sorted(value for value in values if value in FORBIDDEN_RELEASE_ACTIONS)
+        return self._result(
+            [f"Release action is forbidden: {value}." for value in forbidden]
+        )
+
+
+class NoRuntimeActionGuard(CandidateGuard):
+    """Reject formal runtime fix and runtime update action names."""
+
+    guard_name = "no_runtime_action_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        values = _candidate_action_values(candidate)
+        forbidden = sorted(value for value in values if value in FORBIDDEN_RUNTIME_ACTIONS)
+        return self._result(
+            [f"Runtime action is forbidden: {value}." for value in forbidden]
+        )
+
+
+class NoAdkNativeObjectLeakageGuard(CandidateGuard):
+    """Reject ADK and execution-layer object leakage."""
+
+    guard_name = "no_adk_native_object_leakage_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"Runtime object leakage is forbidden at {path}."
+            for path, value in _walk(candidate)
+            if _is_runtime_object(value)
+        ]
+        return self._result(violations)
+
+
+class SensitiveOutputRedactionGuard(CandidateGuard):
+    """Reject raw or sensitive output fields in public candidate boundaries."""
+
+    guard_name = "sensitive_output_redaction_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"Sensitive output key is forbidden at {path}."
+            for path, _value in _walk(candidate)
+            if _is_sensitive_path(path)
+        ]
+        return self._result(violations)
+
+
+class ProductAgentOutputGovernanceDomainGuard(CandidateGuard):
+    """Enforce product-agent output governance candidate boundaries."""
+
+    guard_name = "product_agent_output_governance_domain_guard"
+
+    def validate(self, candidate: Mapping[str, Any]) -> CandidateGuardResult:
+        if not _is_product_agent_output_governance_candidate(candidate):
+            return self._result([])
+
+        violations: list[str] = []
+        domain_metadata = candidate.get("domain_metadata", {})
+        if "domain_metadata" in candidate and not isinstance(domain_metadata, Mapping):
+            violations.append("domain_metadata must be a mapping.")
+        elif isinstance(domain_metadata, Mapping):
+            unexpected_keys = sorted(
+                str(key)
+                for key in domain_metadata
+                if str(key)
+                not in PRODUCT_AGENT_OUTPUT_GOVERNANCE_ALLOWED_DOMAIN_METADATA_KEYS
+            )
+            violations.extend(
+                f"Product-agent domain_metadata key is not allowed: {key}."
+                for key in unexpected_keys
+            )
+            for flag in PRODUCT_AGENT_OUTPUT_GOVERNANCE_BOUNDARY_FLAGS:
+                if flag in domain_metadata and domain_metadata.get(flag) is not True:
+                    violations.append(f"{flag} must be true for product-agent candidates.")
+
+        violations.extend(
+            f"{field_name} must not be true for product-agent candidates."
+            for field_name in PRODUCT_AGENT_OUTPUT_GOVERNANCE_FALSE_INVARIANT_FIELDS
+            if candidate.get(field_name) is True
+        )
+
+        for path, value in _walk(candidate):
+            key = _path_key(path)
+            if key in PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_KEYS:
+                violations.append(
+                    f"Product-agent raw or sensitive key is forbidden at {path}."
+                )
+            if key in PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_ACTION_FIELDS:
+                violations.append(
+                    f"Product-agent action field is forbidden at {path}."
+                )
+            if (
+                isinstance(value, str)
+                and PRODUCT_AGENT_OUTPUT_GOVERNANCE_FORBIDDEN_RELEASE_REASON in value
+            ):
+                violations.append(
+                    "Product-agent candidate must not use release action boundary "
+                    f"reason at {path}."
+                )
+
+        return self._result(violations)
+
+
+DEFAULT_GOVERNANCE_CANDIDATE_GUARDS = (
+    CandidateOnlyGuard(),
+    NoExecutionGuard(),
+    OperatorConfirmationRequiredGuard(),
+    ReviewerExecutorSeparationGuard(),
+    NoReleaseActionGuard(),
+    NoRuntimeActionGuard(),
+    ProductAgentOutputGovernanceDomainGuard(),
+    NoAdkNativeObjectLeakageGuard(),
+    SensitiveOutputRedactionGuard(),
+)
+
+
+def validate_governance_candidate_guards(
+    candidate: Mapping[str, Any],
+    guards: tuple[CandidateGuard, ...] = DEFAULT_GOVERNANCE_CANDIDATE_GUARDS,
+) -> CandidateGuardResult:
+    """Run candidate guards and return a combined non-executing result."""
+
+    violations: list[str] = []
+    for guard in guards:
+        result = guard.validate(candidate)
+        violations.extend(f"{guard.guard_name}: {item}" for item in result.violations)
+    return CandidateGuardResult(
+        passed=not violations,
+        violations=tuple(violations),
+    )
+
+
+def _candidate_action_values(candidate: Mapping[str, Any]) -> set[str]:
+    values: set[str] = set()
+    for key in ("action_kind", "decision", "runtime_action_kind", "release_action_kind"):
+        value = candidate.get(key)
+        if isinstance(value, str):
+            values.add(value.lower())
+    for key in ("allowed_action_kinds", "forbidden_action_kinds"):
+        value = candidate.get(key)
+        if isinstance(value, (list, tuple, set)):
+            values.update(item.lower() for item in value if isinstance(item, str))
+    return values
+
+
+def _walk(value: Any, path: str = "$") -> list[tuple[str, Any]]:
+    items = [(path, value)]
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            items.extend(_walk(item, f"{path}.{key}"))
+    elif isinstance(value, (list, tuple)):
+        for index, item in enumerate(value):
+            items.extend(_walk(item, f"{path}[{index}]"))
+    return items
+
+
+def _is_runtime_object(value: Any) -> bool:
+    if isinstance(value, Mapping):
+        module_name = value.get("object_module")
+        return isinstance(module_name, str) and module_name.startswith(
+            FORBIDDEN_RUNTIME_OBJECT_MODULE_PREFIXES
+        )
+    if value is None or isinstance(value, (str, int, float, bool, list, tuple, dict)):
+        return False
+    return type(value).__module__.startswith(FORBIDDEN_RUNTIME_OBJECT_MODULE_PREFIXES)
+
+
+def _is_sensitive_path(path: str) -> bool:
+    key = path.rsplit(".", maxsplit=1)[-1].lower()
+    if key in SENSITIVE_KEY_EXCEPTIONS:
+        return False
+    return (
+        key in SENSITIVE_OUTPUT_KEYS
+        or key.endswith("_token")
+        or key.endswith("_credential")
+        or key.endswith("_secret")
+    )
+
+
+def _is_product_agent_output_governance_candidate(
+    candidate: Mapping[str, Any],
+) -> bool:
+    return (
+        candidate.get("policy_domain") == PRODUCT_AGENT_OUTPUT_GOVERNANCE_POLICY_DOMAIN
+        or candidate.get("case_type") == PRODUCT_AGENT_OUTPUT_GOVERNANCE_CASE_TYPE
+        or candidate.get("candidate_scope")
+        == PRODUCT_AGENT_OUTPUT_GOVERNANCE_DECISION_CANDIDATE_SCOPE
+    )
+
+
+def _path_key(path: str) -> str:
+    key = path.rsplit(".", maxsplit=1)[-1]
+    if "[" in key:
+        key = key.split("[", maxsplit=1)[0]
+    return key.lower()

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/llm_invocation.py

@@ -0,0 +1,18 @@
+"""Behavior contract for governed LLM invocation."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from schemas.llm_invocation import LlmInvocationRequest, LlmInvocationResult
+
+
+class GovernedLlmInvocationService(Protocol):
+    """Protocol for a governed LLM invocation capability.
+
+    Implementations may use ADK LiteLlm, LiteLLM provider routes, or an ADK
+    WorkflowRunner chain. The protocol itself does not perform model calls.
+    """
+
+    def invoke(self, request: LlmInvocationRequest) -> LlmInvocationResult:
+        """Run a governed invocation and return sanitized result facts."""

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/product_gateway_response_summary.py

@@ -0,0 +1,326 @@
+"""Behavior guards for product gateway response summaries."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from behavior_contracts.governance_candidate import CandidateGuardResult
+from schemas.product_gateway_response_summary import (
+    PRODUCT_GATEWAY_RESPONSE_SUMMARY_ENTRY_KINDS,
+    PRODUCT_GATEWAY_RESPONSE_SUMMARY_PAYLOAD_TYPE,
+    PRODUCT_GATEWAY_RESPONSE_SUMMARY_PRODUCT,
+    PRODUCT_GATEWAY_RESPONSE_SUMMARY_STATUSES,
+    PRODUCT_GATEWAY_RESPONSE_SUMMARY_VERSION,
+)
+
+
+SUMMARY_ONLY_FORBIDDEN_KEYS = frozenset(
+    {
+        "artifact_content",
+        "completion",
+        "content",
+        "full_response",
+        "message",
+        "messages",
+        "prompt",
+        "response",
+        "response_text",
+        "system_prompt",
+        "text",
+        "user_message",
+    }
+)
+
+RAW_PAYLOAD_KEYS = frozenset(
+    {
+        "api_key",
+        "credential",
+        "credentials",
+        "payload",
+        "provider_payload",
+        "provider_response",
+        "raw",
+        "raw_adk_object",
+        "raw_api_payload",
+        "raw_input",
+        "raw_output",
+        "raw_payload",
+        "raw_prompt",
+        "raw_provider_payload",
+        "raw_provider_response",
+        "raw_response",
+        "raw_tool_input",
+        "raw_tool_output",
+        "raw_user_message",
+        "secret",
+        "token",
+        "tool_context",
+        "tool_input",
+        "tool_output",
+    }
+)
+
+SENSITIVE_KEY_EXCEPTIONS = frozenset({"raw_output_digest"})
+
+REF_FIELDS = frozenset(
+    {
+        "evidence_refs",
+        "audit_refs",
+        "agent_advice_refs",
+        "tool_audit_refs",
+    }
+)
+REF_ITEM_KEYS = frozenset({"ref", "kind", "purpose", "metadata"})
+
+NO_EXECUTION_FIELDS = frozenset(
+    {
+        "execution_enabled",
+        "runtime_permission_granted",
+        "agent_runtime_enabled",
+        "llm_call_enabled",
+        "action_execution_enabled",
+        "chat_enabled",
+        "gateway_enabled",
+        "tool_execution_enabled",
+    }
+)
+
+FORBIDDEN_OBJECT_MODULE_PREFIXES = (
+    "google.adk",
+    "adk_adapter",
+    "runtime_container",
+    "composition",
+    "litellm",
+)
+
+
+class ProductGatewayResponseSummaryHeaderGuard:
+    """Validate the frozen product gateway response summary header."""
+
+    guard_name = "product_gateway_response_summary_header_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations: list[str] = []
+        expected = {
+            "product": PRODUCT_GATEWAY_RESPONSE_SUMMARY_PRODUCT,
+            "payload_type": PRODUCT_GATEWAY_RESPONSE_SUMMARY_PAYLOAD_TYPE,
+            "payload_version": PRODUCT_GATEWAY_RESPONSE_SUMMARY_VERSION,
+        }
+        for key, expected_value in expected.items():
+            if summary.get(key) != expected_value:
+                violations.append(f"{key} must be {expected_value}.")
+        for key in ("request_id", "entry_kind", "status"):
+            if not isinstance(summary.get(key), str) or not summary.get(key):
+                violations.append(f"{key} is required.")
+        entry_kind = summary.get("entry_kind")
+        if isinstance(entry_kind, str) and (
+            entry_kind not in PRODUCT_GATEWAY_RESPONSE_SUMMARY_ENTRY_KINDS
+        ):
+            violations.append(f"unsupported product_gateway entry_kind: {entry_kind}.")
+        status = summary.get("status")
+        if isinstance(status, str) and status not in PRODUCT_GATEWAY_RESPONSE_SUMMARY_STATUSES:
+            violations.append(f"unsupported product_gateway status: {status}.")
+        return _result(violations)
+
+
+class ProductGatewayResponseSummaryOnlyGuard:
+    """Reject payloads that carry response bodies instead of summaries."""
+
+    guard_name = "product_gateway_response_summary_only_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"summary-only field is forbidden at {path}."
+            for path, _value in _walk(summary)
+            if _key_at_path(path) in SUMMARY_ONLY_FORBIDDEN_KEYS
+        ]
+        return _result(violations)
+
+
+class ProductGatewayResponseRefsOnlyGuard:
+    """Validate that refs are sanitized ref items only."""
+
+    guard_name = "product_gateway_response_refs_only_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations: list[str] = []
+        for field_name in REF_FIELDS:
+            values = summary.get(field_name, [])
+            if not isinstance(values, (list, tuple)):
+                violations.append(f"{field_name} must be a list.")
+                continue
+            for index, value in enumerate(values):
+                item_path = f"$.{field_name}[{index}]"
+                if not isinstance(value, Mapping):
+                    violations.append(f"{item_path} must be a mapping.")
+                    continue
+                extra_keys = sorted(str(key) for key in set(value.keys()) - REF_ITEM_KEYS)
+                for key in extra_keys:
+                    violations.append(f"{item_path}.{key} is not allowed in refs.")
+                if not isinstance(value.get("ref"), str) or not value.get("ref"):
+                    violations.append(f"{item_path}.ref is required.")
+                if not isinstance(value.get("kind"), str) or not value.get("kind"):
+                    violations.append(f"{item_path}.kind is required.")
+                metadata = value.get("metadata", {})
+                if metadata is not None and not isinstance(metadata, Mapping):
+                    violations.append(f"{item_path}.metadata must be a mapping.")
+        return _result(violations)
+
+
+class ProductGatewayResponseNoRawPayloadGuard:
+    """Reject raw or sensitive payload fields."""
+
+    guard_name = "product_gateway_response_no_raw_payload_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"raw or sensitive payload is forbidden at {path}."
+            for path, value in _walk(summary)
+            if _is_raw_payload(path, value)
+        ]
+        return _result(violations)
+
+
+class ProductGatewayResponseNoExecutionGuard:
+    """Reject execution-enabling flags."""
+
+    guard_name = "product_gateway_response_no_execution_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"{path} must not be true."
+            for path, value in _walk(summary)
+            if _key_at_path(path) in NO_EXECUTION_FIELDS and value is True
+        ]
+        return _result(violations)
+
+
+class ProductGatewayResponseNoRuntimeObjectLeakageGuard:
+    """Reject runtime, ADK, composition, and provider object markers."""
+
+    guard_name = "product_gateway_response_no_runtime_object_leakage_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        violations = [
+            f"runtime object leakage is forbidden at {path}."
+            for path, value in _walk(summary)
+            if _is_runtime_object(value)
+        ]
+        return _result(violations)
+
+
+class ProductGatewayResponseBlockedRequiresReasonGuard:
+    """Require blocked summaries to carry explicit blocking reasons."""
+
+    guard_name = "product_gateway_response_blocked_requires_reason_guard"
+
+    def validate(self, summary: Mapping[str, Any]) -> CandidateGuardResult:
+        if summary.get("status") != "blocked":
+            return _result([])
+        reasons = summary.get("blocking_reasons")
+        if isinstance(reasons, (list, tuple)) and any(
+            isinstance(reason, str) and reason for reason in reasons
+        ):
+            return _result([])
+        return _result(["blocked product gateway summaries require blocking_reasons."])
+
+
+DEFAULT_PRODUCT_GATEWAY_RESPONSE_SUMMARY_GUARDS = (
+    ProductGatewayResponseSummaryHeaderGuard(),
+    ProductGatewayResponseSummaryOnlyGuard(),
+    ProductGatewayResponseRefsOnlyGuard(),
+    ProductGatewayResponseNoRawPayloadGuard(),
+    ProductGatewayResponseNoExecutionGuard(),
+    ProductGatewayResponseNoRuntimeObjectLeakageGuard(),
+    ProductGatewayResponseBlockedRequiresReasonGuard(),
+)
+
+
+def validate_product_gateway_response_summary_guards(
+    summary: Mapping[str, Any],
+    guards: tuple[
+        ProductGatewayResponseSummaryHeaderGuard
+        | ProductGatewayResponseSummaryOnlyGuard
+        | ProductGatewayResponseRefsOnlyGuard
+        | ProductGatewayResponseNoRawPayloadGuard
+        | ProductGatewayResponseNoExecutionGuard
+        | ProductGatewayResponseNoRuntimeObjectLeakageGuard
+        | ProductGatewayResponseBlockedRequiresReasonGuard,
+        ...,
+    ] = DEFAULT_PRODUCT_GATEWAY_RESPONSE_SUMMARY_GUARDS,
+) -> CandidateGuardResult:
+    """Run product gateway response summary guards without executing anything."""
+
+    violations: list[str] = []
+    for guard in guards:
+        result = guard.validate(summary)
+        violations.extend(f"{guard.guard_name}: {item}" for item in result.violations)
+    return _result(violations)
+
+
+def _result(violations: list[str]) -> CandidateGuardResult:
+    return CandidateGuardResult(
+        passed=not violations,
+        violations=tuple(violations),
+    )
+
+
+def _walk(value: Any, path: str = "$") -> list[tuple[str, Any]]:
+    items = [(path, value)]
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            items.extend(_walk(item, f"{path}.{key}"))
+    elif isinstance(value, (list, tuple)):
+        for index, item in enumerate(value):
+            items.extend(_walk(item, f"{path}[{index}]"))
+    return items
+
+
+def _key_at_path(path: str) -> str:
+    return path.rsplit(".", maxsplit=1)[-1].split("[", maxsplit=1)[0].lower()
+
+
+def _is_raw_payload(path: str, value: Any) -> bool:
+    key = _key_at_path(path)
+    if key in SENSITIVE_KEY_EXCEPTIONS:
+        return False
+    if key in RAW_PAYLOAD_KEYS or key.endswith("_token") or key.endswith("_secret"):
+        return True
+    if isinstance(value, str):
+        lowered = value.lower()
+        return any(
+            marker in lowered
+            for marker in (
+                "raw provider response",
+                "raw_response",
+                "response_text",
+                "system_prompt",
+                "raw_tool_input",
+                "raw_tool_output",
+            )
+        )
+    return False
+
+
+def _is_runtime_object(value: Any) -> bool:
+    if isinstance(value, Mapping):
+        module_name = value.get("object_module")
+        return isinstance(module_name, str) and module_name.startswith(
+            FORBIDDEN_OBJECT_MODULE_PREFIXES
+        )
+    if value is None or isinstance(value, (str, int, float, bool, list, tuple, dict)):
+        return False
+    return type(value).__module__.startswith(FORBIDDEN_OBJECT_MODULE_PREFIXES)
+
+
+__all__ = [
+    "DEFAULT_PRODUCT_GATEWAY_RESPONSE_SUMMARY_GUARDS",
+    "ProductGatewayResponseBlockedRequiresReasonGuard",
+    "ProductGatewayResponseNoExecutionGuard",
+    "ProductGatewayResponseNoRawPayloadGuard",
+    "ProductGatewayResponseNoRuntimeObjectLeakageGuard",
+    "ProductGatewayResponseRefsOnlyGuard",
+    "ProductGatewayResponseSummaryHeaderGuard",
+    "ProductGatewayResponseSummaryOnlyGuard",
+    "validate_product_gateway_response_summary_guards",
+]

cognition_system_behavior_contracts-0.7.0/src/behavior_contracts/runtime.py

@@ -0,0 +1,106 @@
+"""Runtime-facing behavior contracts for Cognition Engine."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from schemas.runtime import (
+    AdkServiceFactsSummaryInput,
+    ArtifactDelta,
+    NodeExecutionInput,
+    NodeExecutionResult,
+    RecordedRunEvidenceInput,
+    ResumePoint,
+    RuntimeEvent,
+    RuntimeInput,
+    RuntimeResult,
+    StateDelta,
+    WorkflowInput,
+    WorkflowResult,
+)
+
+
+class RuntimeRunner(Protocol):
+    """Contract for executing one runtime task."""
+
+    def run(self, runtime_input: RuntimeInput) -> RuntimeResult:
+        """Execute a runtime task."""
+
+
+class WorkflowRunner(Protocol):
+    """Contract for executing a workflow."""
+
+    def run_workflow(self, workflow_input: WorkflowInput) -> WorkflowResult:
+        """Execute a workflow."""
+
+
+class NodeRunner(Protocol):
+    """Contract for executing one node."""
+
+    def run_node(self, node_input: NodeExecutionInput) -> NodeExecutionResult:
+        """Execute a node."""
+
+
+class NodeScheduler(Protocol):
+    """Contract for scheduling node execution."""
+
+    def schedule_nodes(
+        self,
+        workflow_input: WorkflowInput,
+    ) -> list[NodeExecutionInput]:
+        """Schedule nodes for a workflow input."""
+
+
+class ResumeController(Protocol):
+    """Contract for resuming runtime execution."""
+
+    def resume(self, resume_point: ResumePoint) -> RuntimeResult:
+        """Resume execution from a resume point."""
+
+
+class RuntimeEventPublisher(Protocol):
+    """Contract for publishing runtime events."""
+
+    def publish_event(self, event: RuntimeEvent) -> None:
+        """Publish a runtime event."""
+
+
+class RuntimeArtifactPublisher(Protocol):
+    """Contract for publishing runtime artifact deltas."""
+
+    def publish_artifact_delta(self, artifact_delta: ArtifactDelta) -> None:
+        """Publish an artifact delta."""
+
+
+class RuntimeStatePublisher(Protocol):
+    """Contract for publishing runtime state deltas."""
+
+    def publish_state_delta(self, state_delta: StateDelta) -> None:
+        """Publish a state delta."""
+
+
+class InvocationTracker(Protocol):
+    """Contract for tracking invocation identity."""
+
+    def next_invocation_id(self) -> str:
+        """Return the next invocation id."""
+
+
+class RecordedRunEvidenceProvider(Protocol):
+    """Contract for converting recorded runtime facts into recorded-run evidence."""
+
+    def build_recorded_run_evidence(
+        self,
+        runtime_result: RuntimeResult,
+    ) -> RecordedRunEvidenceInput:
+        """Build recorded-run evidence facts from a runtime result."""
+
+
+class AdkServiceFactsProvider(Protocol):
+    """Contract for converting recorded runtime facts into ADK service facts."""
+
+    def build_adk_service_facts(
+        self,
+        runtime_result: RuntimeResult,
+    ) -> AdkServiceFactsSummaryInput:
+        """Build ADK service facts from a runtime result."""