khive-pack-knowledge 0.19.0

Knowledge verb pack — lore corpus (atoms/domains), TF-IDF retrieval, concept registration
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
use super::*;

/// Persist `bridge` at its applied watermark, reopen and publish the mmap
/// segment, then raise this consumer's registry row and compact through the
/// pair MIN. Publishing before the durable raise makes the ADR-118 mismatch
/// window empty for this process; a crash before the raise merely
/// under-compacts. Registration still precedes persistence (ADR-079 Amendment
/// 1 §A step 1). On persist/reopen failure the Owned bridge is installed.
pub(crate) async fn checkpoint_raise_compact_readopt(
    rt: &KhiveRuntime,
    ann: &SharedAnn,
    key: &AnnKey,
    bridge: AnnBridge,
    generation: u64,
    authority: CheckpointAuthority,
) -> bool {
    let ns = key.namespace.as_str();
    let model = key.model.as_str();
    let local_publication_lock = checkpoint_lock(ann, key);
    let _local_publication_guard = local_publication_lock.lock().await;

    // This lock spans the complete knowledge-level publication: Vamana
    // segments, UUID sidecar, mmap verification, and the durable registry
    // transition.  The sentinel writer takes the same lock, so an ordinary
    // replay checkpoint that predates registry loss cannot publish after -1.
    let publication_lock = match ann_segment_dir(rt, ns, model) {
        Some(dir) => match khive_retrieval::ann::acquire_checkpoint_lock_async(
            dir,
            BRIDGE_LOCK_MESSAGE_PREFIX,
        )
        .await
        {
            Ok(lock) => Some(lock),
            Err(error) => {
                tracing::warn!(error = %error, "failed to acquire ANN checkpoint lock");
                return false;
            }
        },
        None => None,
    };

    let applied = bridge.index.last_applied_seq().unwrap_or(0);
    let own_watermark = match read_own_watermark(rt, ns, model).await {
        Ok(value) => value,
        Err(error) => {
            tracing::warn!(error = %error, "ann checkpoint registry read failed");
            return false;
        }
    };
    if authority == CheckpointAuthority::FullSentinel {
        if let Some(observed) = own_watermark.filter(|watermark| *watermark >= 0) {
            tracing::info!(
                key = ?key,
                observed_watermark = observed,
                "authoritative ANN rebuild lost publication race; adopting winner"
            );
            let observed = u64::try_from(observed).unwrap_or(0);
            return adopt_checkpoint_winner(rt, ann, key, generation, observed).await;
        }
    } else if let Some(observed) = own_watermark.filter(|watermark| *watermark >= 0) {
        let observed = u64::try_from(observed).unwrap_or(0);
        if observed > applied {
            tracing::info!(
                key = ?key,
                candidate_watermark = applied,
                observed_watermark = observed,
                "stale ANN checkpoint lost publication race; adopting winner"
            );
            return adopt_checkpoint_winner(rt, ann, key, generation, observed).await;
        }
    }
    let authorized = match authority {
        CheckpointAuthority::FullSentinel => own_watermark == Some(-1),
        CheckpointAuthority::Incremental | CheckpointAuthority::FullRegistered => {
            own_watermark.is_some_and(|watermark| watermark >= 0)
        }
    };
    if !authorized {
        mark_force_rebuild(ann, key);
        if let Err(error) = write_force_rebuild_sentinel_row(rt, key).await {
            tracing::warn!(error = %error, "failed to fence unauthorized ANN checkpoint");
        }
        return false;
    }

    if let Err(e) = persist_ann_v2_locked(rt, ns, model, &bridge) {
        tracing::error!(error = %e, "failed to persist v2 Vamana segment");
        install_replacing(ann, key, bridge.with_generation(generation)).await;
        return false;
    }
    let published = match ann_segment_dir(rt, ns, model) {
        Some(dir) => match AnnBridge::load(&dir) {
            Ok(mmap_bridge) => mmap_bridge,
            Err(e) => {
                tracing::warn!(error = %e, "mmap re-adoption failed; serving Owned build");
                bridge
            }
        },
        None => bridge,
    };
    // File-backed publication must replace the in-process bridge before the
    // durable raise, closing the same-process mismatch window. An in-memory
    // runtime has no cross-process segment or compaction peer, so defer its
    // install until the conditional raise succeeds; a losing concurrent full
    // scan then cannot overwrite the winner before discovering the lost race.
    let file_backed = publication_lock.is_some();
    let mut pending_in_memory = Some(published.with_generation(generation));
    let mut installed = false;
    if file_backed {
        installed = install_replacing(
            ann,
            key,
            pending_in_memory.take().expect("published bridge"),
        )
        .await;
    }

    // The durable segment already covers `applied`, and this process now
    // serves that same state. A failed raise only retains extra log rows.
    if let Err(e) = raise_watermark(rt, ns, model, applied, authority).await {
        tracing::warn!(error = %e, "ann watermark raise failed (under-compacts; safe)");
        match read_own_watermark(rt, ns, model).await {
            Ok(Some(observed)) if observed >= 0 => {
                let observed = u64::try_from(observed).unwrap_or(0);
                if observed > applied {
                    return adopt_checkpoint_winner(rt, ann, key, generation, observed).await;
                }
                // Either our conditional transition committed despite an
                // uncertain client result, or the durable row remains behind
                // this candidate. Both are safe under-compaction states.
                if let Some(published) = pending_in_memory.take() {
                    installed = install_replacing(ann, key, published).await;
                }
                clear_force_rebuild(ann, key);
                return installed || has_current_index_at_watermark(ann, key, observed).await;
            }
            Ok(_) => {}
            Err(read_error) => {
                tracing::warn!(
                    error = %read_error,
                    "failed to reconcile ANN checkpoint race"
                );
            }
        }
        mark_force_rebuild(ann, key);
        if let Err(error) = write_force_rebuild_sentinel_row(rt, key).await {
            tracing::warn!(error = %error, "failed to restore ANN checkpoint fence");
        }
        return false;
    }
    if let Some(published) = pending_in_memory {
        installed = install_replacing(ann, key, published).await;
    }
    if authority != CheckpointAuthority::Incremental {
        clear_force_rebuild_if_current(ann, key, generation);
    }
    drop(publication_lock);
    if let Err(e) = compact_log(rt, ns, model).await {
        tracing::warn!(error = %e, "ann log compaction failed (retries next checkpoint)");
    }
    installed
}

