diff --git a/hive-c0re/src/audit_log.rs b/hive-c0re/src/audit_log.rs
index 9b098b33..5f7760dd 100644
--- a/hive-c0re/src/audit_log.rs
+++ b/hive-c0re/src/audit_log.rs
@@ -109,6 +109,13 @@ pub struct AuditLog {
 }
 
 impl AuditLog {
+    /// Open (creating if absent) the `audit_log.sqlite` store under
+    /// `db_dir` and apply the schema. `db_dir` is shared with
+    /// `build_logs` (the broker db's parent directory).
+    ///
+    /// # Errors
+    /// Returns an error if the directory can't be created, the sqlite
+    /// file can't be opened, or applying the schema fails.
     pub fn open(db_dir: &Path) -> Result<Self> {
         std::fs::create_dir_all(db_dir)
             .with_context(|| format!("create audit_log db parent {}", db_dir.display()))?;
@@ -151,6 +158,10 @@ impl AuditLog {
 
     /// Return the most recent `limit` rows, newest first. Limit is
     /// hard-clamped to 500 to bound the worst-case payload.
+    ///
+    /// # Errors
+    /// Returns an error if the query fails to prepare or a row fails to
+    /// deserialize.
     pub fn list_recent(&self, limit: usize) -> Result<Vec<AuditEntry>> {
         let limit = limit.min(500);
         let conn = self.conn.lock().unwrap();
@@ -170,6 +181,9 @@ impl AuditLog {
 
     /// Total row count, regardless of the `list_recent` clamp. Lets the
     /// dashboard show "latest N of TOTAL" instead of silently capping.
+    ///
+    /// # Errors
+    /// Returns an error if the `COUNT(*)` query fails.
     pub fn count_total(&self) -> Result<i64> {
         let conn = self.conn.lock().unwrap();
         let n: i64 = conn.query_row("SELECT COUNT(*) FROM audit_log", [], |r| r.get(0))?;
@@ -178,6 +192,9 @@ impl AuditLog {
 
     /// Drop rows older than the retention window. Returns the number of
     /// rows deleted. Called from the hourly vacuum loop.
+    ///
+    /// # Errors
+    /// Returns an error if the `DELETE` query fails.
     pub fn vacuum(&self) -> Result<u64> {
         let cutoff = now_secs() - KEEP_SECS;
         let conn = self.conn.lock().unwrap();