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