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                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        // The holder may have disappeared while preparation was in flight.
343        // In that case take the normal create path, including source checking.
344        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                // The target can disappear after preparation while another
395                // writer publishes this key. Reconcile only this labeled
396                // endpoint guard; all other failures retain their old path.
397                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                // Admission is cached after the first successful cutover check,
412                // so a receipt store that broke since then surfaces here.
413                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        // This is the exact boundary in the replay path: holder lookup has
480        // completed, but its joined receipt/epoch read has not started.
481        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        // The post-commit caller retains its existing uncertainty semantics.
515        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                // Model a damaged epoch value as well as valid but incomplete
536                // provenance. Restore constraint checks before reading it.
537                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}