AgentSessionManager.Ports.Maintenance behaviour (AgentSessionManager v0.8.0)

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)

Summary

Types

context()

maintenance_ref()

maintenance_report()

Callbacks

clean_orphaned_artifacts(context, keyword)

Clean up orphaned artifacts.

execute(context, t)

Execute retention policy against the store.

hard_delete_expired_sessions(context, t)

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

health_check(context)

Health check: verify data integrity.

prune_session_events(context, session_id, t)

Prune events for a single session based on policy.

soft_delete_expired_sessions(context, t)

Soft-delete completed sessions older than the retention period.

Functions

clean_orphaned_artifacts(maintenance_ref, opts \\ [])

execute(maintenance_ref, policy)

hard_delete_expired_sessions(maintenance_ref, policy)

health_check(maintenance_ref)

prune_session_events(maintenance_ref, session_id, policy)

soft_delete_expired_sessions(maintenance_ref, policy)

Types

context()

@type context() :: term()

maintenance_ref()

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

maintenance_report()

@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()]
}

Callbacks

clean_orphaned_artifacts(context, keyword)

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

Clean up orphaned artifacts.

execute(context, t)

@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(context, t)

@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(context)

@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(context, session_id, t)

@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(context, t)

@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.

Functions

clean_orphaned_artifacts(maintenance_ref, opts \\ [])

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

execute(maintenance_ref, policy)

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

hard_delete_expired_sessions(maintenance_ref, policy)

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

health_check(maintenance_ref)

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

prune_session_events(maintenance_ref, session_id, policy)

@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(maintenance_ref, policy)

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