/// Try to load a Vamana snapshot for `namespace`+`model` from `retrieval_snapshots`.
///
/// Returns `Ok(None)` when the table is absent, the row is missing, or
/// deserialization fails — all of which are treated as cache-miss signals.
pub(super) async fn try_load_snapshot(
    rt: &KhiveRuntime,
    namespace: &str,
    model: &str,
) -> Option<VamanaSnapshot> {
    let key = snapshot_key(namespace, model);
    let sql = rt.sql();
    let mut reader = sql.reader().await.ok()?;
    let rows = reader
        .query_all(SqlStatement {
            sql: ::khive_runtime::sql!("knowledge_legacy_snapshot_load").into(),
            params: vec![SqlValue::Text(key), SqlValue::Text("vamana".into())],
            label: None,
        })
        .await
        .ok()?;

    let row = rows.into_iter().next()?;
    let blob = match row.get("snapshot")? {
        SqlValue::Blob(b) => b.clone(),
        _ => return None,
    };
    serde_json::from_slice::<VamanaSnapshot>(&blob).ok()
}

/// Get the corpus fingerprint by querying the vector store.
pub(crate) async fn compute_fingerprint(
    rt: &KhiveRuntime,
    token: &NamespaceToken,
    model: &str,
) -> Option<CorpusFingerprint> {
    let store = rt.vectors_for_model(token, model).ok()?;
    let info = store.info().await.ok()?;
    Some(CorpusFingerprint {
        vector_count: info.entry_count,
        dimensions: info.dimensions as u32,
    })
}

