@spec close(db()) :: :ok | {:error, term()}

Closes the database connection.

@spec count(db()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the total number of agent events.

@spec delete_before(db(), DateTime.t()) :: {:ok, non_neg_integer()} | {:error, term()}

Deletes events older than the given wall-clock time.

@spec events_after(db(), String.t(), non_neg_integer(), pos_integer()) ::
  {:ok, [MingaAgent.EventLog.EventRecord.t()]} | {:error, term()}

Returns all events for a session with id greater than the cursor, ordered by id.

@spec file_edit_events(db()) ::
  {:ok, [MingaAgent.EventLog.EventRecord.t()]} | {:error, term()}

Returns every persisted file-edit event in durable order.

@spec file_edits_for_path(db(), String.t(), pos_integer()) ::
  {:ok, [MingaAgent.EventLog.EventRecord.t()]} | {:error, term()}

Returns :file_edit_proposed events whose payload path exactly matches, most recent first.

Used by code-provenance reads to find every agent edit that touched a file, across all sessions. Bounded by limit (newest events win).

@spec insert(db(), MingaAgent.EventLog.EventRecord.t()) ::
  {:ok, pos_integer()} | {:error, term()}

Inserts an append-only event record.

@spec integrity_check(db(), :full | :quick) ::
  {:ok, :healthy} | {:error, [String.t()]}

Runs a SQLite integrity check.

@spec latest_id(db(), String.t()) :: {:ok, non_neg_integer()} | {:error, term()}

Returns the latest event id for a session, or 0 when it has no events.

@spec open(String.t()) :: {:ok, db()} | {:error, term()}

Opens or creates the agent event database.

@spec open_memory() :: {:ok, db()} | {:error, term()}

Opens an in-memory database for tests.

@spec open_writer(
  String.t(),
  keyword()
) :: {:ok, db()} | {:error, term()}

Opens the writer connection, recreating a database that fails an integrity check.