# `AgentSessionManager.Ports.Maintenance`
[🔗](https://github.com/nshkrdotcom/agent_session_manager/blob/v0.8.0/lib/agent_session_manager/ports/maintenance.ex#L1)

Port for database maintenance operations.

Provides retention enforcement, event pruning, and data integrity checks.
Maintenance is never automatically scheduled — the application must call
it explicitly (e.g., via a mix task, GenServer timer, or job scheduler).

## Usage

    policy = RetentionPolicy.new(max_completed_session_age_days: 90)
    {:ok, report} = Maintenance.execute({EctoMaintenance, MyApp.Repo}, policy)

# `context`

```elixir
@type context() :: term()
```

# `maintenance_ref`

```elixir
@type maintenance_ref() :: {module(), context()}
```

# `maintenance_report`

```elixir
@type maintenance_report() :: %{
  sessions_soft_deleted: non_neg_integer(),
  sessions_hard_deleted: non_neg_integer(),
  events_pruned: non_neg_integer(),
  artifacts_cleaned: non_neg_integer(),
  orphaned_sequences_cleaned: non_neg_integer(),
  duration_ms: non_neg_integer(),
  errors: [String.t()]
}
```

# `clean_orphaned_artifacts`

```elixir
@callback clean_orphaned_artifacts(
  context(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

Clean up orphaned artifacts.

# `execute`

```elixir
@callback execute(context(), AgentSessionManager.Persistence.RetentionPolicy.t()) ::
  {:ok, maintenance_report()} | {:error, AgentSessionManager.Core.Error.t()}
```

Execute retention policy against the store.

Performs all applicable maintenance operations based on the policy.

# `hard_delete_expired_sessions`

```elixir
@callback hard_delete_expired_sessions(
  context(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) ::
  {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

Hard-delete sessions that were soft-deleted longer ago than hard_delete_after_days.

# `health_check`

```elixir
@callback health_check(context()) ::
  {:ok, [String.t()]} | {:error, AgentSessionManager.Core.Error.t()}
```

Health check: verify data integrity.

Returns a list of issue descriptions. Empty list means healthy.

# `prune_session_events`

```elixir
@callback prune_session_events(
  context(),
  session_id :: String.t(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

Prune events for a single session based on policy.

# `soft_delete_expired_sessions`

```elixir
@callback soft_delete_expired_sessions(
  context(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) ::
  {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

Soft-delete completed sessions older than the retention period.

# `clean_orphaned_artifacts`

```elixir
@spec clean_orphaned_artifacts(
  maintenance_ref(),
  keyword()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

# `execute`

```elixir
@spec execute(maintenance_ref(), AgentSessionManager.Persistence.RetentionPolicy.t()) ::
  {:ok, maintenance_report()} | {:error, AgentSessionManager.Core.Error.t()}
```

# `hard_delete_expired_sessions`

```elixir
@spec hard_delete_expired_sessions(
  maintenance_ref(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

# `health_check`

```elixir
@spec health_check(maintenance_ref()) ::
  {:ok, [String.t()]} | {:error, AgentSessionManager.Core.Error.t()}
```

# `prune_session_events`

```elixir
@spec prune_session_events(
  maintenance_ref(),
  String.t(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

# `soft_delete_expired_sessions`

```elixir
@spec soft_delete_expired_sessions(
  maintenance_ref(),
  AgentSessionManager.Persistence.RetentionPolicy.t()
) :: {:ok, non_neg_integer()} | {:error, AgentSessionManager.Core.Error.t()}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*