/// Accumulate the decoded corpus without retaining owned SQL rows.
///
/// The result vectors grow amortized because a consumer does not know the row
/// count. This avoids a corpus-sized raw-row collection; it is not a bound on
/// the decoded corpus or on buffering inside the database engine.
struct CorpusRows {
    dims: usize,
    saw_row: bool,
    scan_watermark: u64,
    id_map: Vec<Uuid>,
    flat: Vec<f32>,
}

impl CorpusRows {
    fn new(dims: usize) -> Self {
        Self {
            dims,
            saw_row: false,
            scan_watermark: 0,
            id_map: Vec::new(),
            flat: Vec::new(),
        }
    }

    fn finish(self) -> Option<(Vec<f32>, Vec<Uuid>, u64)> {
        if self.id_map.is_empty() {
            None
        } else {
            Some((self.flat, self.id_map, self.scan_watermark))
        }
    }
}

impl khive_storage::SqlRowConsumer for CorpusRows {
    fn push_row(&mut self, row: khive_storage::SqlRow) -> khive_storage::types::StorageResult<()> {
        // Capture the first raw row, even when that row is later skipped.
        if !self.saw_row {
            self.saw_row = true;
            self.scan_watermark = row
                .i64_or_none("log_s")
                .and_then(|value| u64::try_from(value).ok())
                .unwrap_or(0);
        }
        let id_str = match row.get("subject_id") {
            Some(SqlValue::Text(s)) => s.as_str(),
            _ => return Ok(()),
        };
        let uuid = match Uuid::parse_str(id_str) {
            Ok(id) => id,
            Err(_) => return Ok(()),
        };
        let bytes = match row.get("embedding") {
            Some(SqlValue::Blob(b)) => b.as_slice(),
            _ => return Ok(()),
        };
        if bytes.len() != self.dims * 4 {
            return Ok(());
        }
        let Ok(vec) = khive_storage::decode_f32_native(bytes) else {
            return Ok(());
        };
        self.id_map.push(uuid);
        self.flat.extend_from_slice(&vec);
        Ok(())
    }

    fn into_any(self: Box<Self>) -> Box<dyn std::any::Any + Send> {
        self
    }
}

async fn scan_corpus_rows(
    reader: &mut dyn khive_storage::SqlReader,
    statement: khive_storage::SqlStatement,
    dims: usize,
) -> khive_storage::types::StorageResult<Option<(Vec<f32>, Vec<Uuid>, u64)>> {
    // Unsupported is an explicit refusal; do not fall back to query_all.
    let consumer = reader
        .query_consume(statement, Box::new(CorpusRows::new(dims)))
        .await?;
    let corpus = consumer.into_any().downcast::<CorpusRows>().map_err(|_| {
        khive_storage::StorageError::Internal("unexpected corpus SQL consumer".into())
    })?;
    Ok(corpus.finish())
}

fn map_corpus_scan_error(error: khive_storage::StorageError) -> RuntimeError {
    RuntimeError::Internal(error.to_string())
}

#[cfg(test)]
#[path = "../vamana_corpus_scan_consumer_tests.rs"]
mod corpus_scan_consumer_tests;

