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}