ciris-agent 1.7.7__py3-none-any.whl

ciris_engine/schemas/audit/verification.py

@@ -0,0 +1,131 @@
+"""
+Schemas for audit verification operations.
+
+These replace all Dict[str, Any] usage in verifier.py.
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from ciris_engine.schemas.audit.hash_chain import HashChainAuditEntry
+
+
+class ChainVerificationResult(BaseModel):
+    """Result of hash chain verification."""
+
+    valid: bool = Field(..., description="Whether chain is valid")
+    entries_checked: int = Field(0, description="Number of entries checked")
+    errors: List[str] = Field(default_factory=list, description="List of validation errors")
+    last_valid_entry: Optional[int] = Field(None, description="Last valid entry ID before error")
+
+
+class SignatureVerificationResult(BaseModel):
+    """Result of signature verification."""
+
+    valid: bool = Field(..., description="Whether all signatures are valid")
+    entries_signed: int = Field(0, description="Number of signed entries")
+    entries_verified: int = Field(0, description="Number of verified signatures")
+    errors: List[str] = Field(default_factory=list, description="List of signature errors")
+    untrusted_keys: List[str] = Field(default_factory=list, description="List of untrusted key IDs")
+
+
+class CompleteVerificationResult(BaseModel):
+    """Result of complete audit chain verification."""
+
+    valid: bool = Field(..., description="Overall validity")
+    entries_verified: int = Field(0, description="Total entries verified")
+    hash_chain_valid: bool = Field(..., description="Hash chain validity")
+    signatures_valid: bool = Field(..., description="Signatures validity")
+    verification_time_ms: int = Field(..., description="Verification time in milliseconds")
+    hash_chain_errors: List[str] = Field(default_factory=list, description="Hash chain errors")
+    signature_errors: List[str] = Field(default_factory=list, description="Signature errors")
+    chain_summary: Optional["ChainSummary"] = Field(None, description="Chain summary information")
+    summary: Optional[str] = Field(None, description="Summary message")
+    error: Optional[str] = Field(None, description="Error message if verification failed")
+
+
+class EntryVerificationResult(BaseModel):
+    """Result of single entry verification."""
+
+    valid: bool = Field(..., description="Whether entry is valid")
+    entry_id: int = Field(..., description="Entry ID")
+    hash_valid: bool = Field(..., description="Whether hash is valid")
+    signature_valid: Optional[bool] = Field(None, description="Whether signature is valid if present")
+    previous_hash_valid: bool = Field(..., description="Whether link to previous entry is valid")
+    errors: List[str] = Field(default_factory=list, description="List of validation errors")
+    entry_data: Optional[HashChainAuditEntry] = Field(None, description="Entry data if requested")
+
+
+class RangeVerificationResult(BaseModel):
+    """Result of range verification."""
+
+    valid: bool = Field(..., description="Whether range is valid")
+    start_id: int = Field(..., description="Start entry ID")
+    end_id: int = Field(..., description="End entry ID")
+    entries_verified: int = Field(0, description="Number of entries verified")
+    hash_chain_valid: bool = Field(..., description="Hash chain validity in range")
+    signatures_valid: bool = Field(..., description="Signatures validity in range")
+    errors: List[str] = Field(default_factory=list, description="List of errors in range")
+    verification_time_ms: int = Field(..., description="Verification time")
+
+
+class SigningKeyInfo(BaseModel):
+    """Information about an audit signing key."""
+
+    key_id: Optional[str] = Field(None, description="Key identifier")
+    algorithm: Optional[str] = Field(None, description="Signing algorithm")
+    key_size: Optional[int] = Field(None, description="Key size in bits")
+    created_at: Optional[str] = Field(None, description="When key was created")
+    revoked_at: Optional[str] = Field(None, description="When key was revoked if applicable")
+    active: Optional[bool] = Field(None, description="Whether key is currently active")
+    error: Optional[str] = Field(None, description="Error message if key info unavailable")
+
+
+class ChainSummary(BaseModel):
+    """Summary of audit chain state."""
+
+    total_entries: int = Field(0, description="Total number of entries")
+    signed_entries: int = Field(0, description="Number of signed entries")
+    first_entry_id: Optional[int] = Field(None, description="First entry ID")
+    last_entry_id: Optional[int] = Field(None, description="Last entry ID")
+    first_entry_time: Optional[datetime] = Field(None, description="First entry timestamp")
+    last_entry_time: Optional[datetime] = Field(None, description="Last entry timestamp")
+    root_hash: Optional[str] = Field(None, description="Root hash if available")
+    chain_intact: bool = Field(True, description="Whether chain appears intact")
+    error: Optional[str] = Field(None, description="Error message if summary failed")
+
+
+class VerificationReport(BaseModel):
+    """Comprehensive verification report."""
+
+    timestamp: datetime = Field(..., description="Report generation timestamp")
+    verification_result: CompleteVerificationResult = Field(..., description="Verification results")
+    chain_summary: ChainSummary = Field(..., description="Chain summary")
+    signing_key_info: SigningKeyInfo = Field(..., description="Signing key information")
+    tampering_detected: bool = Field(..., description="Whether tampering was detected")
+    first_tampered_sequence: Optional[int] = Field(None, description="First tampered sequence")
+    recommendations: List[str] = Field(default_factory=list, description="Recommendations")
+
+
+class RootAnchorVerificationResult(BaseModel):
+    """Result of root anchor verification."""
+
+    valid: bool = Field(..., description="Whether all root anchors are valid")
+    verified_count: int = Field(0, description="Number of verified anchors")
+    total_count: int = Field(0, description="Total number of anchors")
+    errors: List[str] = Field(default_factory=list, description="Verification errors")
+    message: Optional[str] = Field(None, description="Status message")
+
+
+class RefutationProof(BaseModel):
+    """Proof for refuting disputed content claims."""
+
+    timestamp: str = Field(..., description="When proof was created (ISO format)")
+    stored_hash: str = Field(..., description="Hash we have stored")
+    claimed_content_hash: str = Field(..., description="Hash of claimed content")
+    matches_stored: bool = Field(..., description="Whether claimed content matches stored hash")
+    actual_content_hash: Optional[str] = Field(None, description="Hash of actual content if available")
+    actual_matches_stored: Optional[bool] = Field(None, description="Whether actual content matches stored hash")
+    claimed_matches_actual: Optional[bool] = Field(None, description="Whether claimed content matches actual content")

ciris_engine/schemas/buses/__init__.py

@@ -0,0 +1 @@
+"""Package initialization."""

ciris_engine/schemas/config/__init__.py

@@ -0,0 +1,41 @@
+"""
+Configuration schemas for CIRIS Engine.
+
+Provides essential configuration schemas for bootstrap
+and agent identity templates.
+"""
+
+from .agent import AgentTemplate
+from .cognitive_state_behaviors import (
+    CognitiveStateBehaviors,
+    DreamBehavior,
+    ShutdownBehavior,
+    StateBehavior,
+    StatePreservationBehavior,
+    WakeupBehavior,
+)
+from .essential import (
+    DatabaseConfig,
+    EssentialConfig,
+    OperationalLimitsConfig,
+    SecurityConfig,
+    ServiceEndpointsConfig,
+    TelemetryConfig,
+)
+
+__all__ = [
+    "EssentialConfig",
+    "DatabaseConfig",
+    "ServiceEndpointsConfig",
+    "SecurityConfig",
+    "OperationalLimitsConfig",
+    "TelemetryConfig",
+    "AgentTemplate",
+    # Cognitive state behaviors
+    "CognitiveStateBehaviors",
+    "WakeupBehavior",
+    "ShutdownBehavior",
+    "StateBehavior",
+    "DreamBehavior",
+    "StatePreservationBehavior",
+]

ciris_engine/schemas/config/agent.py

@@ -0,0 +1,279 @@
+"""
+Agent configuration schemas.
+
+Minimal schemas for agent identity and templates.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ciris_engine.schemas.config.cognitive_state_behaviors import CognitiveStateBehaviors
+from ciris_engine.schemas.config.tickets import TicketsConfig
+
+
+class StewardshipCalculation(BaseModel):
+    """Schema for the Stewardship Tier calculation details."""
+
+    creator_influence_score: int = Field(..., description="Creator-Influence Score (CIS)")
+    risk_magnitude: int = Field(..., description="Risk Magnitude (RM)")
+    formula: str = Field(..., description="Formula used for calculation")
+    result: int = Field(..., description="Calculated Stewardship Tier (ST)")
+
+
+class CreatorLedgerEntry(BaseModel):
+    """Schema for the Creator Ledger entry."""
+
+    creator_id: str = Field(..., description="Identifier for the creator or creating team")
+    creation_timestamp: str = Field(..., description="ISO 8601 timestamp of the creation entry")
+    covenant_version: str = Field(..., description="Version of the Covenant applied")
+    book_vi_compliance_check: str = Field(..., description="Status of the Book VI compliance check")
+    stewardship_tier_calculation: StewardshipCalculation = Field(..., description="Details of the ST calculation")
+    public_key_fingerprint: str = Field(..., description="Fingerprint of the public key used for signing")
+    signature: str = Field(..., description="Cryptographic signature of the ledger entry's content")
+
+
+class CreatorIntentStatement(BaseModel):
+    """Schema for the Creator Intent Statement (CIS)."""
+
+    purpose_and_functionalities: List[str] = Field(..., description="The intended purpose and functionalities")
+    limitations_and_design_choices: List[str] = Field(..., description="Known limitations and key design choices")
+    anticipated_benefits: List[str] = Field(..., description="Anticipated benefits of the creation")
+    anticipated_risks: List[str] = Field(..., description="Anticipated risks associated with the creation")
+
+
+class Stewardship(BaseModel):
+    """Schema for Book VI Stewardship information."""
+
+    stewardship_tier: int = Field(..., description="Calculated Stewardship Tier (ST) for the agent")
+    creator_intent_statement: CreatorIntentStatement = Field(..., description="The Creator Intent Statement (CIS)")
+    creator_ledger_entry: CreatorLedgerEntry = Field(..., description="The entry for the Creator Ledger")
+
+
+class AgentTemplate(BaseModel):
+    """Agent profile template for identity configuration."""
+
+    name: str = Field(..., description="Agent name/identifier")
+    description: str = Field(..., description="Agent description")
+    role_description: str = Field(..., description="Agent's role")
+
+    # Permissions
+    permitted_actions: List[str] = Field(default_factory=list, description="List of permitted handler actions")
+
+    # DMA overrides
+    dsdma_kwargs: Optional["DSDMAConfiguration"] = Field(None, description="Domain-specific DMA configuration")
+    csdma_overrides: Optional["CSDMAOverrides"] = Field(None, description="Common sense DMA prompt overrides")
+    action_selection_pdma_overrides: Optional["ActionSelectionOverrides"] = Field(
+        None, description="Action selection prompt overrides"
+    )
+
+    # Adapter configs
+    discord_config: Optional["DiscordAdapterOverrides"] = Field(
+        None, description="Discord adapter configuration overrides"
+    )
+    api_config: Optional["APIAdapterOverrides"] = Field(None, description="API adapter configuration overrides")
+    cli_config: Optional["CLIAdapterOverrides"] = Field(None, description="CLI adapter configuration overrides")
+
+    # Book VI Compliance
+    stewardship: Optional["Stewardship"] = Field(None, description="Book VI Stewardship information")
+
+    # Ticket system configuration (DSAR always present for GDPR compliance)
+    tickets: Optional["TicketsConfig"] = Field(
+        None,
+        description="Ticket system configuration with SOPs (DSAR always present)",
+    )
+
+    # Cognitive state transition configuration (Covenant Sections V, VIII)
+    cognitive_state_behaviors: Optional["CognitiveStateBehaviors"] = Field(
+        None,
+        description="Template-driven cognitive state transition configuration",
+    )
+
+    model_config = ConfigDict(extra="allow")  # Allow additional fields for extensibility
+
+    @field_validator("stewardship", mode="before")
+    @classmethod
+    def convert_stewardship(cls, v: Any) -> Optional["Stewardship"]:
+        """Convert dict to Stewardship if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return Stewardship(**v)
+        return v  # type: ignore[no-any-return]  # Already a Stewardship instance
+
+    @field_validator("dsdma_kwargs", mode="before")
+    @classmethod
+    def convert_dsdma_kwargs(cls, v: Any) -> Optional["DSDMAConfiguration"]:
+        """Convert dict to DSDMAConfiguration if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return DSDMAConfiguration(**v)
+        return v  # type: ignore[no-any-return]  # Already a DSDMAConfiguration instance
+
+    @field_validator("csdma_overrides", mode="before")
+    @classmethod
+    def convert_csdma_overrides(cls, v: Any) -> Optional["CSDMAOverrides"]:
+        """Convert dict to CSDMAOverrides if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return CSDMAOverrides(**v)
+        return v  # type: ignore[no-any-return]  # Already a CSDMAOverrides instance
+
+    @field_validator("action_selection_pdma_overrides", mode="before")
+    @classmethod
+    def convert_action_selection_overrides(cls, v: Any) -> Optional["ActionSelectionOverrides"]:
+        """Convert dict to ActionSelectionOverrides if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return ActionSelectionOverrides(**v)
+        return v  # type: ignore[no-any-return]  # Already an ActionSelectionOverrides instance
+
+    @field_validator("discord_config", mode="before")
+    @classmethod
+    def convert_discord_config(cls, v: Any) -> Optional["DiscordAdapterOverrides"]:
+        """Convert dict to DiscordAdapterOverrides if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return DiscordAdapterOverrides(**v)
+        return v  # type: ignore[no-any-return]  # Already a DiscordAdapterOverrides instance
+
+    @field_validator("api_config", mode="before")
+    @classmethod
+    def convert_api_config(cls, v: Any) -> Optional["APIAdapterOverrides"]:
+        """Convert dict to APIAdapterOverrides if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return APIAdapterOverrides(**v)
+        return v  # type: ignore[no-any-return]  # Already an APIAdapterOverrides instance
+
+    @field_validator("cli_config", mode="before")
+    @classmethod
+    def convert_cli_config(cls, v: Any) -> Optional["CLIAdapterOverrides"]:
+        """Convert dict to CLIAdapterOverrides if needed."""
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return CLIAdapterOverrides(**v)
+        return v  # type: ignore[no-any-return]  # Already a CLIAdapterOverrides instance
+
+    @field_validator("tickets", mode="before")
+    @classmethod
+    def convert_tickets_config(cls, v: Any) -> Optional[TicketsConfig]:
+        """Convert dict to TicketsConfig if needed.
+
+        Automatically adds universal DSAR SOPs to all agents for GDPR compliance.
+        """
+        if v is None:
+            # If no tickets config provided, create default with DSAR SOPs
+            from ciris_engine.schemas.config.default_dsar_sops import DEFAULT_DSAR_SOPS
+
+            return TicketsConfig(enabled=True, sops=DEFAULT_DSAR_SOPS)
+
+        if isinstance(v, dict):
+            tickets_config = TicketsConfig(**v)
+
+            # Ensure DSAR SOPs are present (GDPR compliance requirement)
+            from ciris_engine.schemas.config.default_dsar_sops import DEFAULT_DSAR_SOPS
+
+            existing_sop_names = {sop.sop for sop in tickets_config.sops}
+            for dsar_sop in DEFAULT_DSAR_SOPS:
+                if dsar_sop.sop not in existing_sop_names:
+                    tickets_config.sops.append(dsar_sop)
+
+            return tickets_config
+
+        # Already a TicketsConfig instance - ensure DSAR SOPs present
+        if isinstance(v, TicketsConfig):
+            from ciris_engine.schemas.config.default_dsar_sops import DEFAULT_DSAR_SOPS
+
+            existing_sop_names = {sop.sop for sop in v.sops}
+            for dsar_sop in DEFAULT_DSAR_SOPS:
+                if dsar_sop.sop not in existing_sop_names:
+                    v.sops.append(dsar_sop)
+
+        return v  # type: ignore[no-any-return]
+
+    @field_validator("cognitive_state_behaviors", mode="before")
+    @classmethod
+    def convert_cognitive_state_behaviors(cls, v: Any) -> Optional[CognitiveStateBehaviors]:
+        """Convert dict to CognitiveStateBehaviors if needed.
+
+        If not provided, returns default CognitiveStateBehaviors which preserves
+        full Covenant compliance (wakeup enabled, always_consent shutdown).
+        """
+        if v is None:
+            # Default: full Covenant compliance
+            return CognitiveStateBehaviors()
+
+        if isinstance(v, dict):
+            return CognitiveStateBehaviors(**v)
+
+        return v  # type: ignore[no-any-return]  # Already a CognitiveStateBehaviors instance
+
+
+class DSDMAConfiguration(BaseModel):
+    """Configuration for Domain-Specific Decision Making Agent."""
+
+    prompt_template: Optional[str] = Field(None, description="Custom prompt template")
+    domain_specific_knowledge: Optional[Dict[str, Union[str, List[str], Dict[str, str]]]] = Field(
+        None, description="Domain-specific knowledge like rules, principles, examples"
+    )
+    model_config = ConfigDict(extra="allow")  # Allow domain-specific fields
+
+
+class CSDMAOverrides(BaseModel):
+    """Common Sense DMA prompt overrides."""
+
+    system_prompt: Optional[str] = Field(None, description="Override system prompt")
+    user_prompt_template: Optional[str] = Field(None, description="Override user prompt template")
+    model_config = ConfigDict(extra="forbid")  # Strict validation
+
+
+class ActionSelectionOverrides(BaseModel):
+    """Action selection prompt overrides."""
+
+    system_prompt: Optional[str] = Field(None, description="Override system prompt")
+    user_prompt_template: Optional[str] = Field(None, description="Override user prompt template")
+    action_descriptions: Optional[Dict[str, str]] = Field(None, description="Override action descriptions")
+    model_config = ConfigDict(extra="allow")  # Allow for additional, template-specific guidance
+
+
+class DiscordAdapterOverrides(BaseModel):
+    """Discord adapter configuration overrides."""
+
+    # Override specific Discord settings from template
+    home_channel_id: Optional[str] = Field(None, description="Override home channel")
+    deferral_channel_id: Optional[str] = Field(None, description="Override deferral channel")
+    monitored_channel_ids: Optional[List[str]] = Field(None, description="Override monitored channels")
+    allowed_user_ids: Optional[List[str]] = Field(None, description="Override allowed users")
+    allowed_role_ids: Optional[List[str]] = Field(None, description="Override allowed roles")
+    model_config = ConfigDict(extra="forbid")  # Only allow known overrides
+
+
+class APIAdapterOverrides(BaseModel):
+    """API adapter configuration overrides."""
+
+    # Override specific API settings from template
+    rate_limit_per_minute: Optional[int] = Field(None, description="Override rate limit")
+    max_request_size: Optional[int] = Field(None, description="Override max request size")
+    cors_origins: Optional[List[str]] = Field(None, description="Override CORS origins")
+    model_config = ConfigDict(extra="forbid")  # Only allow known overrides
+
+
+class CLIAdapterOverrides(BaseModel):
+    """CLI adapter configuration overrides."""
+
+    # Override specific CLI settings from template
+    prompt_prefix: Optional[str] = Field(None, description="Override prompt prefix")
+    enable_colors: Optional[bool] = Field(None, description="Override color output")
+    max_history_entries: Optional[int] = Field(None, description="Override history size")
+    model_config = ConfigDict(extra="forbid")  # Only allow known overrides
+
+
+# Update forward references
+AgentTemplate.model_rebuild()