/// Scan the sqlite-vec corpus for `model` and return raw (un-normalized) flat
/// vectors alongside the ordered UUID id-map.
///
/// Rows are fetched `ORDER BY subject_id` so the mapping is deterministic.
/// Returns `Ok(None)` only when a scan COMPLETED and found nothing: the table
/// is empty or no rows pass the byte-length validity check. Store-opening
/// failures propagate as `Err` — `Ok(None)` feeds the terminal unavailable
/// marker (issue #1026), so an operational error must never masquerade as a
/// verified empty corpus. The caller derives `dims` as
/// `flat.len() / id_map.len()`.
pub(super) async fn scan_corpus_raw(
    rt: &KhiveRuntime,
    token: &NamespaceToken,
    model: &str,
) -> Result<Option<(Vec<f32>, Vec<Uuid>, u64)>, RuntimeError> {
    let store = rt
        .vectors_for_model(token, model)
        .map_err(|e| RuntimeError::Internal(e.to_string()))?;

    let info = store
        .info()
        .await
        .map_err(|e| RuntimeError::Internal(e.to_string()))?;
    let count = info.entry_count;
    let dims = info.dimensions;

    if count == 0 || dims == 0 {
        return Ok(None);
    }

    let ns = token.namespace().as_str().to_owned();
    let model_key = sanitize_model_key(model);
    let table_name = format!("vec_{model_key}");
    let model_str = model.to_owned();

    let sql = rt.sql();
    let mut reader = sql
        .reader()
        .await
        .map_err(|e| RuntimeError::Internal(e.to_string()))?;

    // The global AUTOINCREMENT high-water evaluates inside the SAME statement
    // — and therefore the same SQLite read snapshot — as the corpus rows.
    // Unlike MAX over retained rows it survives compaction, so an
    // authoritative recovery checkpoint never regresses below the untrusted
    // segment it replaces. Future writes have a strictly larger global seq;
    // rows from sibling scopes below S are irrelevant to this corpus.
    scan_corpus_rows(
        reader.as_mut(),
        knowledge_corpus(&ns).corpus_scan(&table_name, &model_str, "vamana_corpus_scan"),
        dims,
    )
    .await
    .map_err(map_corpus_scan_error)
}

/// Scan the sqlite-vec table and build a fresh `AnnBridge`.
///
/// Returns `None` when there are no vectors or the model is not configured.
pub(crate) async fn load_and_build_from_vector_store(
    rt: &KhiveRuntime,
    token: &NamespaceToken,
    model: &str,
) -> Result<Option<AnnBridge>, RuntimeError> {
    let Some((flat, id_map, scan_watermark)) = scan_corpus_raw(rt, token, model).await? else {
        return Ok(None);
    };
    let dims = flat.len() / id_map.len();
    // This async task builds inline. The ignored measure_inline_ann_build_tick_gap
    // (docs/benchmarks.md) measured scan/load + build at ~2 s for 4,096 rows
    // on 2 workers: the 10 ms ticker's largest gap was 10.37 ms versus a
    // 10.47 ms baseline, with no extra observed stall. A single worker would
    // be occupied during the inline CPU build; revisit if the runtime or
    // workload changes.
    AnnBridge::build(flat, dims, id_map)
        .map(|mut bridge| {
            bridge.set_applied_seq(scan_watermark);
            Some(bridge)
        })
        .map_err(RuntimeError::Internal)
}

/// Delete all Vamana snapshots for `namespace` from `retrieval_snapshots`.
///
/// Called after any vector-corpus mutation to guarantee `ensure_ann_for_model` cannot
/// load a snapshot that no longer matches the live corpus.  Best-effort: if
/// the `retrieval_snapshots` table doesn't exist yet, the call is a no-op.
pub(crate) async fn invalidate_snapshot(rt: &KhiveRuntime, namespace: &str) {
    let sql = rt.sql();
    let mut w = match sql.writer().await {
        Ok(w) => w,
        Err(e) => {
            tracing::warn!(error = %e, "failed to open writer for Vamana snapshot invalidation");
            return;
        }
    };
    match invalidate_legacy_vamana_snapshots(w.as_mut(), namespace, "invalidate_vamana_snapshot")
        .await
    {
        Ok(_) => {}
        Err(e) if e.to_string().contains("no such table") => {}
        Err(e) => {
            tracing::warn!(error = %e, "failed to invalidate Vamana snapshot");
        }
    }
}