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 #[cfg(test)]
329 crate::keyed_memory_tests::checkpoint(
330 token.namespace().as_str(),
331 crate::keyed_memory_tests::MISSING_SOURCE_CHECKPOINT,
332 true,
333 )
334 .await;
335 holder_seen = resolve_holder(runtime, token, spec.key).await?.is_some();
336 if holder_seen {
337 prepare_keyed_memory(runtime, token, &spec, None)
338 .await
339 .map_err(NoteCreatePrepareError::into_runtime)?
340 } else {
341 return Err(error.into_runtime());
342 }
343 } else {
344 return Err(error.into_runtime());
345 }
346 }
347 };
348 if holder_seen {
349 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
352 if holder.content != spec.content {
353 return Err(idempotency_conflict(spec.key, &holder));
354 }
355 let fences = classified_visibility_receipt(runtime, token, holder.id, true).await?;
356 return Ok((holder, None, true, fences, candidate.0.embedding_truncation));
357 }
358 candidate = prepare_keyed_memory(runtime, token, &spec, spec.source_id)
359 .await
360 .map_err(NoteCreatePrepareError::into_runtime)?;
361 }
362 let (mut prepared, annotation_ids) = candidate;
363 let mut note = prepared.notes.remove(0);
364 let edge_id = annotation_ids.first().copied();
365
366 for _attempt in 0..2 {
367 #[cfg(test)]
368 crate::keyed_memory_tests::checkpoint(token.namespace().as_str(), _attempt, false).await;
369 match run_atomic_unit(runtime.sql().as_ref(), prepared.plans.clone()).await {
370 Ok(AtomicRunOutcome::Committed { .. }) => {
371 note.key = Some(spec.key.to_owned());
372 note.version = 2;
373 let fences = classified_visibility_receipt(runtime, token, note.id, false).await?;
374 return Ok((note, edge_id, false, fences, prepared.embedding_truncation));
375 }
376 Ok(AtomicRunOutcome::RolledBack {
377 failure:
378 AtomicOpFailure::GuardFailed {
379 statement_label,
380 observed: 0,
381 ..
382 },
383 ..
384 }) if statement_label.as_deref() == Some(KEY_CLAIM) => {
385 #[cfg(test)]
386 crate::keyed_memory_tests::checkpoint(token.namespace().as_str(), _attempt, true)
387 .await;
388 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
389 if holder.content == spec.content {
390 let fences =
391 classified_visibility_receipt(runtime, token, holder.id, true).await?;
392 return Ok((holder, None, true, fences, prepared.embedding_truncation));
393 }
394 return Err(idempotency_conflict(spec.key, &holder));
395 }
396 }
397 Ok(AtomicRunOutcome::RolledBack {
398 failed_op_index,
399 failure,
400 }) => {
401 if matches!(
405 &failure,
406 AtomicOpFailure::GuardFailed { statement_label, observed: 0, .. }
407 if statement_label.as_deref() == Some(KEYED_ANNOTATION_ENDPOINT)
408 ) {
409 if let Some(holder) = resolve_holder(runtime, token, spec.key).await? {
410 if holder.content != spec.content {
411 return Err(idempotency_conflict(spec.key, &holder));
412 }
413 let fences =
414 classified_visibility_receipt(runtime, token, holder.id, true).await?;
415 return Ok((holder, None, true, fences, prepared.embedding_truncation));
416 }
417 }
418 runtime.recheck_visibility_cutover()?;
421 return Err(RuntimeError::Internal(format!(
422 "atomic memory write rolled back at op {failed_op_index}: {failure:?}"
423 )));
424 }
425 Err(error) => return Err(RuntimeError::Storage(error.0)),
426 }
427 }
428 Err(
429 KhiveError::unavailable("memory key holder disappeared during reconciliation")
430 .with_details(Details::new_owned([
431 ("reason", "key_holder_unresolved".into()),
432 ("key", spec.key.to_owned()),
433 ]))
434 .into(),
435 )
436}
437
438#[cfg(test)]
439mod receipt_read_tests {
440 use super::*;
441 use crate::DomainDisposition;
442
443 const KEY: &str = "receipt-race-key";
444 const CONTENT: &str = "private receipt race content";
445
446 async fn captured_holder() -> (KhiveRuntime, NamespaceToken, Note) {
447 let runtime = KhiveRuntime::memory().unwrap();
448 runtime.install_kind_registry(vec![], vec!["memory".into()]);
449 let token = runtime
450 .authorize(khive_types::Namespace::parse("receipt-read-race").unwrap())
451 .unwrap();
452 let (note, _, replayed, fences) = create_keyed_memory_with_receipt(
453 &runtime,
454 &token,
455 KeyedMemorySpec {
456 content: CONTENT,
457 key: KEY,
458 salience: 0.7,
459 decay_factor: 0.95,
460 properties: serde_json::json!({}),
461 source_id: None,
462 embedding_model: None,
463 },
464 )
465 .await
466 .unwrap();
467 assert!(!replayed);
468 assert!(fences.is_empty());
469 let holder = resolve_holder(&runtime, &token, KEY)
470 .await
471 .unwrap()
472 .unwrap();
473 assert_eq!(holder, note);
474 assert!(
475 classified_visibility_receipt(&runtime, &token, holder.id, true)
476 .await
477 .unwrap()
478 .is_empty()
479 );
480 (runtime, token, holder)
481 }
482
483 #[tokio::test]
484 async fn replay_receipt_reports_missing_after_captured_holder_is_hard_deleted() {
485 let (runtime, token, holder) = captured_holder().await;
486 assert!(runtime.delete_note(&token, holder.id, true).await.unwrap());
489 assert!(runtime
490 .notes(&token)
491 .unwrap()
492 .get_note_including_deleted(holder.id)
493 .await
494 .unwrap()
495 .is_none());
496 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
497 .await
498 .unwrap_err();
499 assert!(
500 matches!(&error, RuntimeError::Khive(e) if e.kind() == khive_types::ErrorKind::NotFound)
501 );
502 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
503 assert_eq!(value["kind"], "not_found");
504 assert_eq!(value["details"]["reason"], "keyed_replay_holder_missing");
505 assert_eq!(value["domain_disposition"], "not_committed");
506 assert!(value.get("retryable").is_none());
507 let encoded = value.to_string();
508 let id = holder.id.to_string();
509 for private in [KEY, CONTENT, id.as_str()] {
510 assert!(!encoded.contains(private));
511 }
512 assert!(memory_visibility_receipt(&runtime, &token, holder.id)
513 .await
514 .unwrap()
515 .is_none());
516 assert!(resolve_holder(&runtime, &token, KEY)
517 .await
518 .unwrap()
519 .is_none());
520
521 let error = classified_visibility_receipt(&runtime, &token, holder.id, false)
523 .await
524 .unwrap_err();
525 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
526 assert_eq!(value["details"]["reason"], "receipt_epoch_unknown");
527 assert_eq!(value["domain_disposition"], "unknown");
528 }
529
530 #[tokio::test]
531 async fn present_holder_with_missing_or_invalid_epoch_is_not_missing() {
532 for mutation in [
533 "DELETE FROM memory_visibility_epochs WHERE note_id = ?1",
534 "UPDATE memory_visibility_epochs SET epoch = 'unknown' WHERE note_id = ?1",
535 "UPDATE memory_visibility_epochs SET epoch = 'malformed' WHERE note_id = ?1",
536 "UPDATE memory_visibility_epochs SET epoch = 'legacy' WHERE note_id = ?1",
537 "UPDATE memory_visibility_epochs SET namespace = 'foreign-private-namespace' WHERE note_id = ?1",
538 "UPDATE notes SET namespace = 'foreign-private-namespace' WHERE id = ?1",
539 ] {
540 let (runtime, token, holder) = captured_holder().await;
541 {
542 let writer = runtime.backend().pool().try_writer().unwrap();
545 writer.autocommit(|conn| {
546 conn
547 .pragma_update(None, "ignore_check_constraints", true)
548 .unwrap();
549 conn.execute(mutation, [holder.id.to_string()]).unwrap();
550 conn
551 .pragma_update(None, "ignore_check_constraints", false)
552 .unwrap();
553 Ok(())
554 }).unwrap();
555 }
556 assert!(runtime
557 .notes(&token)
558 .unwrap()
559 .get_note_including_deleted(holder.id)
560 .await
561 .unwrap()
562 .is_some());
563 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
564 .await
565 .unwrap_err();
566 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
567 assert_eq!(value["details"]["reason"], "receipt_epoch_unknown");
568 assert_eq!(value["details"]["memory_id"], holder.id.to_string());
569 assert_eq!(value["domain_disposition"], "not_committed");
570 assert_eq!(value["retryable"], false);
571 for private in [KEY, CONTENT, "foreign-private-namespace"] {
572 assert!(!value.to_string().contains(private));
573 }
574 }
575 }
576
577 #[tokio::test]
578 async fn unreadable_note_store_is_unavailable_not_missing() {
579 let (runtime, token, holder) = captured_holder().await;
580 runtime
581 .sql()
582 .writer()
583 .await
584 .unwrap()
585 .execute(SqlStatement {
586 sql: "ALTER TABLE notes RENAME TO private_unreadable_notes".into(),
587 params: vec![],
588 label: Some("receipt-unreadable-note-control".into()),
589 })
590 .await
591 .unwrap();
592 let error = classified_visibility_receipt(&runtime, &token, holder.id, true)
593 .await
594 .unwrap_err();
595 let value = crate::error_projection::runtime_error_value(error, DomainDisposition::Unknown);
596 assert_eq!(value["details"]["reason"], "receipt_store_unavailable");
597 assert_eq!(value["details"]["memory_id"], holder.id.to_string());
598 assert_eq!(value["domain_disposition"], "unknown");
599 assert_eq!(value["retryable"], true);
600 for private in [KEY, CONTENT, "private_unreadable_notes"] {
601 assert!(!value.to_string().contains(private));
602 }
603 }
604}