Persistence¶

async def connect(self) -> None:
    """Establish connection to the storage backend.

    Raises:
        PersistenceConnectionError: If the connection cannot be
            established.
    """
    ...

async def disconnect(self) -> None:
    """Close the storage backend connection.

    Safe to call even if not connected.
    """
    ...

async def health_check(self) -> bool:
    """Check whether the backend is healthy and responsive.

    Returns:
        ``True`` if the backend is reachable and operational.
    """
    ...

async def migrate(self) -> None:
    """Run pending schema migrations.

    Raises:
        MigrationError: If a migration fails.
    """
    ...

def get_db(self) -> Any:
    """Return the underlying database connection.

    Returns:
        The raw database connection object (backend-specific).

    Raises:
        PersistenceConnectionError: If not yet connected.
    """
    ...

async def get_setting(self, key: NotBlankStr) -> str | None:
    """Retrieve a setting value by key.

    Args:
        key: Setting key.

    Returns:
        The setting value, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def set_setting(self, key: NotBlankStr, value: str) -> None:
    """Store a setting value.

    Upserts -- creates or updates the key.

    Args:
        key: Setting key.
        value: Setting value.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, record: CollaborationMetricRecord) -> None:
    """Persist a collaboration metric record.

    Args:
        record: The collaboration metric record to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def query(
    self,
    *,
    agent_id: NotBlankStr | None = None,
    since: AwareDatetime | None = None,
) -> tuple[CollaborationMetricRecord, ...]:
    """Query collaboration metric records with optional filters.

    Args:
        agent_id: Filter by agent identifier.
        since: Include records after this time.

    Returns:
        Matching collaboration metric records.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, event: AgentLifecycleEvent) -> None:
    """Persist a lifecycle event.

    Args:
        event: The lifecycle event to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def list_events(
    self,
    *,
    agent_id: NotBlankStr | None = None,
    event_type: LifecycleEventType | None = None,
    since: AwareDatetime | None = None,
    limit: int | None = None,
) -> tuple[AgentLifecycleEvent, ...]:
    """List lifecycle events with optional filters.

    Args:
        agent_id: Filter by agent identifier.
        event_type: Filter by event type.
        since: Filter events after this timestamp.
        limit: Maximum number of events to return. ``None`` for all.

    Returns:
        Matching lifecycle events.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, record: TaskMetricRecord) -> None:
    """Persist a task metric record.

    Args:
        record: The task metric record to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def query(
    self,
    *,
    agent_id: NotBlankStr | None = None,
    since: AwareDatetime | None = None,
    until: AwareDatetime | None = None,
) -> tuple[TaskMetricRecord, ...]:
    """Query task metric records with optional filters.

    Args:
        agent_id: Filter by agent identifier.
        since: Include records after this time.
        until: Include records before this time.

    Returns:
        Matching task metric records.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, task: Task) -> None:
    """Persist a task (insert or update).

    Args:
        task: The task to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get(self, task_id: NotBlankStr) -> Task | None:
    """Retrieve a task by its ID.

    Args:
        task_id: The task identifier.

    Returns:
        The task, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def list_tasks(
    self,
    *,
    status: TaskStatus | None = None,
    assigned_to: NotBlankStr | None = None,
    project: NotBlankStr | None = None,
) -> tuple[Task, ...]:
    """List tasks with optional filters.

    Args:
        status: Filter by task status.
        assigned_to: Filter by assignee agent ID.
        project: Filter by project ID.

    Returns:
        Matching tasks as a tuple.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def delete(self, task_id: NotBlankStr) -> bool:
    """Delete a task by ID.

    Args:
        task_id: The task identifier.

    Returns:
        ``True`` if the task was deleted, ``False`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, record: CostRecord) -> None:
    """Persist a cost record (append-only).

    Args:
        record: The cost record to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def query(
    self,
    *,
    agent_id: NotBlankStr | None = None,
    task_id: NotBlankStr | None = None,
) -> tuple[CostRecord, ...]:
    """Query cost records with optional filters.

    Args:
        agent_id: Filter by agent identifier.
        task_id: Filter by task identifier.

    Returns:
        Matching cost records as a tuple.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def aggregate(
    self,
    *,
    agent_id: NotBlankStr | None = None,
    task_id: NotBlankStr | None = None,
) -> float:
    """Sum total cost_usd, optionally filtered by agent and/or task.

    Args:
        agent_id: Filter by agent identifier.
        task_id: Filter by task identifier.

    Returns:
        Total cost in USD (base currency).

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, message: Message) -> None:
    """Persist a message.

    Args:
        message: The message to persist.

    Raises:
        DuplicateRecordError: If a message with the same ID exists.
        PersistenceError: If the operation fails.
    """
    ...

async def get_history(
    self,
    channel: NotBlankStr,
    *,
    limit: int | None = None,
) -> tuple[Message, ...]:
    """Retrieve message history for a channel.

    Args:
        channel: Channel name to query.
        limit: Maximum number of messages to return (newest first).

    Returns:
        Messages ordered by timestamp descending.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, context: ParkedContext) -> None:
    """Persist a parked context.

    Args:
        context: The parked context to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get(self, parked_id: NotBlankStr) -> ParkedContext | None:
    """Retrieve a parked context by ID.

    Args:
        parked_id: The parked context identifier.

    Returns:
        The parked context, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get_by_approval(self, approval_id: NotBlankStr) -> ParkedContext | None:
    """Retrieve a parked context by approval ID.

    Args:
        approval_id: The approval item identifier.

    Returns:
        The parked context, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get_by_agent(self, agent_id: NotBlankStr) -> tuple[ParkedContext, ...]:
    """Retrieve all parked contexts for an agent.

    Args:
        agent_id: The agent identifier.

    Returns:
        Parked contexts for the agent.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def delete(self, parked_id: NotBlankStr) -> bool:
    """Delete a parked context by ID.

    Args:
        parked_id: The parked context identifier.

    Returns:
        ``True`` if deleted, ``False`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, entry: AuditEntry) -> None:
    """Persist an audit entry (append-only).

    Args:
        entry: The audit entry to persist.

    Raises:
        DuplicateRecordError: If an entry with the same ID exists.
        QueryError: If the operation fails.
    """
    ...

