1use khive_storage::note::Note;
4use khive_storage::{SqlStatement, SqlValue};
5use khive_types::{Details, KhiveError};
6use serde_json::Value;
7use uuid::Uuid;
8
9use crate::atomic_message::{AtomicNoteOptions, AtomicNoteSpec, PreparedAtomicNotes};
10use crate::atomic_runner::{run_atomic_unit, AtomicOpFailure, AtomicRunOutcome};
11use crate::note_create::{
12 prepare_note_create_classified, KeyPublication, NoteCreatePrepareError,
13 KEYED_ANNOTATION_ENDPOINT, KEY_CLAIM,
14};
15use crate::{KhiveRuntime, NamespaceToken, RuntimeError, RuntimeResult};
16
17pub struct KeyedMemorySpec<'a> {
18 pub content: &'a str,
19 pub key: &'a str,
20 pub salience: f64,
21 pub decay_factor: f64,
22 pub properties: Value,
23 pub source_id: Option<Uuid>,
24 pub embedding_model: Option<&'a str>,
25}
26
27pub fn validate_memory_key(key: &str) -> RuntimeResult<()> {
28 crate::note_validation::validate_key(
29 key,
30 "key must be at most 512 UTF-8 bytes and must not contain U+0000",
31 )
32}
33
34fn idempotency_conflict(key: &str, existing: &Note) -> RuntimeError {
35 KhiveError::conflict(format!(
36 "idempotency_key_conflict: key {key:?} already exists; stored content differs (existing memory {})",
37 existing.id
38 ))
39 .with_details(Details::new_owned([
40 ("reason", "idempotency_key_conflict".into()),
41 ("key", key.to_owned()),
42 ("existing_id", existing.id.to_string()),
43 ]))
44 .into()
45}
46
47async fn resolve_holder(
48 runtime: &KhiveRuntime,
49 token: &NamespaceToken,
50 key: &str,
51) -> RuntimeResult<Option<Note>> {
52 let mut matches = runtime
53 .notes(token)?
54 .get_live_notes_by_key(token.namespace().as_str(), key, Some("memory"))
55 .await?;
56 match matches.len() {
57 0 => Ok(None),
58 1 => Ok(matches.pop()),
59 _ => Err(RuntimeError::Internal(
60 "memory key lookup returned multiple live holders".into(),
61 )),
62 }
63}
64
65struct VisibilityReceiptState {
66 note_present: bool,
67 epoch: Option<String>,
68 receipt_present: bool,
69 fences: Option<Vec<(String, u64)>>,
70}
71
72async fn visibility_receipt_state(
76 runtime: &KhiveRuntime,
77 token: &NamespaceToken,
78 note_id: Uuid,
79) -> RuntimeResult<VisibilityReceiptState> {
80 let unavailable = || {
81 crate::visibility_receipts::receipt_failure(
82 "receipt_store_unavailable",
83 Some(note_id),
84 false,
85 )
86 };
87 runtime
88 .require_visibility_cutover()
89 .map_err(|_| unavailable())?;
90 let mut reader = runtime.sql().reader().await.map_err(|_| unavailable())?;
91 let rows = reader
92 .query_all(SqlStatement {
93 sql: "SELECT n.kind AS note_kind, n.namespace AS note_namespace, \
94 e.namespace AS epoch_namespace, e.epoch, \
95 r.note_id AS receipt_id, r.namespace AS receipt_namespace, r.model_count, \
96 f.namespace AS fence_namespace, f.model, f.ann_write_log_seq \
97 FROM notes n LEFT JOIN memory_visibility_epochs e ON e.note_id = n.id \
98 LEFT JOIN memory_visibility_receipts r ON r.note_id = n.id \
99 LEFT JOIN memory_visibility_fences f ON f.note_id = n.id \
100 WHERE n.id = ?1 ORDER BY r.namespace, f.namespace, f.model"
101 .into(),
102 params: vec![SqlValue::Text(note_id.to_string())],
103 label: Some("memory-visibility-receipt-read".into()),
104 })
105 .await
106 .map_err(|_| unavailable())?;
107 let mut state = VisibilityReceiptState {
108 note_present: !rows.is_empty(),
109 epoch: None,
110 receipt_present: false,
111 fences: None,
112 };
113 let Some(first) = rows.first() else {
114 return Ok(state);
115 };
116 let namespace = token.namespace().as_str();
117 let text = |value: Option<&SqlValue>, expected: &str| match value {
118 Some(SqlValue::Text(actual)) => actual == expected,
119 _ => false,
120 };
121 let identity_matches = text(first.get("note_kind"), "memory")
122 && text(first.get("note_namespace"), namespace)
123 && text(first.get("epoch_namespace"), namespace);
124 if identity_matches {
125 if let Some(SqlValue::Text(epoch)) = first.get("epoch") {
126 state.epoch = Some(epoch.clone());
127 }
128 }
129 state.receipt_present = rows
130 .iter()
131 .any(|row| matches!(row.get("receipt_id"), Some(SqlValue::Text(_))));
132 let expected_count = match first.get("model_count") {
133 Some(SqlValue::Integer(count)) if *count >= 0 => usize::try_from(*count).ok(),
134 _ => None,
135 };
136 let mut valid = text(first.get("note_kind"), "memory")
137 && text(first.get("note_namespace"), namespace)
138 && state.receipt_present
139 && expected_count.is_some();
140 let mut fences = std::collections::BTreeMap::new();
141 for row in &rows {
142 if (matches!(row.get("receipt_id"), Some(SqlValue::Text(_)))
143 && !text(row.get("receipt_namespace"), namespace))
144 || matches!(row.get("fence_namespace"), Some(SqlValue::Text(ns))
145 if ns != namespace || !text(row.get("receipt_namespace"), ns))
146 {
147 state.epoch = None;
148 }
149 valid &= text(row.get("receipt_namespace"), namespace)
150 && matches!(row.get("model_count"), Some(SqlValue::Integer(count))
151 if usize::try_from(*count).ok() == expected_count);
152 match (
153 row.get("fence_namespace"),
154 row.get("model"),
155 row.get("ann_write_log_seq"),
156 ) {
157 (
158 Some(SqlValue::Text(ns)),
159 Some(SqlValue::Text(model)),
160 Some(SqlValue::Integer(seq)),
161 ) if ns == namespace && !model.is_empty() && *seq > 0 => {
162 valid &= fences.insert(model.clone(), *seq as u64).is_none();
163 }
164 (
165 Some(SqlValue::Null) | None,
166 Some(SqlValue::Null) | None,
167 Some(SqlValue::Null) | None,
168 ) => {}
169 _ => valid = false,
170 }
171 }
172 if valid && expected_count == Some(fences.len()) {
173 state.fences = Some(fences.into_iter().collect());
174 }
175 Ok(state)
176}
177
178pub async fn memory_visibility_receipt(
181 runtime: &KhiveRuntime,
182 token: &NamespaceToken,
183 note_id: Uuid,
184) -> RuntimeResult<Option<Vec<(String, u64)>>> {
185 Ok(visibility_receipt_state(runtime, token, note_id)
186 .await?
187 .fences)
188}
189
190async fn classified_visibility_receipt(
191 runtime: &KhiveRuntime,
192 token: &NamespaceToken,
193 note_id: Uuid,
194 replay: bool,
195) -> RuntimeResult<Vec<(String, u64)>> {
196 let state = visibility_receipt_state(runtime, token, note_id).await?;
197 if replay && !state.note_present {
198 return Err(KhiveError::not_found("memory", "keyed replay holder")
201 .with_details(Details::new_owned([(
202 "reason",
203 "keyed_replay_holder_missing".into(),
204 )]))
205 .into());
206 }
207 let reason = match state.epoch.as_deref() {
208 Some("modern") => {
209 if let Some(fences) = state.fences {
210 return Ok(fences);
211 }
212 "receipt_temporarily_unavailable"
213 }
214 Some("legacy") if !state.receipt_present => "legacy_receipt_absent",
215 _ => "receipt_epoch_unknown",
216 };
217 Err(crate::visibility_receipts::receipt_failure(
218 reason,
219 Some(note_id),
220 replay,
221 ))
222}
223
224pub async fn create_keyed_memory(
225 runtime: &KhiveRuntime,
226 token: &NamespaceToken,
227 spec: KeyedMemorySpec<'_>,
228) -> RuntimeResult<(Note, Option<Uuid>, bool)> {
229 let (note, edge_id, replayed, _) =
230 create_keyed_memory_with_report(runtime, token, spec).await?;
231 Ok((note, edge_id, replayed))
232}
233
234pub async fn create_keyed_memory_with_report(
238 runtime: &KhiveRuntime,
239 token: &NamespaceToken,
240 spec: KeyedMemorySpec<'_>,
241) -> RuntimeResult<(
242 Note,
243 Option<Uuid>,
244 bool,
245 crate::retrieval::EmbeddingTruncationReport,
246)> {
247 let (note, edge_id, replayed, _, report) =
248 create_keyed_memory_with_receipt_and_report(runtime, token, spec).await?;
249 Ok((note, edge_id, replayed, report))
250}
251
252pub async fn create_keyed_memory_with_receipt(
255 runtime: &KhiveRuntime,
256 token: &NamespaceToken,
257 spec: KeyedMemorySpec<'_>,
258) -> RuntimeResult<(Note, Option<Uuid>, bool, Vec<(String, u64)>)> {
259 let (note, edge_id, replayed, fences, _) =
260 create_keyed_memory_with_receipt_and_report(runtime, token, spec).await?;
261 Ok((note, edge_id, replayed, fences))
262}
263
264async fn prepare_keyed_memory(
265 runtime: &KhiveRuntime,
266 token: &NamespaceToken,
267 spec: &KeyedMemorySpec<'_>,
268 source_id: Option<Uuid>,
269) -> Result<(PreparedAtomicNotes, Vec<Uuid>), NoteCreatePrepareError> {
270 prepare_note_create_classified(
271 runtime,
272 AtomicNoteSpec {
273 token,
274 id: None,
275 kind: "memory",
276 name: None,
277 content: spec.content,
278 properties: Some(spec.properties.clone()),
279 },
280 AtomicNoteOptions {
281 salience: Some(spec.salience),
282 decay_factor: Some(spec.decay_factor),
283 embedding_model: spec.embedding_model,
284 key: Some(spec.key),
285 memory_visibility_receipt: true,
286 ..Default::default()
287 },
288 &source_id.into_iter().collect::<Vec<_>>(),
289 KeyPublication::AfterDependents,
290 )
291 .await
292}
293
294pub async fn create_keyed_memory_with_receipt_and_report(
298 runtime: &KhiveRuntime,
299 token: &NamespaceToken,
300 spec: KeyedMemorySpec<'_>,
301) -> RuntimeResult<(
302 Note,
303 Option<Uuid>,
304 bool,
305 Vec<(String, u64)>,
306 crate::retrieval::EmbeddingTruncationReport,
307)> {
308 validate_memory_key(spec.key)?;
309 crate::secret_gate::check_at(spec.key, "note", "key")?;
310 if spec.content.trim().is_empty() {
311 return Err(RuntimeError::InvalidInput(
312 "content must not be empty".into(),
313 ));
314 }
315 let mut holder_seen = resolve_holder(runtime, token, spec.key).await?.is_some();
319 let source_to_prepare = if holder_seen { None } else { spec.source_id };
320 let mut candidate = match prepare_keyed_memory(runtime, token, &spec, source_to_prepare).await {
321 Ok(candidate) => candidate,
322 Err(error) => {
323 let missing_source = matches!(error, NoteCreatePrepareError::MissingAnnotation(_));
327 if !holder_seen && missing_source {
328 holder_seen = resolve_holder(runtime, token, spec.key).await?.is_some();
329 if holder_seen {
330 prepare_keyed_memory(runtime, token, &spec, None)
331 .await
332 .map_err(NoteCreatePrepareError::into_runtime)?
333 } else {
334 return Err(error.into_runtime());
335 }
336 } else {
337 return Err(error.into_runtime());
338 }
339 }
340 };
341 if holder_seen {
342 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
345 if holder.content != spec.content {
346 return Err(idempotency_conflict(spec.key, &holder));
347 }
348 let fences = classified_visibility_receipt(runtime, token, holder.id, true).await?;
349 return Ok((holder, None, true, fences, candidate.0.embedding_truncation));
350 }
351 candidate = prepare_keyed_memory(runtime, token, &spec, spec.source_id)
352 .await
353 .map_err(NoteCreatePrepareError::into_runtime)?;
354 }
355 let (mut prepared, annotation_ids) = candidate;
356 let mut note = prepared.notes.remove(0);
357 let edge_id = annotation_ids.first().copied();
358
359 for _attempt in 0..2 {
360 #[cfg(test)]
361 crate::keyed_memory_tests::checkpoint(token.namespace().as_str(), _attempt, false).await;
362 match run_atomic_unit(runtime.sql().as_ref(), prepared.plans.clone()).await {
363 Ok(AtomicRunOutcome::Committed { .. }) => {
364 note.key = Some(spec.key.to_owned());
365 note.version = 2;
366 let fences = classified_visibility_receipt(runtime, token, note.id, false).await?;
367 return Ok((note, edge_id, false, fences, prepared.embedding_truncation));
368 }
369 Ok(AtomicRunOutcome::RolledBack {
370 failure:
371 AtomicOpFailure::GuardFailed {
372 statement_label,
373 observed: 0,
374 ..
375 },
376 ..
377 }) if statement_label.as_deref() == Some(KEY_CLAIM) => {
378 #[cfg(test)]
379 crate::keyed_memory_tests::checkpoint(token.namespace().as_str(), _attempt, true)
380 .await;
381 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
382 if holder.content == spec.content {
383 let fences =
384 classified_visibility_receipt(runtime, token, holder.id, true).await?;
385 return Ok((holder, None, true, fences, prepared.embedding_truncation));
386 }
387 return Err(idempotency_conflict(spec.key, &holder));
388 }
389 }
390 Ok(AtomicRunOutcome::RolledBack {
391 failed_op_index,
392 failure,
393 }) => {
394 if matches!(
398 &failure,
399 AtomicOpFailure::GuardFailed { statement_label, observed: 0, .. }
400 if statement_label.as_deref() == Some(KEYED_ANNOTATION_ENDPOINT)
401 ) {
402 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
403 if holder.content != spec.content {
404 return Err(idempotency_conflict(spec.key, &holder));
405 }
406 let fences =
407 classified_visibility_receipt(runtime, token, holder.id, true).await?;
408 return Ok((holder, None, true, fences, prepared.embedding_truncation));
409 }
410 }
411 runtime.recheck_visibility_cutover()?;
414 return Err(RuntimeError::Internal(format!(
415 "atomic memory write rolled back at op {failed_op_index}: {failure:?}"
416 )));
417 }
418 Err(error) => return Err(RuntimeError::Storage(error.0)),
419 }
420 }
421 Err(
422 KhiveError::unavailable("memory key holder disappeared during reconciliation")
423 .with_details(Details::new_owned([
424 ("reason", "key_holder_unresolved".into()),
425 ("key", spec.key.to_owned()),
426 ]))
427 .into(),
428 )
429}
430
431#[cfg(test)]
432mod receipt_read_tests {
433 use super::*;
434 use crate::DomainDisposition;
435
436 const KEY: &str = "receipt-race-key";
437 const CONTENT: &str = "private receipt race content";
438
439 async fn captured_holder() -> (KhiveRuntime, NamespaceToken, Note) {
440 let runtime = KhiveRuntime::memory().unwrap();
441 runtime.install_kind_registry(vec![], vec!["memory".into()]);
442 let token = runtime
443 .authorize(khive_types::Namespace::parse("receipt-read-race").unwrap())
444 .unwrap();
445 let (note, _, replayed, fences) = create_keyed_memory_with_receipt(
446 &runtime,
447 &token,
448 KeyedMemorySpec {
449 content: CONTENT,
450 key: KEY,
451 salience: 0.7,
452 decay_factor: 0.95,
453 properties: serde_json::json!({}),
454 source_id: None,
455 embedding_model: None,
456 },
457 )
458 .await
459 .unwrap();
460 assert!(!replayed);
461 assert!(fences.is_empty());
462 let holder = resolve_holder(&runtime, &token, KEY)
463 .await
464 .unwrap()
465 .unwrap();
466 assert_eq!(holder, note);
467 assert!(
468 classified_visibility_receipt(&runtime, &token, holder.id, true)
469 .await
470 .unwrap()
471 .is_empty()
472 );
473 (runtime, token, holder)
474 }
475
476 #[tokio::test]
477 async fn replay_receipt_reports_missing_after_captured_holder_is_hard_deleted() {
478 let (runtime, token, holder) = captured_holder().await;
479 assert!(runtime.delete_note(&token, holder.id, true).await.unwrap());
482 assert!(runtime
483 .notes(&token)
484 .unwrap()
485 .get_note_including_deleted(holder.id)
486 .await
487 .unwrap()
488 .is_none());
489 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
490 .await
491 .unwrap_err();
492 assert!(
493 matches!(&error, RuntimeError::Khive(e) if e.kind() == khive_types::ErrorKind::NotFound)
494 );
495 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
496 assert_eq!(value["kind"], "not_found");
497 assert_eq!(value["details"]["reason"], "keyed_replay_holder_missing");
498 assert_eq!(value["domain_disposition"], "not_committed");
499 assert!(value.get("retryable").is_none());
500 let encoded = value.to_string();
501 let id = holder.id.to_string();
502 for private in [KEY, CONTENT, id.as_str()] {
503 assert!(!encoded.contains(private));
504 }
505 assert!(memory_visibility_receipt(&runtime, &token, holder.id)
506 .await
507 .unwrap()
508 .is_none());
509 assert!(resolve_holder(&runtime, &token, KEY)
510 .await
511 .unwrap()
512 .is_none());
513
514 let error = classified_visibility_receipt(&runtime, &token, holder.id, false)
516 .await
517 .unwrap_err();
518 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
519 assert_eq!(value["details"]["reason"], "receipt_epoch_unknown");
520 assert_eq!(value["domain_disposition"], "unknown");
521 }
522
523 #[tokio::test]
524 async fn present_holder_with_missing_or_invalid_epoch_is_not_missing() {
525 for mutation in [
526 "DELETE FROM memory_visibility_epochs WHERE note_id = ?1",
527 "UPDATE memory_visibility_epochs SET epoch = 'unknown' WHERE note_id = ?1",
528 "UPDATE memory_visibility_epochs SET epoch = 'malformed' WHERE note_id = ?1",
529 "UPDATE memory_visibility_epochs SET epoch = 'legacy' WHERE note_id = ?1",
530 "UPDATE memory_visibility_epochs SET namespace = 'foreign-private-namespace' WHERE note_id = ?1",
531 "UPDATE notes SET namespace = 'foreign-private-namespace' WHERE id = ?1",
532 ] {
533 let (runtime, token, holder) = captured_holder().await;
534 {
535 let writer = runtime.backend().pool().try_writer().unwrap();
538 writer.autocommit(|conn| {
539 conn
540 .pragma_update(None, "ignore_check_constraints", true)
541 .unwrap();
542 conn.execute(mutation, [holder.id.to_string()]).unwrap();
543 conn
544 .pragma_update(None, "ignore_check_constraints", false)
545 .unwrap();
546 Ok(())
547 }).unwrap();
548 }
549 assert!(runtime
550 .notes(&token)
551 .unwrap()
552 .get_note_including_deleted(holder.id)
553 .await
554 .unwrap()
555 .is_some());
556 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
557 .await
558 .unwrap_err();
559 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
560 assert_eq!(value["details"]["reason"], "receipt_epoch_unknown");
561 assert_eq!(value["details"]["memory_id"], holder.id.to_string());
562 assert_eq!(value["domain_disposition"], "not_committed");
563 assert_eq!(value["retryable"], false);
564 for private in [KEY, CONTENT, "foreign-private-namespace"] {
565 assert!(!value.to_string().contains(private));
566 }
567 }
568 }
569
570 #[tokio::test]
571 async fn unreadable_note_store_is_unavailable_not_missing() {
572 let (runtime, token, holder) = captured_holder().await;
573 runtime
574 .sql()
575 .writer()
576 .await
577 .unwrap()
578 .execute(SqlStatement {
579 sql: "ALTER TABLE notes RENAME TO private_unreadable_notes".into(),
580 params: vec![],
581 label: Some("receipt-unreadable-note-control".into()),
582 })
583 .await
584 .unwrap();
585 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
586 .await
587 .unwrap_err();
588 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
589 assert_eq!(value["details"]["reason"], "receipt_store_unavailable");
590 assert_eq!(value["details"]["memory_id"], holder.id.to_string());
591 assert_eq!(value["domain_disposition"], "unknown");
592 assert_eq!(value["retryable"], true);
593 for private in [KEY, CONTENT, "private_unreadable_notes"] {
594 assert!(!value.to_string().contains(private));
595 }
596 }
597}