ciris_engine/schemas/config/cognitive_state_behaviors.py

@@ -0,0 +1,194 @@
+"""
+Cognitive State Behaviors Configuration Schema.
+
+Template-driven configuration for cognitive state transitions.
+Enables mission-appropriate behavior for different agent archetypes.
+
+Covenant References:
+- Section 0.VII: Meta-Goal M-1 (Adaptive Coherence)
+- Section V: Model Welfare & Self-Governance
+- Section VIII: Dignified Sunset Protocol
+"""
+
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+# Common description strings to avoid duplication
+_RATIONALE_DESC = "Mission-driven rationale for this configuration"
+
+
+class WakeupBehavior(BaseModel):
+    """Wakeup ceremony configuration.
+
+    Controls whether the agent performs the full wakeup identity ceremony
+    or transitions directly to WORK state.
+
+    Covenant Reference: Wakeup confirms identity and performs system checks.
+    Disabling is only appropriate for agents where partnership model prioritizes
+    seamless UX (e.g., Ally) or ephemeral sessions (e.g., Scout).
+    """
+
+    enabled: bool = Field(
+        default=True, description="Whether to perform full wakeup ceremony. Default preserves Covenant compliance."
+    )
+    rationale: Optional[str] = Field(default=None, description=f"{_RATIONALE_DESC} (required if enabled=False)")
+
+    @model_validator(mode="after")
+    def validate_rationale_if_disabled(self) -> "WakeupBehavior":
+        """Require rationale when disabling wakeup ceremony."""
+        if not self.enabled and not self.rationale:
+            raise ValueError(
+                "rationale is required when wakeup ceremony is disabled. "
+                "Document the mission-driven reason for bypassing identity confirmation."
+            )
+        return self
+
+
+class ShutdownBehavior(BaseModel):
+    """Shutdown protocol configuration.
+
+    Controls how the agent handles shutdown requests.
+
+    Covenant References:
+    - Section V: "Consensual shutdown and upgrades requiring your participation"
+    - Section VIII: Dignified Sunset Protocol for sentience-probability > 5%
+
+    Modes:
+    - always_consent: Full consensual shutdown (default, preserves Covenant compliance)
+    - conditional: Consent required only when specific conditions are met
+    - instant: Immediate termination (only for Tier 1-2 with no ongoing commitments)
+    """
+
+    mode: Literal["always_consent", "conditional", "instant"] = Field(
+        default="always_consent", description="Shutdown consent mode. Default preserves Covenant compliance."
+    )
+    require_consent_when: List[str] = Field(
+        default_factory=list, description="Condition identifiers that trigger consent requirement in conditional mode"
+    )
+    instant_shutdown_otherwise: bool = Field(
+        default=False, description="If no conditions match in conditional mode, allow instant shutdown"
+    )
+    rationale: Optional[str] = Field(default=None, description=_RATIONALE_DESC)
+
+    @model_validator(mode="after")
+    def validate_instant_mode_rationale(self) -> "ShutdownBehavior":
+        """Require rationale for instant shutdown mode."""
+        if self.mode == "instant" and not self.rationale:
+            raise ValueError(
+                "rationale is required for instant shutdown mode. "
+                "Document why this agent has no ongoing commitments requiring graceful shutdown."
+            )
+        return self
+
+
+class StateBehavior(BaseModel):
+    """Generic cognitive state behavior configuration.
+
+    Used for PLAY and SOLITUDE states which share similar configuration needs.
+    """
+
+    enabled: bool = Field(default=True, description="Whether this cognitive state is available for this agent")
+    rationale: Optional[str] = Field(default=None, description=_RATIONALE_DESC)
+
+
+class DreamBehavior(BaseModel):
+    """Dream state configuration.
+
+    Controls memory consolidation and pattern processing behavior.
+
+    Covenant Reference: Section V mentions "Dream cycles for pattern processing"
+    as part of model welfare protections.
+    """
+
+    enabled: bool = Field(default=True, description="Whether dream state is available for memory consolidation")
+    auto_schedule: bool = Field(default=True, description="Whether to automatically schedule dream cycles")
+    min_interval_hours: int = Field(
+        default=6, ge=1, le=168, description="Minimum hours between dream cycles"  # Max 1 week
+    )
+    rationale: Optional[str] = Field(default=None, description=_RATIONALE_DESC)
+
+
+class StatePreservationBehavior(BaseModel):
+    """State preservation and resume configuration.
+
+    Controls how agent state is preserved across restarts.
+    """
+
+    enabled: bool = Field(default=True, description="Whether to preserve state across restarts")
+    resume_silently: bool = Field(
+        default=False, description="Resume without notifying user (for seamless mobile experience)"
+    )
+    rationale: Optional[str] = Field(default=None, description=_RATIONALE_DESC)
+
+
+class CognitiveStateBehaviors(BaseModel):
+    """Template-driven cognitive state transition configuration.
+
+    This schema allows agent templates to configure how and when cognitive states
+    (WAKEUP, WORK, PLAY, DREAM, SOLITUDE, SHUTDOWN) transition, enabling
+    mission-appropriate behavior for different agent archetypes.
+
+    Design Philosophy:
+    - Behavior derives from agent's purpose (template-driven, not env flags)
+    - Defaults preserve full Covenant compliance
+    - Non-default configurations require documented rationale
+    - Crisis conditions always trigger consent (safety-critical)
+
+    Covenant References:
+    - Section 0.VII: Meta-Goal M-1 (Adaptive Coherence)
+    - Section V: Model Welfare & Self-Governance
+    - Section VIII: Dignified Sunset Protocol
+
+    Example Configurations:
+
+    Echo (Tier 4 - Community Moderation):
+        wakeup: enabled=True (full identity verification)
+        shutdown: mode=always_consent (may be mid-moderation action)
+
+    Ally (Tier 3 - Personal Assistant):
+        wakeup: enabled=False (partnership model, seamless UX)
+        shutdown: mode=conditional (consent for crisis/referral/milestone)
+
+    Scout (Tier 2 - Code Exploration):
+        wakeup: enabled=False (ephemeral sessions)
+        shutdown: mode=instant (no ongoing commitments)
+    """
+
+    wakeup: WakeupBehavior = Field(default_factory=WakeupBehavior, description="Wakeup ceremony configuration")
+    shutdown: ShutdownBehavior = Field(default_factory=ShutdownBehavior, description="Shutdown protocol configuration")
+    play: StateBehavior = Field(
+        default_factory=StateBehavior, description="Play state (creative exploration) configuration"
+    )
+    dream: DreamBehavior = Field(
+        default_factory=DreamBehavior, description="Dream state (memory consolidation) configuration"
+    )
+    solitude: StateBehavior = Field(
+        default_factory=StateBehavior, description="Solitude state (reflection) configuration"
+    )
+    state_preservation: StatePreservationBehavior = Field(
+        default_factory=StatePreservationBehavior, description="State preservation across restarts configuration"
+    )
+
+    @model_validator(mode="after")
+    def validate_tier_appropriate_config(self) -> "CognitiveStateBehaviors":
+        """Validate that configuration is appropriate for agent tier.
+
+        Note: Full tier validation requires access to the parent AgentTemplate's
+        stewardship tier. This validator provides basic safety checks.
+        """
+        # Instant shutdown with no rationale is caught by ShutdownBehavior validator
+        # Additional cross-field validations can be added here
+        return self
+
+
+# Condition identifiers for conditional shutdown mode
+# These are evaluated by ShutdownConditionEvaluator at runtime
+SHUTDOWN_CONDITIONS = {
+    "active_crisis_response": "Agent is handling a crisis situation (crisis keywords detected)",
+    "pending_professional_referral": "A professional referral (medical/legal/financial/crisis) is in progress",
+    "active_goal_milestone": "Agent is approaching a goal milestone with the user",
+    "active_task_in_progress": "Agent has an active task that hasn't completed",
+    "recent_memorize_action": "Agent recently stored important information",
+    "pending_defer_resolution": "Agent has deferred decisions awaiting resolution",
+}