From 1b8a6be8ce426c6963ba78d5109cb66f8cabc656 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive>
Date: Mon, 1 Jun 2026 10:34:51 +0200
Subject: [PATCH] docs: add build_logs.sqlite section to persistence.md, trim
 build_logs.rs module doc

---
 docs/persistence.md         | 22 ++++++++++++++++++++++
 hive-c0re/src/build_logs.rs | 24 ++++--------------------
 2 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/docs/persistence.md b/docs/persistence.md
index f5de1554..386e9e0c 100644
--- a/docs/persistence.md
+++ b/docs/persistence.md
@@ -127,6 +127,28 @@ sentinel files (`hyperhive-rate-limited`, `hyperhive-needs-login`) if the
 JSON is absent, so existing containers keep working through the transition
 window before their next rebuild.
 
+### `/var/lib/hyperhive/build_logs.sqlite` (host)
+
+Full stdout + stderr capture for every `nixos-container` / `nix
+build` invocation the lifecycle layer fires. One row per invocation;
+the row accumulates lines as the child runs.
+
+Replaces the legacy 32-line stderr ring buffer that `lifecycle::run`
+kept. The ring tail routinely truncated real eval errors ("tried
+alternatives" blocks alone are often 30+ lines), so failures bailed
+with an arbitrary tail whose full stream only lived in the host
+journal. With this table the dashboard can surface the entire log.
+
+Two indices:
+- `(agent, started_at)` — backs the per-agent latest-N lookup used
+  by the agent card chip.
+- `(status, finished_at)` — backs the retention sweep that runs
+  as part of the existing hourly vacuum.
+
+Writes are best-effort: `append_stdout` / `append_stderr` / `finish`
+log a warning on sqlite error and let the build continue. A failed
+log row never blocks a rebuild.
+
 ### `/state/hyperhive-model` (per agent)
 
 Single-line text file holding the claude model name currently
diff --git a/hive-c0re/src/build_logs.rs b/hive-c0re/src/build_logs.rs
index e54d7f01..f629cd93 100644
--- a/hive-c0re/src/build_logs.rs
+++ b/hive-c0re/src/build_logs.rs
@@ -1,23 +1,7 @@
-//! Sqlite-backed full build-log capture. One row per `nixos-container`
-//! / `nix build` invocation that the host-side lifecycle layer fires;
-//! the row accumulates stdout + stderr line-by-line as the child runs.
-//!
-//! Replaces the legacy 32-line stderr ring buffer in
-//! `lifecycle::run` / `lifecycle::prebuild_toplevel`. The ring tail
-//! routinely truncated the actual eval error (a "tried alternatives"
-//! block alone is often 30+ lines), so failures bailed with an
-//! arbitrary tail and the full stream only lived in the host journal.
-//! With this table the dashboard can surface the entire log.
-//!
-//! Storage lives next to the broker / approvals dbs (one file at
-//! `<db_path>/build_logs.sqlite`). Two indices:
-//! `(agent, started_at)` for the per-agent latest-N lookup that backs
-//! the agent card chip; `(status, finished_at)` for the retention
-//! sweep that runs as part of the existing hourly vacuum.
-//!
-//! Writes are best-effort: every `append_*` / `finish` call logs a
-//! warning on sqlite error and lets the build continue. A failed log
-//! row never breaks a rebuild.
+//! Sqlite-backed full build-log capture — stdout + stderr per
+//! `nixos-container` / `nix build` invocation, accumulated live.
+//! Schema, indices, retention, and the rationale for replacing
+//! the old ring buffer: `docs/persistence.md::/var/lib/hyperhive/build_logs.sqlite`.
 
 use std::path::Path;
 use std::sync::{Arc, Mutex, OnceLock};