Skip to main content

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    /// `updated_at ASC, id ASC`: the oldest-touched rows first.
386    UpdatedAt,
387}
388
389/// Read selection on the note's top-level storage status, independent of
390/// workflow fields such as `properties.status`. Tombstone visibility remains
391/// controlled separately by [`NoteFilter::include_deleted`].
392#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
393#[serde(rename_all = "snake_case")]
394pub enum NoteStatusSelector {
395    Active,
396    Archived,
397    Any,
398}
399
400impl NoteStatusSelector {
401    pub const fn as_str(self) -> &'static str {
402        match self {
403            Self::Active => "active",
404            Self::Archived => "archived",
405            Self::Any => "any",
406        }
407    }
408
409    pub fn matches(self, status: &str) -> bool {
410        match self {
411            Self::Active => status == "active",
412            Self::Archived => status == "archived",
413            Self::Any => true,
414        }
415    }
416}
417
418/// Filter + sort options for [`NoteStore::query_notes_filtered`].
419///
420/// Designed for general property-based filtering on any JSON field, not
421/// schedule-specific, so D9 and future packs can reuse the same API.
422#[derive(Clone, Debug, Default, Serialize, Deserialize)]
423pub struct NoteFilter {
424    pub kind: Option<String>,
425    /// Top-level storage status for filtered reads. `None` and `Any` are raw
426    /// all-status selection; ordinary callers may default missing input to Active.
427    /// Neither bypasses tombstone visibility. Active/Archived are read-only and
428    /// must be rejected by filtered mutations before writer admission.
429    #[serde(default)]
430    pub note_status: Option<NoteStatusSelector>,
431    #[serde(default)]
432    pub property_filters: Vec<PropertyFilter>,
433    /// `(json_path, direction)` — `None` defaults to `created_at DESC`.
434    pub order_by: Option<(String, SortDir)>,
435    /// Interpret `order_by`'s text property as an RFC 3339 UTC instant before
436    /// sorting. Only ascending order is currently supported.
437    #[serde(default)]
438    pub order_by_instant: bool,
439    /// When true, omit the SQL ordering clause from count-free pages. The
440    /// caller is responsible for ordering the bounded result set.
441    #[serde(default)]
442    pub unordered: bool,
443    /// When non-empty, restricts results to any of these namespaces using
444    /// `namespace IN (...)`. Takes precedence over the `namespace` string
445    /// parameter passed to `query_notes_filtered`. When empty the
446    /// caller-supplied `namespace` parameter is used (backward-compatible).
447    #[serde(default)]
448    pub namespaces: Vec<String>,
449    /// Restrict to notes where `created_at >= min_created_at` (microseconds epoch).
450    /// `None` applies no lower-bound constraint.
451    pub min_created_at: Option<i64>,
452    /// Inclusive creation-time upper bound in microseconds since the Unix epoch.
453    #[serde(default)]
454    pub max_created_at: Option<i64>,
455    /// Inclusive expiry-time upper bound in microseconds since the Unix epoch.
456    /// Rows with no expiry do not match a supplied bound.
457    #[serde(default)]
458    pub max_expires_at: Option<i64>,
459    /// Include soft-deleted rows in filtered reads. Property patches remain live-only.
460    #[serde(default)]
461    pub include_deleted: bool,
462    /// Select expired notes, falling back to creation time only when expiry is absent.
463    /// This predicate is ANDed with all other bounds and property filters.
464    #[serde(default)]
465    pub expiry_fallback: Option<NoteExpiryFallback>,
466    /// Native ascending timestamp order for counted/count-free/bounded pages.
467    /// Incompatible with property/instant/unordered ordering or any cursor.
468    /// Keyed/sequence reads and filtered mutations reject it; counts ignore ordering.
469    #[serde(default)]
470    pub time_order: Option<NoteTimeOrder>,
471    #[serde(default)]
472    pub min_updated_at: Option<i64>,
473    #[serde(default)]
474    pub tags: Vec<String>,
475    #[serde(default)]
476    pub tag_mode: NoteTagMode,
477    /// Restrict results to rows strictly after this boundary in the default
478    /// `created_at DESC, id ASC` order, for keyset (seek) pagination that
479    /// avoids re-walking earlier pages the way `PageRequest.offset` does.
480    /// Requires `order_by` to be `None`.
481    ///
482    /// Honoured only by [`NoteStore::query_notes_filtered_count_free`], which
483    /// seeks directly to the boundary and returns `total: None`.
484    /// [`NoteStore::query_notes_filtered`] rejects a non-`None` value with
485    /// `StorageError::InvalidInput`: it computes an exact `COUNT(*)` total
486    /// over the whole matching set, which has no defined meaning paired with
487    /// a seek boundary.
488    #[serde(default)]
489    pub after: Option<NoteSeekAfter>,
490    /// Seek after a row in the `order_by_instant` total order. Honoured only
491    /// by `query_notes_filtered_count_free` with `offset: 0`.
492    #[serde(default)]
493    pub after_instant: Option<NoteInstantSeekAfter>,
494    /// Restrict `message` rows to the ones this mailbox reader may see, in
495    /// the query itself. Rows of every other kind are unaffected. Applying the
496    /// partition here means a scan window, and any cursor derived from it,
497    /// only ever contains rows the reader is allowed to see.
498    #[serde(default)]
499    pub mailbox: Option<NoteMailboxScope>,
500}
501
502impl NoteFilter {
503    /// Supply an ordinary-read default without replacing an explicit selector.
504    pub fn with_default_note_status(mut self, status: NoteStatusSelector) -> Self {
505        self.note_status.get_or_insert(status);
506        self
507    }
508
509    /// Select expiry timestamps at or before `micros` (inclusive, Unix microseconds).
510    /// A note without an expiry does not match this bound.
511    pub fn expires_before(mut self, micros: i64) -> Self {
512        self.max_expires_at = Some(micros);
513        self
514    }
515
516    /// Select creation timestamps at or before `micros` (inclusive, Unix microseconds).
517    pub fn created_before(mut self, micros: i64) -> Self {
518        self.max_created_at = Some(micros);
519        self
520    }
521
522    /// Include tombstones in filtered reads without permitting property patches on them.
523    pub fn include_deleted(mut self) -> Self {
524        self.include_deleted = true;
525        self
526    }
527}
528
529/// The actor partition a mailbox reader may see, as evaluated by the store.
530/// It mirrors the row-level mailbox rule: an inbound message belongs to its
531/// `to_actor`, an outbound message to its `from_actor`, and `legacy_local`
532/// additionally admits the unattributed pre-routing rows.
533#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
534pub struct NoteMailboxScope {
535    pub actor_id: String,
536    pub legacy_local: bool,
537}
538
539/// Temporal-referential note CRUD over the notes substrate table.
540///
541/// Every read accepting a [`NoteFilter`] must apply its `note_status` selection
542/// before counting, paging, lookahead and cursor derivation, or fail closed with
543/// [`crate::StorageError::Unsupported`] if it cannot honor that selector. It must
544/// never silently ignore Active/Archived. Raw `None` and explicit `Any` retain
545/// the existing all-status population and do not bypass `include_deleted`.
546#[async_trait]
547pub trait NoteStore: Send + Sync + 'static {
548    /// Set the key of a live, unkeyed note in the asserted namespace once.
549    /// The namespace is a row predicate, not an authorization check.
550    /// An existing key is never replaced, and the live key uniqueness scope is
551    /// namespace and note kind. Invalid keys are refused without a write.
552    async fn assign_note_key_if_unset(
553        &self,
554        _id: Uuid,
555        key: &str,
556        _namespace: &str,
557    ) -> StorageResult<NoteKeyAssignOutcome> {
558        validate_note_key_for_store(key, "assign_note_key_if_unset")?;
559        Err(crate::StorageError::Unsupported {
560            capability: crate::StorageCapability::Notes,
561            operation: "assign_note_key_if_unset".into(),
562            message: "backend has no guarded note key assignment".into(),
563        })
564    }
565
566    async fn get_live_notes_by_key(
567        &self,
568        _namespace: &str,
569        _key: &str,
570        _kind: Option<&str>,
571    ) -> StorageResult<Vec<Note>> {
572        Err(crate::StorageError::Unsupported {
573            capability: crate::StorageCapability::Notes,
574            operation: "get_live_notes_by_key".into(),
575            message: "backend has no keyed note lookup".into(),
576        })
577    }
578
579    async fn query_keyed_notes(
580        &self,
581        _namespace: &str,
582        _filter: &NoteFilter,
583        _prefix: &str,
584        _after: Option<&NoteKeyCursor>,
585        _page: PageRequest,
586    ) -> StorageResult<(Vec<Note>, Option<NoteKeyCursor>)> {
587        Err(crate::StorageError::Unsupported {
588            capability: crate::StorageCapability::Notes,
589            operation: "query_keyed_notes".into(),
590            message: "backend has no keyed note pagination".into(),
591        })
592    }
593
594    /// Insert or update a single note. Updates preserve the stored immutable key.
595    async fn upsert_note(&self, note: Note) -> StorageResult<()>;
596    /// Replace a note only when the persisted row still matches the caller's
597    /// read snapshot.
598    ///
599    /// `expected_updated_at` is the snapshot revision and
600    /// `expected_deleted_at` closes the soft-delete race (legacy soft-delete
601    /// paths may change `deleted_at` without changing `updated_at`). The
602    /// replacement note's `updated_at` must be strictly greater than that
603    /// persisted revision. Returns `false` when the row disappeared, changed,
604    /// or was supplied a non-advancing replacement revision. This is the
605    /// full-note compare-and-swap seam used when a pack hook derives coupled
606    /// fields from that snapshot before persistence. The default returns
607    /// `Unsupported` rather than falling back to an unguarded upsert and
608    /// reintroducing the stale-snapshot race.
609    async fn replace_note_if_unchanged(
610        &self,
611        _note: Note,
612        _expected_updated_at: i64,
613        _expected_deleted_at: Option<i64>,
614    ) -> StorageResult<bool> {
615        Err(crate::StorageError::Unsupported {
616            capability: crate::StorageCapability::Notes,
617            operation: "replace_note_if_unchanged".into(),
618            message: "this backend does not implement guarded note replacement".into(),
619        })
620    }
621    /// Insert a note only if no row already holds its id, reporting whether
622    /// this call is the one that inserted it.
623    ///
624    /// This closes the other half of the read-modify-write race that
625    /// [`NoteStore::replace_note_if_unchanged`] closes. That one protects a
626    /// caller who read an existing row; this one protects a caller who read
627    /// *no* row. Where the id is derived rather than freshly generated — a
628    /// deterministic per-subject id — two callers can both read absence and
629    /// both write, and an upsert resolves that by overwriting, so the first
630    /// caller's write is lost with no error on either side. Returns `false`
631    /// when a row already existed, which the caller maps to a conflict rather
632    /// than to success.
633    ///
634    /// The pre-existing row is left exactly as it is: this must not be
635    /// implemented as an upsert, since overwriting is the behaviour being
636    /// avoided. The default returns `Unsupported` for that reason, rather
637    /// than falling back to `upsert_note` and silently reintroducing the
638    /// race under a name that promises otherwise.
639    async fn insert_note_if_absent(&self, _note: Note) -> StorageResult<bool> {
640        Err(crate::StorageError::Unsupported {
641            capability: crate::StorageCapability::Notes,
642            operation: "insert_note_if_absent".into(),
643            message: "this backend does not implement guarded note insertion".into(),
644        })
645    }
646    /// Insert or update a batch of notes. Updates preserve each stored immutable key.
647    async fn upsert_notes(&self, notes: Vec<Note>) -> StorageResult<BatchWriteSummary>;
648    /// Fetch a note by UUID, returning `None` if absent.
649    async fn get_note(&self, id: Uuid) -> StorageResult<Option<Note>>;
650    /// Fetch a note by UUID regardless of soft-deletion state.
651    ///
652    /// Returns the note row even when `deleted_at` is set. Callers use this
653    /// to distinguish "soft-deleted" from "never existed".
654    async fn get_note_including_deleted(&self, id: Uuid) -> StorageResult<Option<Note>>;
655    /// Delete a note by UUID using the specified delete mode.
656    async fn delete_note(&self, id: Uuid, mode: DeleteMode) -> StorageResult<bool>;
657    /// Patch `properties`/`updated_at` on an existing note in place via a real
658    /// `UPDATE`, leaving every other column (including the row's `rowid`)
659    /// untouched.
660    ///
661    /// Unlike `upsert_note`, which writes the complete note shape, this leaves
662    /// every non-property column untouched. It also never churns the row's
663    /// implicit `rowid`, which is required by callers relying on stable row
664    /// identity (#780).
665    /// Returns `true` when a live (non-soft-deleted) row with this `id` was
666    /// found and updated, `false` otherwise.
667    async fn update_note_properties(
668        &self,
669        id: Uuid,
670        properties: Option<Value>,
671        updated_at: i64,
672    ) -> StorageResult<bool>;
673    /// Atomically set one top-level key in a note's JSON `properties` object.
674    ///
675    /// The backend must perform the read/modify/write as one storage operation
676    /// so concurrent writes to different keys cannot overwrite each other.
677    /// `value` keeps its JSON type, including explicit JSON `null`. A SQL-NULL
678    /// property document is initialized as an empty object. A live row whose
679    /// stored document is a non-object is not modified and returns `false`, as
680    /// do missing and soft-deleted rows. Keys containing U+0000 must be
681    /// rejected: SQLite JSON-path labels cannot address them without risking
682    /// mutation of a shorter sibling key.
683    async fn set_note_property(
684        &self,
685        id: Uuid,
686        key: &str,
687        value: Value,
688        updated_at: i64,
689    ) -> StorageResult<bool>;
690    /// Atomically patch a single `properties` JSON key on a note, but only
691    /// when the row's *current* state (re-evaluated inside this same
692    /// statement, not a snapshot the caller fetched earlier) still satisfies
693    /// `filter`'s namespace/kind/property_filters.
694    ///
695    /// Unlike `set_note_property` (which patches unconditionally once the row
696    /// is live) or `update_note_properties` (which replaces the whole
697    /// `properties` column with a value the caller already computed — safe
698    /// only when nothing else can have written to the row since the caller's
699    /// read), this also rechecks `filter` against the row's live state before
700    /// writing, so a target that stopped matching an eligibility predicate
701    /// between validation and this call is not mutated. Any other property
702    /// written concurrently between the caller's read and this call survives
703    /// untouched either way. A live row whose stored `properties` document is
704    /// a non-object (scalar, array, or otherwise) is not modified and returns
705    /// `false`, mirroring `set_note_property`. Returns `Ok(false)` — not an
706    /// error — when no live row currently matches `filter` (id not found,
707    /// soft-deleted, an eligibility property changed since the caller last
708    /// validated it, or the stored document is not a JSON object); the
709    /// caller degrades that the same way as `update_note_properties`'s
710    /// `Ok(false)`.
711    ///
712    /// Active/Archived `note_status` values are read-only selectors and must be
713    /// rejected before writer admission, not ignored. Selector-aware backends
714    /// return InvalidInput; unsupported backends may fail closed as Unsupported.
715    /// None/Any preserve the existing neutral mutation population.
716    async fn try_patch_note_property(
717        &self,
718        id: Uuid,
719        namespace: &str,
720        filter: &NoteFilter,
721        json_path: &str,
722        value: Value,
723        updated_at: i64,
724    ) -> StorageResult<bool>;
725    /// Atomically apply a bounded partial property update to one live note.
726    ///
727    /// The current row must match the id, exact namespace, exact kind, and all
728    /// preconditions in the same operation that merges the writes. Namespace
729    /// is an equality guard, not an authorization boundary. A SQL-NULL property
730    /// document starts as `{}`; non-object documents and any other nonmatch
731    /// return `false` without changing the row. Unrelated properties, immutable
732    /// key, row identity, and non-target columns survive. A matched update
733    /// advances the persisted version, even when the supplied timestamp is older.
734    ///
735    /// Validate bounds, keys and write values before writer admission. Maintain
736    /// derived retry-deadline fields when `next_attempt_at` is written, and leave
737    /// them untouched otherwise. Unsupported backends must fail closed without
738    /// a read/replace or upsert fallback.
739    async fn try_patch_note_properties(
740        &self,
741        _id: Uuid,
742        _namespace: &str,
743        _kind: &str,
744        _patch: &NotePropertyPatch,
745    ) -> StorageResult<bool> {
746        Err(crate::StorageError::Unsupported {
747            capability: crate::StorageCapability::Notes,
748            operation: "try_patch_note_properties".into(),
749            message: "this backend does not implement guarded partial note updates".into(),
750        })
751    }
752    /// Atomically patch one JSON property on every supplied note.
753    ///
754    /// Each target is rechecked against `namespace` and `filter` inside the
755    /// same transaction. The operation commits only when every distinct id
756    /// matches exactly one live object-valued row; a missing, soft-deleted, or
757    /// no-longer-eligible target rolls the entire unit back. Other property
758    /// keys are preserved by the same storage-side `json_set` operation as
759    /// [`Self::try_patch_note_property`]. Backends without a transactional
760    /// multi-note implementation retain the default `Unsupported` result.
761    /// Active/Archived `note_status` values must be rejected before writer
762    /// admission, as for [`Self::try_patch_note_property`]; None/Any are neutral.
763    async fn patch_note_property_atomic(
764        &self,
765        _ids: Vec<Uuid>,
766        _namespace: &str,
767        _filter: &NoteFilter,
768        _json_path: &str,
769        _value: Value,
770        _updated_at: i64,
771    ) -> StorageResult<()> {
772        Err(crate::StorageError::Unsupported {
773            capability: crate::StorageCapability::Notes,
774            operation: "patch_note_property_atomic".into(),
775            message: "this backend does not implement atomic multi-note property patches".into(),
776        })
777    }
778    /// Query notes by namespace and optional kind with pagination.
779    /// The returned total and page items must come from one consistent
780    /// backend snapshot.
781    async fn query_notes(
782        &self,
783        namespace: &str,
784        kind: Option<&str>,
785        page: PageRequest,
786    ) -> StorageResult<Page<Note>>;
787    /// Query notes by namespace and optional kind without computing an exact total.
788    ///
789    /// Implementations must return `total: None`. Backends that cannot
790    /// guarantee a count-free projection must fail closed rather than invoke
791    /// [`Self::query_notes`], whose exact total remains available to callers
792    /// that expose a snapshot-consistent count.
793    async fn query_notes_count_free(
794        &self,
795        _namespace: &str,
796        _kind: Option<&str>,
797        _page: PageRequest,
798    ) -> StorageResult<Page<Note>> {
799        Err(crate::StorageError::Unsupported {
800            capability: crate::StorageCapability::Notes,
801            operation: "query_notes_count_free".into(),
802            message: "this backend does not implement count-free note paging".into(),
803        })
804    }
805    /// Query notes with property-based filtering and custom sort.
806    /// The returned total and page items must come from one consistent
807    /// backend snapshot.
808    async fn query_notes_filtered(
809        &self,
810        namespace: &str,
811        filter: &NoteFilter,
812        page: PageRequest,
813    ) -> StorageResult<Page<Note>>;
814    /// Query a filtered note page without computing an exact total.
815    ///
816    /// Implementations must return `total: None`; callers that need a
817    /// `has_more` bit should request one lookahead row. Backends that cannot
818    /// guarantee a count-free projection must fail closed rather than invoke
819    /// [`Self::query_notes_filtered`], whose exact total is intentionally
820    /// backlog-proportional.
821    async fn query_notes_filtered_count_free(
822        &self,
823        _namespace: &str,
824        _filter: &NoteFilter,
825        _page: PageRequest,
826    ) -> StorageResult<Page<Note>> {
827        Err(crate::StorageError::Unsupported {
828            capability: crate::StorageCapability::Notes,
829            operation: "query_notes_filtered_count_free".into(),
830            message: "this backend does not implement count-free filtered note paging".into(),
831        })
832    }
833    /// Count several filtered note populations in one consistent backend
834    /// snapshot. Backends that cannot provide that guarantee must return
835    /// [`crate::StorageError::Unsupported`] rather than composing independent
836    /// queries or treating an absent page total as zero. SQL backends should
837    /// override this operation so callers can retain separate index-friendly
838    /// predicates without racing between their counts.
839    async fn count_notes_filtered_in_snapshot(
840        &self,
841        _namespace: &str,
842        _filters: &[NoteFilter],
843    ) -> StorageResult<Vec<u64>> {
844        Err(crate::StorageError::Unsupported {
845            capability: crate::StorageCapability::Notes,
846            operation: "count_notes_filtered_in_snapshot".into(),
847            message: "this backend does not implement snapshot-consistent filtered note counts"
848                .into(),
849        })
850    }
851    /// Count several filtered note populations in one backend snapshot, with
852    /// each count bounded by `cap`.
853    ///
854    /// A saturated entry reports `count == cap` and `saturated == true`; an
855    /// unsaturated entry is exact. SQL implementations should count over a
856    /// limited `SELECT 1` subquery so work is proportional to `cap` and the
857    /// caller's own matching population, never an unrelated backlog. That
858    /// bound holds only when every `property_filter` in the given
859    /// `NoteFilter` is servable as an index key column (equality on a bound
860    /// parameter or a plan-time-provable partial-index predicate) all the way
861    /// down to the filter that actually narrows the population — a residual
862    /// filter evaluated after the index seek (a bound parameter the index
863    /// cannot use to skip rows) degrades the bound to work proportional to
864    /// the rows *scanned* before `cap` matches are found, not the rows that
865    /// match. Callers building filters against this bound must ensure the
866    /// full predicate set is indexed, not just the predicate that narrows the
867    /// population most. This includes `note_status`: selecting a status does not
868    /// imply a status index or a cap-proportional scan. Backends that cannot
869    /// preserve the shared snapshot or
870    /// work bound must fail closed.
871    async fn count_notes_filtered_bounded_in_snapshot(
872        &self,
873        _namespace: &str,
874        _filters: &[NoteFilter],
875        _cap: u32,
876    ) -> StorageResult<Vec<BoundedCount>> {
877        Err(crate::StorageError::Unsupported {
878            capability: crate::StorageCapability::Notes,
879            operation: "count_notes_filtered_bounded_in_snapshot".into(),
880            message: "this backend does not implement snapshot-consistent bounded note counts"
881                .into(),
882        })
883    }
884    /// Resolve a note id to its immutable insertion sequence.
885    async fn note_sequence(&self, _id: Uuid) -> StorageResult<Option<i64>> {
886        Err(crate::StorageError::Unsupported {
887            capability: crate::StorageCapability::Notes,
888            operation: "note_sequence".into(),
889            message: "this backend does not implement note insertion sequences".into(),
890        })
891    }
892    /// Query an immutable insertion-sequence keyset page with the same
893    /// predicates as [`Self::query_notes_filtered`].
894    async fn query_notes_filtered_after(
895        &self,
896        _namespace: &str,
897        _filter: &NoteFilter,
898        _after: Option<SeekCursor>,
899        _limit: u32,
900    ) -> StorageResult<SeekPage<Note>> {
901        Err(crate::StorageError::Unsupported {
902            capability: crate::StorageCapability::Notes,
903            operation: "query_notes_filtered_after".into(),
904            message: "this backend does not implement note seek pagination".into(),
905        })
906    }
907    /// Fetch up to `max_rows + 1` notes matching `filter` in a single
908    /// deterministically-ordered SQL statement, with no separate `COUNT(*)`
909    /// and no pagination loop.
910    ///
911    /// A single statement observes one consistent snapshot for its entire
912    /// execution, so the result cannot be split across a concurrent insert
913    /// the way a `COUNT(*)` followed by independent `LIMIT`/`OFFSET` pages
914    /// can. Callers detect the over-bound case by checking whether the
915    /// returned `Vec` has more than `max_rows` items — that means at least
916    /// `max_rows + 1` rows matched and the caller must reject the query
917    /// rather than silently return a truncated, possibly priority-incomplete
918    /// set.
919    async fn query_notes_filtered_bounded(
920        &self,
921        namespace: &str,
922        filter: &NoteFilter,
923        max_rows: u32,
924    ) -> StorageResult<Vec<Note>>;
925    /// Count notes in a namespace, optionally filtered by kind.
926    async fn count_notes(&self, namespace: &str, kind: Option<&str>) -> StorageResult<u64>;
927    /// Count notes across the given namespaces, optionally filtered by kind.
928    /// The default preserves compatibility by summing the existing
929    /// single-namespace operation; SQL backends should override this with one
930    /// `IN` aggregate.
931    async fn count_notes_in_namespaces(
932        &self,
933        namespaces: &[String],
934        kind: Option<&str>,
935    ) -> StorageResult<u64> {
936        let mut total = 0;
937        for namespace in namespaces {
938            total += self.count_notes(namespace, kind).await?;
939        }
940        Ok(total)
941    }
942
943    /// Attempt to insert a note without overwriting an existing row.
944    ///
945    /// Returns `true` when the row was newly written.  Returns `false` only
946    /// when a live note with the same non-empty `external_id` already exists in
947    /// the same namespace and kind (confirmed dedup hit).  Any other constraint
948    /// violation (e.g. a primary key collision) is surfaced as a `StorageError`
949    /// so that callers do not misinterpret unexpected failures as deduplication.
950    async fn try_insert_note(&self, note: Note) -> StorageResult<bool>;
951
952    /// Atomically insert an ingest note and the blob attachments owned by it.
953    /// A deduplicated note writes no attachments; callers must inspect the
954    /// existing note before repairing a legacy missing role.
955    async fn try_insert_note_with_attachments(
956        &self,
957        _note: Note,
958        _attachments: Vec<crate::Attachment>,
959    ) -> StorageResult<bool> {
960        Err(crate::StorageError::Unsupported {
961            capability: crate::StorageCapability::Notes,
962            operation: "try_insert_note_with_attachments".into(),
963            message: "this backend cannot atomically insert note attachments".into(),
964        })
965    }
966
967    /// Fetch multiple notes by UUID in a single call.
968    async fn get_notes_batch(&self, ids: &[Uuid]) -> StorageResult<Vec<Note>> {
969        let mut out = Vec::with_capacity(ids.len());
970        for &id in ids {
971            if let Some(n) = self.get_note(id).await? {
972                out.push(n);
973            }
974        }
975        Ok(out)
976    }
977
978    /// Fetch multiple notes, including soft-deleted rows, for mutation policy checks.
979    /// Missing IDs are omitted; callers correlate rows by ID rather than result order.
980    async fn get_notes_batch_including_deleted(&self, ids: &[Uuid]) -> StorageResult<Vec<Note>> {
981        let mut out = Vec::with_capacity(ids.len());
982        for &id in ids {
983            if let Some(note) = self.get_note_including_deleted(id).await? {
984                out.push(note);
985            }
986        }
987        Ok(out)
988    }
989
990    /// Fetch only the columns needed for note visibility checks by UUID.
991    /// Missing IDs are omitted; soft-deleted rows retain their deletion time.
992    async fn get_note_visibility_batch(&self, ids: &[Uuid]) -> StorageResult<Vec<NoteVisibility>> {
993        let mut out = Vec::with_capacity(ids.len());
994        for &id in ids {
995            if let Some(note) = self.get_note_including_deleted(id).await? {
996                out.push(NoteVisibility {
997                    id: note.id,
998                    namespace: note.namespace,
999                    deleted_at: note.deleted_at,
1000                });
1001            }
1002        }
1003        Ok(out)
1004    }
1005}
1006
1007#[cfg(test)]
1008mod note_status_selector_contract_tests {
1009    use super::*;
1010
1011    #[test]
1012    fn selector_wire_values_and_exact_status_matching_are_closed() {
1013        for (selector, wire) in [
1014            (NoteStatusSelector::Active, "active"),
1015            (NoteStatusSelector::Archived, "archived"),
1016            (NoteStatusSelector::Any, "any"),
1017        ] {
1018            assert_eq!(selector.as_str(), wire);
1019            assert_eq!(
1020                serde_json::to_value(selector).unwrap(),
1021                Value::String(wire.into())
1022            );
1023            assert_eq!(
1024                serde_json::from_value::<NoteStatusSelector>(Value::String(wire.into())).unwrap(),
1025                selector
1026            );
1027        }
1028        for invalid in ["Active", "deleted", "unknown", ""] {
1029            assert!(
1030                serde_json::from_value::<NoteStatusSelector>(Value::String(invalid.into()))
1031                    .is_err()
1032            );
1033        }
1034        assert!(NoteStatusSelector::Active.matches("active"));
1035        assert!(!NoteStatusSelector::Active.matches("archived"));
1036        assert!(!NoteStatusSelector::Active.matches("ACTIVE"));
1037        assert!(NoteStatusSelector::Archived.matches("archived"));
1038        assert!(!NoteStatusSelector::Archived.matches("active"));
1039        assert!(NoteStatusSelector::Any.matches("deleted"));
1040        assert!(NoteStatusSelector::Any.matches("unrecognized-stored-status"));
1041    }
1042
1043    #[test]
1044    fn raw_filter_is_neutral_and_defaulting_preserves_explicit_status() {
1045        let legacy: NoteFilter = serde_json::from_value(serde_json::json!({
1046            "kind": null, "order_by": null, "min_created_at": null
1047        }))
1048        .unwrap();
1049        assert_eq!(legacy.note_status, None);
1050        assert_eq!(NoteFilter::default().note_status, None);
1051        assert_eq!(
1052            legacy
1053                .with_default_note_status(NoteStatusSelector::Active)
1054                .note_status,
1055            Some(NoteStatusSelector::Active)
1056        );
1057        for explicit in [
1058            NoteStatusSelector::Active,
1059            NoteStatusSelector::Archived,
1060            NoteStatusSelector::Any,
1061        ] {
1062            let filter = NoteFilter {
1063                note_status: Some(explicit),
1064                ..Default::default()
1065            }
1066            .with_default_note_status(NoteStatusSelector::Active);
1067            assert_eq!(filter.note_status, Some(explicit));
1068            let decoded: NoteFilter =
1069                serde_json::from_value(serde_json::to_value(filter).unwrap()).unwrap();
1070            assert_eq!(decoded.note_status, Some(explicit));
1071        }
1072    }
1073}