async def query(  # noqa: PLR0913
    self,
    *,
    agent_id: NotBlankStr | None = None,
    action_type: str | None = None,
    verdict: AuditVerdictStr | None = None,
    risk_level: ApprovalRiskLevel | None = None,
    since: AwareDatetime | None = None,
    until: AwareDatetime | None = None,
    limit: int = 100,
) -> tuple[AuditEntry, ...]:
    """Query audit entries with optional filters.

    Filters are AND-combined. Results are ordered by timestamp
    descending (newest first).

    Args:
        agent_id: Filter by agent identifier.
        action_type: Filter by action type string.
        verdict: Filter by verdict string.
        risk_level: Filter by risk level.
        since: Only return entries at or after this timestamp.
        until: Only return entries at or before this timestamp.
        limit: Maximum number of entries to return (must be >= 1).

    Returns:
        Matching audit entries as a tuple.

    Raises:
        QueryError: If the operation fails, *limit* < 1, or
            *until* is earlier than *since*.
    """
    ...

async def save(self, user: User) -> None:
    """Persist a user (insert or update).

    Args:
        user: The user to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get(self, user_id: NotBlankStr) -> User | None:
    """Retrieve a user by ID.

    Args:
        user_id: The user identifier.

    Returns:
        The user, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get_by_username(self, username: NotBlankStr) -> User | None:
    """Retrieve a user by username.

    Args:
        username: The login username.

    Returns:
        The user, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def list_users(self) -> tuple[User, ...]:
    """List all human users (excludes the system user).

    Returns:
        Human users as a tuple.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def count(self) -> int:
    """Count the number of human users (excludes the system user).

    Returns:
        Human user count.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def count_by_role(self, role: HumanRole) -> int:
    """Count users with a specific role.

    Args:
        role: The role to filter by.

    Returns:
        Number of users with the given role.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def delete(self, user_id: NotBlankStr) -> bool:
    """Delete a user by ID.

    Args:
        user_id: The user identifier.

    Returns:
        ``True`` if deleted, ``False`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, key: ApiKey) -> None:
    """Persist an API key.

    Args:
        key: The API key to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get(self, key_id: NotBlankStr) -> ApiKey | None:
    """Retrieve an API key by ID.

    Args:
        key_id: The key identifier.

    Returns:
        The API key, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def get_by_hash(self, key_hash: NotBlankStr) -> ApiKey | None:
    """Retrieve an API key by its hash.

    Args:
        key_hash: HMAC-SHA256 hex digest.

    Returns:
        The API key, or ``None`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def list_by_user(self, user_id: NotBlankStr) -> tuple[ApiKey, ...]:
    """List API keys belonging to a user.

    Args:
        user_id: The owner user ID.

    Returns:
        API keys for the user.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def delete(self, key_id: NotBlankStr) -> bool:
    """Delete an API key by ID.

    Args:
        key_id: The key identifier.

    Returns:
        ``True`` if deleted, ``False`` if not found.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...

async def save(self, checkpoint: Checkpoint) -> None:
    """Persist a checkpoint (insert or replace by ID).

    Args:
        checkpoint: The checkpoint to persist.

    Raises:
        PersistenceError: If the operation fails.
    """
    ...