khive_storage/note.rs
1//! Note storage capability — temporal-referential record CRUD.
2
3use async_trait::async_trait;
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6use std::collections::BTreeMap;
7use uuid::Uuid;
8
9use crate::types::{
10 BatchWriteSummary, BoundedCount, DeleteMode, Page, PageRequest, SeekCursor, SeekPage, SqlValue,
11 StorageResult,
12};
13
14/// A storage-level note record. Flat, SQL-friendly representation.
15#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
16pub struct Note {
17 pub id: Uuid,
18 pub namespace: String,
19 pub kind: String,
20 pub status: String,
21 pub name: Option<String>,
22 pub content: String,
23 pub salience: Option<f64>,
24 pub decay_factor: Option<f64>,
25 pub expires_at: Option<i64>,
26 pub properties: Option<Value>,
27 pub created_at: i64,
28 pub updated_at: i64,
29 pub deleted_at: Option<i64>,
30 /// Caller-chosen identity, unique among live notes of the same namespace and kind.
31 /// Once set, it cannot be replaced.
32 #[serde(default, skip_serializing_if = "Option::is_none")]
33 pub key: Option<String>,
34 /// Persisted revision, assigned by storage and advanced on every matched update.
35 #[serde(default = "initial_note_version")]
36 pub version: i64,
37}
38
39/// The columns needed to decide whether a note may appear in an ID-based result.
40/// Includes soft-deleted rows so the caller can apply its visibility policy.
41#[derive(Clone, Debug, PartialEq, Eq)]
42pub struct NoteVisibility {
43 pub id: Uuid,
44 pub namespace: String,
45 pub deleted_at: Option<i64>,
46}
47
48/// Maximum size of a caller-chosen note key in UTF-8 bytes.
49pub const NOTE_KEY_MAX_BYTES: usize = 512;
50
51/// Whether a note key satisfies the shared size and character constraints.
52pub fn note_key_is_valid(key: &str) -> bool {
53 key.len() <= NOTE_KEY_MAX_BYTES && !key.contains('\0')
54}
55
56/// Validate a key for a note-store operation without accessing storage.
57pub fn validate_note_key_for_store(key: &str, operation: &'static str) -> StorageResult<()> {
58 if note_key_is_valid(key) {
59 Ok(())
60 } else {
61 Err(crate::StorageError::InvalidInput {
62 capability: crate::StorageCapability::Notes,
63 operation: operation.into(),
64 message: "key must be at most 512 UTF-8 bytes and must not contain U+0000".into(),
65 })
66 }
67}
68
69/// Result of setting the key on an existing note that has none.
70#[derive(Clone, Debug, PartialEq, Eq)]
71pub enum NoteKeyAssignOutcome {
72 Assigned,
73 AlreadyKeyed { existing: String },
74 KeyTaken,
75 NotFound,
76}
77
78const fn initial_note_version() -> i64 {
79 1
80}
81
82impl Note {
83 /// Create a new note with a generated UUID and current timestamp.
84 pub fn new(
85 namespace: impl Into<String>,
86 kind: impl Into<String>,
87 content: impl Into<String>,
88 ) -> Self {
89 let now = chrono::Utc::now().timestamp_micros();
90 Self {
91 id: Uuid::new_v4(),
92 namespace: namespace.into(),
93 kind: kind.into(),
94 status: "active".to_string(),
95 name: None,
96 content: content.into(),
97 salience: None,
98 decay_factor: None,
99 expires_at: None,
100 properties: None,
101 created_at: now,
102 updated_at: now,
103 deleted_at: None,
104 key: None,
105 version: 1,
106 }
107 }
108
109 /// Set the note display name.
110 pub fn with_name(mut self, n: impl Into<String>) -> Self {
111 self.name = Some(n.into());
112 self
113 }
114
115 /// Set salience (infallible). Rejects non-finite values by returning `self`
116 /// unchanged; clamps finite values to `[0.0, 1.0]`. Prefer
117 /// [`try_with_salience`](Self::try_with_salience) at public boundaries.
118 pub fn with_salience(mut self, s: f64) -> Self {
119 if !s.is_finite() {
120 return self;
121 }
122 self.salience = Some(s.clamp(0.0, 1.0));
123 self
124 }
125
126 /// Set decay factor (infallible). Rejects non-finite values by returning
127 /// `self` unchanged; floors finite values at `0.0`. Prefer
128 /// [`try_with_decay`](Self::try_with_decay) at public boundaries.
129 pub fn with_decay(mut self, d: f64) -> Self {
130 if !d.is_finite() {
131 return self;
132 }
133 self.decay_factor = Some(d.max(0.0));
134 self
135 }
136
137 /// Set salience with validation. Returns an error for non-finite or
138 /// out-of-range `[0.0, 1.0]` values.
139 pub fn try_with_salience(mut self, s: f64) -> Result<Self, String> {
140 if !s.is_finite() {
141 return Err(format!("salience must be finite, got {s}"));
142 }
143 if !(0.0..=1.0).contains(&s) {
144 return Err(format!("salience must be in [0.0, 1.0], got {s}"));
145 }
146 self.salience = Some(s);
147 Ok(self)
148 }
149
150 /// Set decay factor with validation. Returns an error for non-finite or
151 /// negative values.
152 pub fn try_with_decay(mut self, d: f64) -> Result<Self, String> {
153 if !d.is_finite() {
154 return Err(format!("decay_factor must be finite, got {d}"));
155 }
156 if d < 0.0 {
157 return Err(format!("decay_factor must be >= 0.0, got {d}"));
158 }
159 self.decay_factor = Some(d);
160 Ok(self)
161 }
162
163 /// Set the note properties JSON blob.
164 pub fn with_properties(mut self, p: Value) -> Self {
165 self.properties = Some(p);
166 self
167 }
168}
169
170#[cfg(test)]
171#[path = "note/tests.rs"]
172mod tests;
173
174/// Sort direction for filtered note queries.
175#[derive(Clone, Debug, Serialize, Deserialize)]
176#[serde(rename_all = "snake_case")]
177pub enum SortDir {
178 Asc,
179 Desc,
180}
181
182/// Comparison operator for a [`PropertyFilter`] on a JSON path.
183#[derive(Clone, Debug, Serialize, Deserialize)]
184#[serde(rename_all = "snake_case")]
185pub enum FilterOp {
186 Eq,
187 /// Matches rows where the JSON field equals the value OR the field is absent/NULL.
188 /// Used for properties that may be missing in legacy rows (e.g. `$.read`).
189 EqOrMissing,
190 /// Matches the supplied value using the indexable
191 /// `ifnull(json_extract(...), '')` expression. The value may be any
192 /// [`SqlValue`] accepted by the SQL adapter; in particular, `Text("")`
193 /// matches both missing values and present-but-empty values.
194 EqOrMissingIndexed,
195 /// Matches rows where the JSON field is absent or SQL-NULL.
196 JsonTypeMissing,
197 /// Matches a missing path, JSON null, or JSON text empty after SQLite's
198 /// ASCII-SPACE-only `trim`. Tabs and Unicode whitespace do not match.
199 /// `PropertyFilter.value` is unused.
200 MissingNullOrSpaceEmptyText,
201 /// Matches JSON boolean true or the exact JSON text "true", not numeric 1.
202 /// `PropertyFilter.value` is unused.
203 TrueOrTextTrue,
204 /// Matches rows where the JSON field is absent or explicitly JSON `null`,
205 /// while constraining its index key to the empty recipient key. This is
206 /// the index-friendly legacy-recipient partition used with
207 /// [`FilterOp::EqOrMissingIndexed`].
208 JsonTypeMissingOrNullIndexed,
209 /// Combines the exact-value and legacy-recipient partitions
210 /// (`EqOrMissingIndexed` + `JsonTypeMissingOrNullIndexed`) into one
211 /// predicate over the same indexable `ifnull(json_extract(...), '')`
212 /// expression, so a single index seek serves both partitions instead of
213 /// two separate bounded queries. Matches rows where the field equals the
214 /// value, OR the field is absent/JSON-`null`. A present-but-empty JSON
215 /// string value does NOT match through the legacy branch — the same
216 /// `json_type` guard `JsonTypeMissingOrNullIndexed` uses excludes it —
217 /// so this reproduces `EqOrMissing` exactly, given a non-empty compared
218 /// value.
219 EqOrLegacyIndexed,
220 /// Matches rows where a JSON text field equals the value, while treating
221 /// every missing or non-text value as that same value. The SQL adapter
222 /// emits `CASE WHEN json_type(...) = 'text' THEN json_extract(...) ELSE
223 /// value END = value`, mirroring callers whose read model assigns one
224 /// textual default to absent, JSON-null, and malformed legacy values.
225 TextEqOrNonText,
226 /// Matches a JSON text field against the supplied set, or any missing or
227 /// non-text value. The non-text branch still matches when the set is empty.
228 /// `PropertyFilter.value` is unused; the set lives in this variant.
229 TextInOrNonText(Vec<SqlValue>),
230 Ne,
231 Lt,
232 Lte,
233 Gt,
234 Gte,
235 /// Matches rows where `json_type(properties, path) = value`.
236 /// Value must be a SQLite json_type string literal: 'true', 'false', 'integer',
237 /// 'real', 'text', 'array', 'object', or 'null'.
238 JsonTypeEq,
239 /// Matches rows where the json_type is absent (NULL) OR differs from value.
240 /// Equivalent to `json_type IS NULL OR json_type != value`.
241 /// Value must be a SQLite json_type string literal: 'true', 'false',
242 /// 'integer', 'real', 'text', 'array', 'object', or 'null'. Used for
243 /// unread filter: matches any `$.read` that is NOT the JSON boolean true.
244 JsonTypeNeMissing,
245 /// Matches rows where `json_extract(properties, path)` equals any value in
246 /// the set. A row with a missing/NULL property does not match — use
247 /// `TextInOrNonText` when a textual read model includes missing/non-text
248 /// legacy values. `PropertyFilter.value` is unused for this op; the set
249 /// lives in the variant itself.
250 In(Vec<SqlValue>),
251 /// Matches rows where the property is missing/NULL OR its value is not in
252 /// the set. Used to exclude a closed set while treating an unset property
253 /// as included (e.g. comm inbox excludes `outbound`). `PropertyFilter.value` is
254 /// unused for this op; the set lives in the variant itself.
255 NotInOrMissing(Vec<SqlValue>),
256 /// Matches rows whose JSON text field starts with the supplied prefix.
257 /// Rendered as an index-seekable half-open range over the plain
258 /// `json_extract` expression (`expr >= prefix AND expr < next(prefix)`,
259 /// where `next` increments the prefix's last code point), so an index
260 /// keyed on that expression serves the seek instead of a scan. SQLite
261 /// sorts non-text values outside the text range, so a missing, null or
262 /// numeric field never matches. `PropertyFilter.value` is the prefix and
263 /// must be `SqlValue::Text`; an empty prefix matches every text value.
264 TextStartsWithIndexed,
265 /// Match a recipient's first colon-terminated channel prefix by equality
266 /// on its indexed bucket. The value must be a nonempty `SqlValue::Text`
267 /// prefix with exactly one trailing colon, such as `email:`. Arbitrary
268 /// partial prefixes use `TextStartsWithIndexed` instead.
269 TextColonPrefixBucketIndexed,
270 /// Keep only RFC 3339 text values that parse as UTC instants.
271 Rfc3339Valid,
272 /// Compare parsed UTC instants, including subsecond precision and offsets.
273 /// The value is a `Timestamp` or RFC 3339 `Text`.
274 Rfc3339Gte,
275 Rfc3339Lte,
276 /// Matches an RFC 3339 instant at or before the supplied timestamp, or a
277 /// missing, null, non-text, or malformed value. The outbox uses this to
278 /// fail open on legacy retry deadlines without filtering after LIMIT.
279 Rfc3339LteOrInvalid,
280}
281
282/// A single `json_extract(properties, '$.field') op value` predicate.
283///
284/// Callers import this as `khive_storage::note::PropertyFilter` to avoid
285/// collision with the vector-metadata `PropertyFilter` in `khive_storage::types`.
286#[derive(Clone, Debug, Serialize, Deserialize)]
287pub struct PropertyFilter {
288 pub json_path: String,
289 pub op: FilterOp,
290 pub value: SqlValue,
291}
292
293/// A predicate on one literal top-level property key, rechecked at write time.
294/// Explicit JSON null is present and never matches an absent-key branch.
295#[derive(Clone, Debug)]
296pub enum NotePropertyPrecondition {
297 /// `json_extract(properties, path) = value`, with the ordinary [`SqlValue`]
298 /// binding rules. SQL NULL equality does not match; this is not typed JSON equality.
299 ExtractEquals { key: String, value: SqlValue },
300 /// An absent key (`json_type IS NULL`) or [`Self::ExtractEquals`].
301 AbsentOrExtractEquals { key: String, value: SqlValue },
302 /// An absent key, or a JSON text value exactly equal to `value`.
303 AbsentOrTextEquals { key: String, value: String },
304 /// JSON boolean `true` or the exact JSON string `"true"`; numeric 1 is excluded.
305 TrueOrTextTrue { key: String },
306}
307
308/// A bounded, atomic partial update of a note's properties and retention metadata.
309#[derive(Clone, Debug)]
310pub struct NotePropertyPatch {
311 /// AND-combined predicates, at most 32. Keys are literal top-level keys.
312 pub preconditions: Vec<NotePropertyPrecondition>,
313 /// Between 1 and 32 literal top-level writes, preserving each JSON value's type.
314 /// Keys in either collection must not contain U+0000.
315 pub set: BTreeMap<String, Value>,
316 /// Install or extend this expiry; `None` preserves the stored expiry.
317 pub extend_expires_at: Option<i64>,
318 /// Applied as the maximum of the stored and supplied timestamps.
319 pub updated_at: i64,
320}
321
322/// Keyset pagination boundary over the notes store's default total order
323/// (`created_at DESC, id ASC` — see `note_filter_page_order_clause`).
324///
325/// Only meaningful when [`NoteFilter::order_by`] is `None`: the boundary is
326/// expressed in terms of that default order, and combining it with a custom
327/// sort field has no defined meaning, so callers must not set both.
328#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
329pub struct NoteSeekAfter {
330 pub created_at: i64,
331 pub id: Uuid,
332}
333
334/// Boundary in an ascending RFC 3339 property order. Equal instants sort by
335/// their stored text and then note ID, so this cursor identifies one row even
336/// when distinct offsets encode the same instant.
337#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
338pub struct NoteInstantSeekAfter {
339 pub value: String,
340 pub id: Uuid,
341}
342
343#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
344#[serde(rename_all = "snake_case")]
345pub enum NoteTagMode {
346 #[default]
347 Any,
348 All,
349}
350
351#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
352#[serde(deny_unknown_fields)]
353pub struct NoteKeyCursor {
354 pub updated_at: i64,
355 pub key: String,
356 pub id: Uuid,
357}
358
359impl From<&Note> for NoteKeyCursor {
360 fn from(note: &Note) -> Self {
361 Self {
362 updated_at: note.updated_at,
363 key: note.key.clone().expect("keyed row"),
364 id: note.id,
365 }
366 }
367}
368
369/// Inclusive expiry cutoff with a creation cutoff only for notes without an expiry.
370/// Both bounds use microseconds since the Unix epoch.
371#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
372pub struct NoteExpiryFallback {
373 pub expires_at_or_before: i64,
374 pub created_at_or_before: i64,
375}
376
377/// Ascending native timestamp order, with ascending note ID as the final tie-break.
378#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
379#[serde(rename_all = "snake_case")]
380pub enum NoteTimeOrder {
381 /// `expires_at ASC, id ASC`; absent expiries sort first.
382 ExpiresAt,
383 /// `COALESCE(expires_at, created_at) ASC, id ASC`.
384 ExpiresAtOrCreatedAt,
385}
386
387/// Read selection on the note's top-level storage status, independent of
388/// workflow fields such as `properties.status`. Tombstone visibility remains
389/// controlled separately by [`NoteFilter::include_deleted`].
390#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
391#[serde(rename_all = "snake_case")]
392pub enum NoteStatusSelector {
393 Active,
394 Archived,
395 Any,
396}
397
398impl NoteStatusSelector {
399 pub const fn as_str(self) -> &'static str {
400 match self {
401 Self::Active => "active",
402 Self::Archived => "archived",
403 Self::Any => "any",
404 }
405 }
406
407 pub fn matches(self, status: &str) -> bool {
408 match self {
409 Self::Active => status == "active",
410 Self::Archived => status == "archived",
411 Self::Any => true,
412 }
413 }
414}
415
416/// Filter + sort options for [`NoteStore::query_notes_filtered`].
417///
418/// Designed for general property-based filtering on any JSON field, not
419/// schedule-specific, so D9 and future packs can reuse the same API.
420#[derive(Clone, Debug, Default, Serialize, Deserialize)]
421pub struct NoteFilter {
422 pub kind: Option<String>,
423 /// Top-level storage status for filtered reads. `None` and `Any` are raw
424 /// all-status selection; ordinary callers may default missing input to Active.
425 /// Neither bypasses tombstone visibility. Active/Archived are read-only and
426 /// must be rejected by filtered mutations before writer admission.
427 #[serde(default)]
428 pub note_status: Option<NoteStatusSelector>,
429 #[serde(default)]
430 pub property_filters: Vec<PropertyFilter>,
431 /// `(json_path, direction)` — `None` defaults to `created_at DESC`.
432 pub order_by: Option<(String, SortDir)>,
433 /// Interpret `order_by`'s text property as an RFC 3339 UTC instant before
434 /// sorting. Only ascending order is currently supported.
435 #[serde(default)]
436 pub order_by_instant: bool,
437 /// When true, omit the SQL ordering clause from count-free pages. The
438 /// caller is responsible for ordering the bounded result set.
439 #[serde(default)]
440 pub unordered: bool,
441 /// When non-empty, restricts results to any of these namespaces using
442 /// `namespace IN (...)`. Takes precedence over the `namespace` string
443 /// parameter passed to `query_notes_filtered`. When empty the
444 /// caller-supplied `namespace` parameter is used (backward-compatible).
445 #[serde(default)]
446 pub namespaces: Vec<String>,
447 /// Restrict to notes where `created_at >= min_created_at` (microseconds epoch).
448 /// `None` applies no lower-bound constraint.
449 pub min_created_at: Option<i64>,
450 /// Inclusive creation-time upper bound in microseconds since the Unix epoch.
451 #[serde(default)]
452 pub max_created_at: Option<i64>,
453 /// Inclusive expiry-time upper bound in microseconds since the Unix epoch.
454 /// Rows with no expiry do not match a supplied bound.
455 #[serde(default)]
456 pub max_expires_at: Option<i64>,
457 /// Include soft-deleted rows in filtered reads. Property patches remain live-only.
458 #[serde(default)]
459 pub include_deleted: bool,
460 /// Select expired notes, falling back to creation time only when expiry is absent.
461 /// This predicate is ANDed with all other bounds and property filters.
462 #[serde(default)]
463 pub expiry_fallback: Option<NoteExpiryFallback>,
464 /// Native ascending timestamp order for counted/count-free/bounded pages.
465 /// Incompatible with property/instant/unordered ordering or any cursor.
466 /// Keyed/sequence reads and filtered mutations reject it; counts ignore ordering.
467 #[serde(default)]
468 pub time_order: Option<NoteTimeOrder>,
469 #[serde(default)]
470 pub min_updated_at: Option<i64>,
471 #[serde(default)]
472 pub tags: Vec<String>,
473 #[serde(default)]
474 pub tag_mode: NoteTagMode,
475 /// Restrict results to rows strictly after this boundary in the default
476 /// `created_at DESC, id ASC` order, for keyset (seek) pagination that
477 /// avoids re-walking earlier pages the way `PageRequest.offset` does.
478 /// Requires `order_by` to be `None`.
479 ///
480 /// Honoured only by [`NoteStore::query_notes_filtered_count_free`], which
481 /// seeks directly to the boundary and returns `total: None`.
482 /// [`NoteStore::query_notes_filtered`] rejects a non-`None` value with
483 /// `StorageError::InvalidInput`: it computes an exact `COUNT(*)` total
484 /// over the whole matching set, which has no defined meaning paired with
485 /// a seek boundary.
486 #[serde(default)]
487 pub after: Option<NoteSeekAfter>,
488 /// Seek after a row in the `order_by_instant` total order. Honoured only
489 /// by `query_notes_filtered_count_free` with `offset: 0`.
490 #[serde(default)]
491 pub after_instant: Option<NoteInstantSeekAfter>,
492 /// Restrict `message` rows to the ones this mailbox reader may see, in
493 /// the query itself. Rows of every other kind are unaffected. Applying the
494 /// partition here means a scan window, and any cursor derived from it,
495 /// only ever contains rows the reader is allowed to see.
496 #[serde(default)]
497 pub mailbox: Option<NoteMailboxScope>,
498}
499
500impl NoteFilter {
501 /// Supply an ordinary-read default without replacing an explicit selector.
502 pub fn with_default_note_status(mut self, status: NoteStatusSelector) -> Self {
503 self.note_status.get_or_insert(status);
504 self
505 }
506
507 /// Select expiry timestamps at or before `micros` (inclusive, Unix microseconds).
508 /// A note without an expiry does not match this bound.
509 pub fn expires_before(mut self, micros: i64) -> Self {
510 self.max_expires_at = Some(micros);
511 self
512 }
513
514 /// Select creation timestamps at or before `micros` (inclusive, Unix microseconds).
515 pub fn created_before(mut self, micros: i64) -> Self {
516 self.max_created_at = Some(micros);
517 self
518 }
519
520 /// Include tombstones in filtered reads without permitting property patches on them.
521 pub fn include_deleted(mut self) -> Self {
522 self.include_deleted = true;
523 self
524 }
525}
526
527/// The actor partition a mailbox reader may see, as evaluated by the store.
528/// It mirrors the row-level mailbox rule: an inbound message belongs to its
529/// `to_actor`, an outbound message to its `from_actor`, and `legacy_local`
530/// additionally admits the unattributed pre-routing rows.
531#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
532pub struct NoteMailboxScope {
533 pub actor_id: String,
534 pub legacy_local: bool,
535}
536
537/// Temporal-referential note CRUD over the notes substrate table.
538///
539/// Every read accepting a [`NoteFilter`] must apply its `note_status` selection
540/// before counting, paging, lookahead and cursor derivation, or fail closed with
541/// [`crate::StorageError::Unsupported`] if it cannot honor that selector. It must
542/// never silently ignore Active/Archived. Raw `None` and explicit `Any` retain
543/// the existing all-status population and do not bypass `include_deleted`.
544#[async_trait]
545pub trait NoteStore: Send + Sync + 'static {
546 /// Set the key of a live, unkeyed note in the asserted namespace once.
547 /// The namespace is a row predicate, not an authorization check.
548 /// An existing key is never replaced, and the live key uniqueness scope is
549 /// namespace and note kind. Invalid keys are refused without a write.
550 async fn assign_note_key_if_unset(
551 &self,
552 _id: Uuid,
553 key: &str,
554 _namespace: &str,
555 ) -> StorageResult<NoteKeyAssignOutcome> {
556 validate_note_key_for_store(key, "assign_note_key_if_unset")?;
557 Err(crate::StorageError::Unsupported {
558 capability: crate::StorageCapability::Notes,
559 operation: "assign_note_key_if_unset".into(),
560 message: "backend has no guarded note key assignment".into(),
561 })
562 }
563
564 async fn get_live_notes_by_key(
565 &self,
566 _namespace: &str,
567 _key: &str,
568 _kind: Option<&str>,
569 ) -> StorageResult<Vec<Note>> {
570 Err(crate::StorageError::Unsupported {
571 capability: crate::StorageCapability::Notes,
572 operation: "get_live_notes_by_key".into(),
573 message: "backend has no keyed note lookup".into(),
574 })
575 }
576
577 async fn query_keyed_notes(
578 &self,
579 _namespace: &str,
580 _filter: &NoteFilter,
581 _prefix: &str,
582 _after: Option<&NoteKeyCursor>,
583 _page: PageRequest,
584 ) -> StorageResult<(Vec<Note>, Option<NoteKeyCursor>)> {
585 Err(crate::StorageError::Unsupported {
586 capability: crate::StorageCapability::Notes,
587 operation: "query_keyed_notes".into(),
588 message: "backend has no keyed note pagination".into(),
589 })
590 }
591
592 /// Insert or update a single note. Updates preserve the stored immutable key.
593 async fn upsert_note(&self, note: Note) -> StorageResult<()>;
594 /// Replace a note only when the persisted row still matches the caller's
595 /// read snapshot.
596 ///
597 /// `expected_updated_at` is the snapshot revision and
598 /// `expected_deleted_at` closes the soft-delete race (legacy soft-delete
599 /// paths may change `deleted_at` without changing `updated_at`). The
600 /// replacement note's `updated_at` must be strictly greater than that
601 /// persisted revision. Returns `false` when the row disappeared, changed,
602 /// or was supplied a non-advancing replacement revision. This is the
603 /// full-note compare-and-swap seam used when a pack hook derives coupled
604 /// fields from that snapshot before persistence. The default returns
605 /// `Unsupported` rather than falling back to an unguarded upsert and
606 /// reintroducing the stale-snapshot race.
607 async fn replace_note_if_unchanged(
608 &self,
609 _note: Note,
610 _expected_updated_at: i64,
611 _expected_deleted_at: Option<i64>,
612 ) -> StorageResult<bool> {
613 Err(crate::StorageError::Unsupported {
614 capability: crate::StorageCapability::Notes,
615 operation: "replace_note_if_unchanged".into(),
616 message: "this backend does not implement guarded note replacement".into(),
617 })
618 }
619 /// Insert a note only if no row already holds its id, reporting whether
620 /// this call is the one that inserted it.
621 ///
622 /// This closes the other half of the read-modify-write race that
623 /// [`NoteStore::replace_note_if_unchanged`] closes. That one protects a
624 /// caller who read an existing row; this one protects a caller who read
625 /// *no* row. Where the id is derived rather than freshly generated — a
626 /// deterministic per-subject id — two callers can both read absence and
627 /// both write, and an upsert resolves that by overwriting, so the first
628 /// caller's write is lost with no error on either side. Returns `false`
629 /// when a row already existed, which the caller maps to a conflict rather
630 /// than to success.
631 ///
632 /// The pre-existing row is left exactly as it is: this must not be
633 /// implemented as an upsert, since overwriting is the behaviour being
634 /// avoided. The default returns `Unsupported` for that reason, rather
635 /// than falling back to `upsert_note` and silently reintroducing the
636 /// race under a name that promises otherwise.
637 async fn insert_note_if_absent(&self, _note: Note) -> StorageResult<bool> {
638 Err(crate::StorageError::Unsupported {
639 capability: crate::StorageCapability::Notes,
640 operation: "insert_note_if_absent".into(),
641 message: "this backend does not implement guarded note insertion".into(),
642 })
643 }
644 /// Insert or update a batch of notes. Updates preserve each stored immutable key.
645 async fn upsert_notes(&self, notes: Vec<Note>) -> StorageResult<BatchWriteSummary>;
646 /// Fetch a note by UUID, returning `None` if absent.
647 async fn get_note(&self, id: Uuid) -> StorageResult<Option<Note>>;
648 /// Fetch a note by UUID regardless of soft-deletion state.
649 ///
650 /// Returns the note row even when `deleted_at` is set. Callers use this
651 /// to distinguish "soft-deleted" from "never existed".
652 async fn get_note_including_deleted(&self, id: Uuid) -> StorageResult<Option<Note>>;
653 /// Delete a note by UUID using the specified delete mode.
654 async fn delete_note(&self, id: Uuid, mode: DeleteMode) -> StorageResult<bool>;
655 /// Patch `properties`/`updated_at` on an existing note in place via a real
656 /// `UPDATE`, leaving every other column (including the row's `rowid`)
657 /// untouched.
658 ///
659 /// Unlike `upsert_note`, which writes the complete note shape, this leaves
660 /// every non-property column untouched. It also never churns the row's
661 /// implicit `rowid`, which is required by callers relying on stable row
662 /// identity (#780).
663 /// Returns `true` when a live (non-soft-deleted) row with this `id` was
664 /// found and updated, `false` otherwise.
665 async fn update_note_properties(
666 &self,
667 id: Uuid,
668 properties: Option<Value>,
669 updated_at: i64,
670 ) -> StorageResult<bool>;
671 /// Atomically set one top-level key in a note's JSON `properties` object.
672 ///
673 /// The backend must perform the read/modify/write as one storage operation
674 /// so concurrent writes to different keys cannot overwrite each other.
675 /// `value` keeps its JSON type, including explicit JSON `null`. A SQL-NULL
676 /// property document is initialized as an empty object. A live row whose
677 /// stored document is a non-object is not modified and returns `false`, as
678 /// do missing and soft-deleted rows. Keys containing U+0000 must be
679 /// rejected: SQLite JSON-path labels cannot address them without risking
680 /// mutation of a shorter sibling key.
681 async fn set_note_property(
682 &self,
683 id: Uuid,
684 key: &str,
685 value: Value,
686 updated_at: i64,
687 ) -> StorageResult<bool>;
688 /// Atomically patch a single `properties` JSON key on a note, but only
689 /// when the row's *current* state (re-evaluated inside this same
690 /// statement, not a snapshot the caller fetched earlier) still satisfies
691 /// `filter`'s namespace/kind/property_filters.
692 ///
693 /// Unlike `set_note_property` (which patches unconditionally once the row
694 /// is live) or `update_note_properties` (which replaces the whole
695 /// `properties` column with a value the caller already computed — safe
696 /// only when nothing else can have written to the row since the caller's
697 /// read), this also rechecks `filter` against the row's live state before
698 /// writing, so a target that stopped matching an eligibility predicate
699 /// between validation and this call is not mutated. Any other property
700 /// written concurrently between the caller's read and this call survives
701 /// untouched either way. A live row whose stored `properties` document is
702 /// a non-object (scalar, array, or otherwise) is not modified and returns
703 /// `false`, mirroring `set_note_property`. Returns `Ok(false)` — not an
704 /// error — when no live row currently matches `filter` (id not found,
705 /// soft-deleted, an eligibility property changed since the caller last
706 /// validated it, or the stored document is not a JSON object); the
707 /// caller degrades that the same way as `update_note_properties`'s
708 /// `Ok(false)`.
709 ///
710 /// Active/Archived `note_status` values are read-only selectors and must be
711 /// rejected before writer admission, not ignored. Selector-aware backends
712 /// return InvalidInput; unsupported backends may fail closed as Unsupported.
713 /// None/Any preserve the existing neutral mutation population.
714 async fn try_patch_note_property(
715 &self,
716 id: Uuid,
717 namespace: &str,
718 filter: &NoteFilter,
719 json_path: &str,
720 value: Value,
721 updated_at: i64,
722 ) -> StorageResult<bool>;
723 /// Atomically apply a bounded partial property update to one live note.
724 ///
725 /// The current row must match the id, exact namespace, exact kind, and all
726 /// preconditions in the same operation that merges the writes. Namespace
727 /// is an equality guard, not an authorization boundary. A SQL-NULL property
728 /// document starts as `{}`; non-object documents and any other nonmatch
729 /// return `false` without changing the row. Unrelated properties, immutable
730 /// key, row identity, and non-target columns survive. A matched update
731 /// advances the persisted version, even when the supplied timestamp is older.
732 ///
733 /// Validate bounds, keys and write values before writer admission. Maintain
734 /// derived retry-deadline fields when `next_attempt_at` is written, and leave
735 /// them untouched otherwise. Unsupported backends must fail closed without
736 /// a read/replace or upsert fallback.
737 async fn try_patch_note_properties(
738 &self,
739 _id: Uuid,
740 _namespace: &str,
741 _kind: &str,
742 _patch: &NotePropertyPatch,
743 ) -> StorageResult<bool> {
744 Err(crate::StorageError::Unsupported {
745 capability: crate::StorageCapability::Notes,
746 operation: "try_patch_note_properties".into(),
747 message: "this backend does not implement guarded partial note updates".into(),
748 })
749 }
750 /// Atomically patch one JSON property on every supplied note.
751 ///
752 /// Each target is rechecked against `namespace` and `filter` inside the
753 /// same transaction. The operation commits only when every distinct id
754 /// matches exactly one live object-valued row; a missing, soft-deleted, or
755 /// no-longer-eligible target rolls the entire unit back. Other property
756 /// keys are preserved by the same storage-side `json_set` operation as
757 /// [`Self::try_patch_note_property`]. Backends without a transactional
758 /// multi-note implementation retain the default `Unsupported` result.
759 /// Active/Archived `note_status` values must be rejected before writer
760 /// admission, as for [`Self::try_patch_note_property`]; None/Any are neutral.
761 async fn patch_note_property_atomic(
762 &self,
763 _ids: Vec<Uuid>,
764 _namespace: &str,
765 _filter: &NoteFilter,
766 _json_path: &str,
767 _value: Value,
768 _updated_at: i64,
769 ) -> StorageResult<()> {
770 Err(crate::StorageError::Unsupported {
771 capability: crate::StorageCapability::Notes,
772 operation: "patch_note_property_atomic".into(),
773 message: "this backend does not implement atomic multi-note property patches".into(),
774 })
775 }
776 /// Query notes by namespace and optional kind with pagination.
777 /// The returned total and page items must come from one consistent
778 /// backend snapshot.
779 async fn query_notes(
780 &self,
781 namespace: &str,
782 kind: Option<&str>,
783 page: PageRequest,
784 ) -> StorageResult<Page<Note>>;
785 /// Query notes by namespace and optional kind without computing an exact total.
786 ///
787 /// Implementations must return `total: None`. Backends that cannot
788 /// guarantee a count-free projection must fail closed rather than invoke
789 /// [`Self::query_notes`], whose exact total remains available to callers
790 /// that expose a snapshot-consistent count.
791 async fn query_notes_count_free(
792 &self,
793 _namespace: &str,
794 _kind: Option<&str>,
795 _page: PageRequest,
796 ) -> StorageResult<Page<Note>> {
797 Err(crate::StorageError::Unsupported {
798 capability: crate::StorageCapability::Notes,
799 operation: "query_notes_count_free".into(),
800 message: "this backend does not implement count-free note paging".into(),
801 })
802 }
803 /// Query notes with property-based filtering and custom sort.
804 /// The returned total and page items must come from one consistent
805 /// backend snapshot.
806 async fn query_notes_filtered(
807 &self,
808 namespace: &str,
809 filter: &NoteFilter,
810 page: PageRequest,
811 ) -> StorageResult<Page<Note>>;
812 /// Query a filtered note page without computing an exact total.
813 ///
814 /// Implementations must return `total: None`; callers that need a
815 /// `has_more` bit should request one lookahead row. Backends that cannot
816 /// guarantee a count-free projection must fail closed rather than invoke
817 /// [`Self::query_notes_filtered`], whose exact total is intentionally
818 /// backlog-proportional.
819 async fn query_notes_filtered_count_free(
820 &self,
821 _namespace: &str,
822 _filter: &NoteFilter,
823 _page: PageRequest,
824 ) -> StorageResult<Page<Note>> {
825 Err(crate::StorageError::Unsupported {
826 capability: crate::StorageCapability::Notes,
827 operation: "query_notes_filtered_count_free".into(),
828 message: "this backend does not implement count-free filtered note paging".into(),
829 })
830 }
831 /// Count several filtered note populations in one consistent backend
832 /// snapshot. Backends that cannot provide that guarantee must return
833 /// [`crate::StorageError::Unsupported`] rather than composing independent
834 /// queries or treating an absent page total as zero. SQL backends should
835 /// override this operation so callers can retain separate index-friendly
836 /// predicates without racing between their counts.
837 async fn count_notes_filtered_in_snapshot(
838 &self,
839 _namespace: &str,
840 _filters: &[NoteFilter],
841 ) -> StorageResult<Vec<u64>> {
842 Err(crate::StorageError::Unsupported {
843 capability: crate::StorageCapability::Notes,
844 operation: "count_notes_filtered_in_snapshot".into(),
845 message: "this backend does not implement snapshot-consistent filtered note counts"
846 .into(),
847 })
848 }
849 /// Count several filtered note populations in one backend snapshot, with
850 /// each count bounded by `cap`.
851 ///
852 /// A saturated entry reports `count == cap` and `saturated == true`; an
853 /// unsaturated entry is exact. SQL implementations should count over a
854 /// limited `SELECT 1` subquery so work is proportional to `cap` and the
855 /// caller's own matching population, never an unrelated backlog. That
856 /// bound holds only when every `property_filter` in the given
857 /// `NoteFilter` is servable as an index key column (equality on a bound
858 /// parameter or a plan-time-provable partial-index predicate) all the way
859 /// down to the filter that actually narrows the population — a residual
860 /// filter evaluated after the index seek (a bound parameter the index
861 /// cannot use to skip rows) degrades the bound to work proportional to
862 /// the rows *scanned* before `cap` matches are found, not the rows that
863 /// match. Callers building filters against this bound must ensure the
864 /// full predicate set is indexed, not just the predicate that narrows the
865 /// population most. This includes `note_status`: selecting a status does not
866 /// imply a status index or a cap-proportional scan. Backends that cannot
867 /// preserve the shared snapshot or
868 /// work bound must fail closed.
869 async fn count_notes_filtered_bounded_in_snapshot(
870 &self,
871 _namespace: &str,
872 _filters: &[NoteFilter],
873 _cap: u32,
874 ) -> StorageResult<Vec<BoundedCount>> {
875 Err(crate::StorageError::Unsupported {
876 capability: crate::StorageCapability::Notes,
877 operation: "count_notes_filtered_bounded_in_snapshot".into(),
878 message: "this backend does not implement snapshot-consistent bounded note counts"
879 .into(),
880 })
881 }
882 /// Resolve a note id to its immutable insertion sequence.
883 async fn note_sequence(&self, _id: Uuid) -> StorageResult<Option<i64>> {
884 Err(crate::StorageError::Unsupported {
885 capability: crate::StorageCapability::Notes,
886 operation: "note_sequence".into(),
887 message: "this backend does not implement note insertion sequences".into(),
888 })
889 }
890 /// Query an immutable insertion-sequence keyset page with the same
891 /// predicates as [`Self::query_notes_filtered`].
892 async fn query_notes_filtered_after(
893 &self,
894 _namespace: &str,
895 _filter: &NoteFilter,
896 _after: Option<SeekCursor>,
897 _limit: u32,
898 ) -> StorageResult<SeekPage<Note>> {
899 Err(crate::StorageError::Unsupported {
900 capability: crate::StorageCapability::Notes,
901 operation: "query_notes_filtered_after".into(),
902 message: "this backend does not implement note seek pagination".into(),
903 })
904 }
905 /// Fetch up to `max_rows + 1` notes matching `filter` in a single
906 /// deterministically-ordered SQL statement, with no separate `COUNT(*)`
907 /// and no pagination loop.
908 ///
909 /// A single statement observes one consistent snapshot for its entire
910 /// execution, so the result cannot be split across a concurrent insert
911 /// the way a `COUNT(*)` followed by independent `LIMIT`/`OFFSET` pages
912 /// can. Callers detect the over-bound case by checking whether the
913 /// returned `Vec` has more than `max_rows` items — that means at least
914 /// `max_rows + 1` rows matched and the caller must reject the query
915 /// rather than silently return a truncated, possibly priority-incomplete
916 /// set.
917 async fn query_notes_filtered_bounded(
918 &self,
919 namespace: &str,
920 filter: &NoteFilter,
921 max_rows: u32,
922 ) -> StorageResult<Vec<Note>>;
923 /// Count notes in a namespace, optionally filtered by kind.
924 async fn count_notes(&self, namespace: &str, kind: Option<&str>) -> StorageResult<u64>;
925 /// Count notes across the given namespaces, optionally filtered by kind.
926 /// The default preserves compatibility by summing the existing
927 /// single-namespace operation; SQL backends should override this with one
928 /// `IN` aggregate.
929 async fn count_notes_in_namespaces(
930 &self,
931 namespaces: &[String],
932 kind: Option<&str>,
933 ) -> StorageResult<u64> {
934 let mut total = 0;
935 for namespace in namespaces {
936 total += self.count_notes(namespace, kind).await?;
937 }
938 Ok(total)
939 }
940
941 /// Attempt to insert a note without overwriting an existing row.
942 ///
943 /// Returns `true` when the row was newly written. Returns `false` only
944 /// when a live note with the same non-empty `external_id` already exists in
945 /// the same namespace and kind (confirmed dedup hit). Any other constraint
946 /// violation (e.g. a primary key collision) is surfaced as a `StorageError`
947 /// so that callers do not misinterpret unexpected failures as deduplication.
948 async fn try_insert_note(&self, note: Note) -> StorageResult<bool>;
949
950 /// Atomically insert an ingest note and the blob attachments owned by it.
951 /// A deduplicated note writes no attachments; callers must inspect the
952 /// existing note before repairing a legacy missing role.
953 async fn try_insert_note_with_attachments(
954 &self,
955 _note: Note,
956 _attachments: Vec<crate::Attachment>,
957 ) -> StorageResult<bool> {
958 Err(crate::StorageError::Unsupported {
959 capability: crate::StorageCapability::Notes,
960 operation: "try_insert_note_with_attachments".into(),
961 message: "this backend cannot atomically insert note attachments".into(),
962 })
963 }
964
965 /// Fetch multiple notes by UUID in a single call.
966 async fn get_notes_batch(&self, ids: &[Uuid]) -> StorageResult<Vec<Note>> {
967 let mut out = Vec::with_capacity(ids.len());
968 for &id in ids {
969 if let Some(n) = self.get_note(id).await? {
970 out.push(n);
971 }
972 }
973 Ok(out)
974 }
975
976 /// Fetch multiple notes, including soft-deleted rows, for mutation policy checks.
977 /// Missing IDs are omitted; callers correlate rows by ID rather than result order.
978 async fn get_notes_batch_including_deleted(&self, ids: &[Uuid]) -> StorageResult<Vec<Note>> {
979 let mut out = Vec::with_capacity(ids.len());
980 for &id in ids {
981 if let Some(note) = self.get_note_including_deleted(id).await? {
982 out.push(note);
983 }
984 }
985 Ok(out)
986 }
987
988 /// Fetch only the columns needed for note visibility checks by UUID.
989 /// Missing IDs are omitted; soft-deleted rows retain their deletion time.
990 async fn get_note_visibility_batch(&self, ids: &[Uuid]) -> StorageResult<Vec<NoteVisibility>> {
991 let mut out = Vec::with_capacity(ids.len());
992 for &id in ids {
993 if let Some(note) = self.get_note_including_deleted(id).await? {
994 out.push(NoteVisibility {
995 id: note.id,
996 namespace: note.namespace,
997 deleted_at: note.deleted_at,
998 });
999 }
1000 }
1001 Ok(out)
1002 }
1003}
1004
1005#[cfg(test)]
1006mod note_status_selector_contract_tests {
1007 use super::*;
1008
1009 #[test]
1010 fn selector_wire_values_and_exact_status_matching_are_closed() {
1011 for (selector, wire) in [
1012 (NoteStatusSelector::Active, "active"),
1013 (NoteStatusSelector::Archived, "archived"),
1014 (NoteStatusSelector::Any, "any"),
1015 ] {
1016 assert_eq!(selector.as_str(), wire);
1017 assert_eq!(
1018 serde_json::to_value(selector).unwrap(),
1019 Value::String(wire.into())
1020 );
1021 assert_eq!(
1022 serde_json::from_value::<NoteStatusSelector>(Value::String(wire.into())).unwrap(),
1023 selector
1024 );
1025 }
1026 for invalid in ["Active", "deleted", "unknown", ""] {
1027 assert!(
1028 serde_json::from_value::<NoteStatusSelector>(Value::String(invalid.into()))
1029 .is_err()
1030 );
1031 }
1032 assert!(NoteStatusSelector::Active.matches("active"));
1033 assert!(!NoteStatusSelector::Active.matches("archived"));
1034 assert!(!NoteStatusSelector::Active.matches("ACTIVE"));
1035 assert!(NoteStatusSelector::Archived.matches("archived"));
1036 assert!(!NoteStatusSelector::Archived.matches("active"));
1037 assert!(NoteStatusSelector::Any.matches("deleted"));
1038 assert!(NoteStatusSelector::Any.matches("unrecognized-stored-status"));
1039 }
1040
1041 #[test]
1042 fn raw_filter_is_neutral_and_defaulting_preserves_explicit_status() {
1043 let legacy: NoteFilter = serde_json::from_value(serde_json::json!({
1044 "kind": null, "order_by": null, "min_created_at": null
1045 }))
1046 .unwrap();
1047 assert_eq!(legacy.note_status, None);
1048 assert_eq!(NoteFilter::default().note_status, None);
1049 assert_eq!(
1050 legacy
1051 .with_default_note_status(NoteStatusSelector::Active)
1052 .note_status,
1053 Some(NoteStatusSelector::Active)
1054 );
1055 for explicit in [
1056 NoteStatusSelector::Active,
1057 NoteStatusSelector::Archived,
1058 NoteStatusSelector::Any,
1059 ] {
1060 let filter = NoteFilter {
1061 note_status: Some(explicit),
1062 ..Default::default()
1063 }
1064 .with_default_note_status(NoteStatusSelector::Active);
1065 assert_eq!(filter.note_status, Some(explicit));
1066 let decoded: NoteFilter =
1067 serde_json::from_value(serde_json::to_value(filter).unwrap()).unwrap();
1068 assert_eq!(decoded.note_status, Some(explicit));
1069 }
1070 }
1071}