Skip to main content

khive_runtime/
keyed_memory.rs

1//! Memory identity is published only by the final DML of its atomic create.
2
3use 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
72/// Join identity, independent provenance and original receipt in one snapshot.
73/// Joins use note identity first so a conflicting namespace cannot disappear
74/// behind a filter and masquerade as a genuinely absent receipt or marker.
75async 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
178/// Read original fences without issuing a token. Callers needing a replay token
179/// must additionally apply the independent provenance classification below.
180pub 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        // The attempt's own unit rolled back on the key claim, so this request
199        // wrote nothing; the reason carries that to the error projection.
200        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
234/// Same as [`create_keyed_memory`], also returning the embedding-input
235/// truncation report computed for this call. A replay stores nothing new but
236/// retains the report from preparing this call's identical content.
237pub 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
252/// Receipt-bearing keyed create. The original per-model receipt is retained
253/// on replay, including an explicit receipt for a write with zero models.
254pub 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
294/// Return both the original visibility receipt and the embedding-input report.
295/// Replays retain the stored fences and the report computed while preparing
296/// this call's embedding input; the report does not describe the original write.
297pub 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    // A replay's source describes no new write. Check the live holder before
316    // validating that creation-only endpoint, but still prepare the candidate
317    // so the existing content checks and embedding report remain in force.
318    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            // A winner can publish between the first lookup and source checking.
324            // Only this exact annotation-existence refusal is eligible for a
325            // recheck; unrelated NotFound errors must retain their meaning.
326            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        // The holder may have disappeared while preparation was in flight.
350        // In that case take the normal create path, including source checking.
351        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                // The target can disappear after preparation while another
402                // writer publishes this key. Reconcile only this labeled
403                // endpoint guard; all other failures retain their old path.
404                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                // Admission is cached after the first successful cutover check,
419                // so a receipt store that broke since then surfaces here.
420                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        // This is the exact boundary in the replay path: holder lookup has
487        // completed, but its joined receipt/epoch read has not started.
488        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        // The post-commit caller retains its existing uncertainty semantics.
522        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                // Model a damaged epoch value as well as valid but incomplete
543                // provenance. Restore constraint checks before reading it.
544                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}