Skip to main content

simbad_resolver/cache/
redb.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5//! Single redb-backed [`Cache`] + [`Queue`], durable (file) or ephemeral
6//! (in-memory).
7//!
8//! # Table design
9//!
10//! redb keeps keys sorted; every table is keyed by a `&str` or `&str`-encoded
11//! id and stores a `serde_json` blob, mirroring the in-memory backend's
12//! indexes:
13//!
14//! - `targets` — `id (uuid) → StoredTarget` (the canonical row, aliases
15//!   excluded). Dedup by `simbad_oid` and lookup-by-oid scan this table (the
16//!   oid lives inside the row, so no separate oid index can go stale).
17//! - `aliases` — `alias_id (uuid) → StoredAlias { target_id, alias }`, the
18//!   single source of truth for every alias. `get_by_normalized`, `search`, and
19//!   per-target assembly scan this table (a local typeahead cache is small, and
20//!   a full scan matches the reference backend's behaviour exactly).
21//! - `pending` — `id → StoredPending`, the batch queue; a monotonic `seq`
22//!   (allocated from `meta`) gives `claim_pending` its approximate-FIFO order.
23//! - `meta` — `&str → u64`; holds the next pending sequence number.
24//!
25//! redb is synchronous; the async trait methods run each unit of work inside
26//! [`tokio::task::spawn_blocking`], moving a cloned `Arc<Database>` in.
27
28use std::collections::{HashMap, HashSet};
29use std::path::Path;
30use std::sync::Arc;
31
32use redb::{Database, ReadableDatabase, ReadableTable, TableDefinition};
33use serde::{Deserialize, Serialize};
34use uuid::Uuid;
35
36use super::{
37    Cache, CacheError, CachedTarget, PendingItem, PendingState, Queue, QueueError, SearchHit,
38    UpsertOutcome, RANK_EXACT, RANK_PREFIX, RANK_SUBSTRING,
39};
40use crate::identity::target_id_from_designation;
41use crate::normalize::normalize;
42use crate::types::{AliasKind, ObjectType, ResolvedAlias, ResolvedIdentity, TargetSource};
43
44const TARGETS: TableDefinition<&str, &[u8]> = TableDefinition::new("targets");
45const ALIASES: TableDefinition<&str, &[u8]> = TableDefinition::new("aliases");
46const PENDING: TableDefinition<&str, &[u8]> = TableDefinition::new("pending");
47const META: TableDefinition<&str, u64> = TableDefinition::new("meta");
48const PENDING_SEQ_KEY: &str = "pending_seq";
49
50/// Map any `Display` error (redb, serde, join) to a [`CacheError::Backend`].
51fn cache_err<E: std::fmt::Display>(e: E) -> CacheError {
52    CacheError::Backend(e.to_string())
53}
54
55/// Map any `Display` error (redb, serde, join) to a [`QueueError::Backend`].
56fn queue_err<E: std::fmt::Display>(e: E) -> QueueError {
57    QueueError::Backend(e.to_string())
58}
59
60/// The current time as an RFC 3339 timestamp (UTC).
61fn now_iso() -> String {
62    time::OffsetDateTime::now_utc()
63        .format(&time::format_description::well_known::Rfc3339)
64        .expect("Rfc3339 format is always valid for OffsetDateTime")
65}
66
67// ── Persisted row structs ─────────────────────────────────────────────────────
68
69/// A canonical target row (aliases excluded — those live in the `aliases`
70/// table, keyed independently so `remove_user_alias` can address one).
71#[derive(Serialize, Deserialize)]
72struct StoredTarget {
73    simbad_oid: Option<i64>,
74    primary_designation: String,
75    common_name: Option<String>,
76    object_type: ObjectType,
77    otype_raw: String,
78    ra_deg: f64,
79    dec_deg: f64,
80    /// Johnson V magnitude when known. `#[serde(default)]` so target rows
81    /// written before this field existed still deserialize (as `None`).
82    #[serde(default)]
83    v_mag: Option<f64>,
84    source: TargetSource,
85    resolved_at: String,
86}
87
88impl StoredTarget {
89    fn from_identity(identity: &ResolvedIdentity) -> Self {
90        Self {
91            simbad_oid: identity.simbad_oid,
92            primary_designation: identity.primary_designation.clone(),
93            common_name: identity.common_name.clone(),
94            object_type: identity.object_type,
95            otype_raw: identity.otype_raw.clone(),
96            ra_deg: identity.ra_deg,
97            dec_deg: identity.dec_deg,
98            v_mag: identity.v_mag,
99            source: identity.source,
100            resolved_at: now_iso(),
101        }
102    }
103
104    fn into_target(self, id: Uuid, aliases: Vec<ResolvedAlias>) -> CachedTarget {
105        CachedTarget {
106            id,
107            simbad_oid: self.simbad_oid,
108            primary_designation: self.primary_designation,
109            common_name: self.common_name,
110            object_type: self.object_type,
111            otype_raw: self.otype_raw,
112            ra_deg: self.ra_deg,
113            dec_deg: self.dec_deg,
114            v_mag: self.v_mag,
115            source: self.source,
116            resolved_at: self.resolved_at,
117            aliases,
118        }
119    }
120}
121
122/// One alias row: a [`ResolvedAlias`] owned by `target_id`.
123#[derive(Serialize, Deserialize)]
124struct StoredAlias {
125    target_id: String,
126    alias: ResolvedAlias,
127}
128
129/// One queued item. `state` is the [`PendingState`] wire string; `seq` is the
130/// monotonic insertion order used to approximate FIFO in `claim_pending`.
131#[derive(Serialize, Deserialize)]
132struct StoredPending {
133    query: String,
134    state: String,
135    attempts: i64,
136    target_id: Option<String>,
137    seq: u64,
138}
139
140impl StoredPending {
141    fn into_item(self, id: String) -> Result<PendingItem, QueueError> {
142        let state = PendingState::from_wire(&self.state)
143            .ok_or_else(|| QueueError::InvalidState(self.state.clone()))?;
144        let target_id = self
145            .target_id
146            .map(|t| Uuid::parse_str(&t).map_err(|e| QueueError::InvalidUuid(t.clone(), e)))
147            .transpose()?;
148        Ok(PendingItem { id, query: self.query, state, attempts: self.attempts, target_id })
149    }
150}
151
152// ── Store ─────────────────────────────────────────────────────────────────────
153
154/// Write-transaction durability [`Cache::upsert_batch`] uses, configured once
155/// when a [`Store`] is opened (see [`Store::open_with`]) — not per call.
156/// Maps to `redb::Durability`: `Durable` -> `Immediate`, `Eventual` -> `None`.
157/// Single-item [`Cache::upsert`] always stays `Durable` regardless of this
158/// setting — point writes should stay durable; only a bulk batch load is
159/// worth trading that away.
160///
161/// Per redb's docs, a `None`-durability commit is visible to later
162/// reads/writes against the same open [`Database`] immediately, but "will not
163/// be persisted to disk unless followed by a commit with
164/// [`redb::Durability::Immediate`]" — so **only an unclean process
165/// termination** (a real crash/power-loss) *before* that later durable commit
166/// can roll it back. A clean shutdown is not at risk: redb's [`Database`]
167/// flushes and finalizes its on-disk header on `Drop` regardless of the last
168/// commit's durability, so an `Eventual` write left uncommitted-durably at
169/// process exit is still persisted once the process exits normally — the gap
170/// [`RedbCache::flush`] closes is the crash window *while the `Database`
171/// stays open*, not "forgetting to flush before exit".
172///
173/// Intended usage for a chunked bulk load (nightwatch-astro/alm#695: a
174/// 13k-entry seed warm split into e.g. 1000-entry chunks): open the store
175/// with `Eventual`, call [`Cache::upsert_batch`] once per chunk (none of them
176/// fsync), then call [`RedbCache::flush`] once right after the last chunk —
177/// don't wait for the store to close naturally, since it may stay open for
178/// the rest of the process's lifetime. redb commits are cumulative — each
179/// transaction's root builds on the last — so that one fsync persists every
180/// chunk, not just the last one.
181#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
182pub enum BatchDurability {
183    /// Every `upsert_batch` commit is fsync'd — today's only behavior.
184    #[default]
185    Durable,
186    /// `upsert_batch` commits skip the fsync; call [`RedbCache::flush`] once
187    /// after the last chunk to persist all of them in a single fsync.
188    Eventual,
189}
190
191/// An open redb database shared by a [`RedbCache`] and a [`RedbQueue`].
192///
193/// Cloning is cheap (an `Arc` handle over one `redb::Database`), so
194/// [`Self::cache`] / [`Self::queue`] hand out independent wrappers sharing the
195/// same underlying database.
196///
197/// [`Store::in_memory`] opens an ephemeral database, so this example is fully
198/// runnable with no filesystem access. Share one [`Store`] between a
199/// [`crate::SimbadResolver`] (via [`crate::CacheBackend::custom`]) and a
200/// [`crate::BatchResolver`] to have both operate over the same rows.
201///
202/// ```
203/// use simbad_resolver::Store;
204///
205/// # fn demo() -> Result<(), simbad_resolver::CacheError> {
206/// let store = Store::in_memory()?;
207/// let cache = store.cache(); // implements `Cache`
208/// let queue = store.queue(); // implements `Queue`
209/// # let _ = (cache, queue);
210/// # Ok(()) }
211/// ```
212#[derive(Clone)]
213pub struct Store {
214    db: Arc<Database>,
215    bulk_durability: BatchDurability,
216}
217
218impl Store {
219    /// Open (creating if missing) a durable, file-backed store at `path`,
220    /// with the default [`BatchDurability::Durable`] bulk-load policy —
221    /// exactly today's behavior. See [`Store::open_with`] to opt into
222    /// [`BatchDurability::Eventual`] batch loads.
223    ///
224    /// # Errors
225    ///
226    /// Returns [`CacheError::Backend`] if the database cannot be opened or its
227    /// tables cannot be initialised.
228    ///
229    /// ```
230    /// use simbad_resolver::Store;
231    ///
232    /// # fn run() -> Result<(), simbad_resolver::CacheError> {
233    /// let path = std::env::temp_dir().join("simbad-resolver-doctest-store-open.redb");
234    /// let store = Store::open(&path)?; // creates the file if missing
235    /// assert!(path.exists());
236    /// # let _ = store;
237    /// # let _ = std::fs::remove_file(&path);
238    /// # Ok(()) }
239    /// ```
240    pub fn open(path: impl AsRef<Path>) -> Result<Self, CacheError> {
241        Self::open_with(path, BatchDurability::default())
242    }
243
244    /// Like [`Store::open`], but configuring the [`BatchDurability`] every
245    /// [`Cache::upsert_batch`] call against this store uses.
246    ///
247    /// # Errors
248    ///
249    /// Returns [`CacheError::Backend`] if the database cannot be opened or its
250    /// tables cannot be initialised.
251    pub fn open_with(
252        path: impl AsRef<Path>,
253        bulk_durability: BatchDurability,
254    ) -> Result<Self, CacheError> {
255        let db = Database::create(path).map_err(cache_err)?;
256        init_tables(&db)?;
257        Ok(Self { db: Arc::new(db), bulk_durability })
258    }
259
260    /// Open a fresh, ephemeral in-memory store (nothing persisted to disk),
261    /// with the default [`BatchDurability::Durable`] bulk-load policy.
262    ///
263    /// [`BatchDurability::Eventual`] only matters for a file-backed store
264    /// (there's no "reopen after a crash" scenario for an in-memory one), so
265    /// unlike [`Store::open`] this has no `_with` variant; add one if that
266    /// changes.
267    ///
268    /// # Errors
269    ///
270    /// Returns [`CacheError::Backend`] if the in-memory database cannot be
271    /// created or its tables cannot be initialised.
272    pub fn in_memory() -> Result<Self, CacheError> {
273        let db = Database::builder()
274            .create_with_backend(redb::backends::InMemoryBackend::new())
275            .map_err(cache_err)?;
276        init_tables(&db)?;
277        Ok(Self { db: Arc::new(db), bulk_durability: BatchDurability::default() })
278    }
279
280    /// A [`RedbCache`] over this store's database, inheriting its configured
281    /// [`BatchDurability`].
282    #[must_use]
283    pub fn cache(&self) -> RedbCache {
284        RedbCache { db: self.db.clone(), bulk_durability: self.bulk_durability }
285    }
286
287    /// A [`RedbQueue`] over this store's database.
288    #[must_use]
289    pub fn queue(&self) -> RedbQueue {
290        RedbQueue { db: self.db.clone() }
291    }
292}
293
294/// Create every table up front so later read transactions always find them
295/// (redb errors on `open_table` for a table that was never written).
296fn init_tables(db: &Database) -> Result<(), CacheError> {
297    let w = db.begin_write().map_err(cache_err)?;
298    {
299        w.open_table(TARGETS).map_err(cache_err)?;
300        w.open_table(ALIASES).map_err(cache_err)?;
301        w.open_table(PENDING).map_err(cache_err)?;
302        w.open_table(META).map_err(cache_err)?;
303    }
304    w.commit().map_err(cache_err)?;
305    Ok(())
306}
307
308/// The durable/ephemeral redb-backed [`Cache`].
309#[derive(Clone)]
310pub struct RedbCache {
311    db: Arc<Database>,
312    bulk_durability: BatchDurability,
313}
314
315/// The durable/ephemeral redb-backed [`Queue`].
316#[derive(Clone)]
317pub struct RedbQueue {
318    db: Arc<Database>,
319}
320
321// ── Cache sync operations ─────────────────────────────────────────────────────
322
323/// Load every alias owned by `target_id`, sorted by display form.
324fn aliases_for(db: &Database, target_id: &str) -> Result<Vec<ResolvedAlias>, CacheError> {
325    let txn = db.begin_read().map_err(cache_err)?;
326    let table = txn.open_table(ALIASES).map_err(cache_err)?;
327    let mut aliases = Vec::new();
328    for entry in table.iter().map_err(cache_err)? {
329        let (_, v) = entry.map_err(cache_err)?;
330        let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
331        if sa.target_id == target_id {
332            aliases.push(sa.alias);
333        }
334    }
335    aliases.sort_by(|a, b| a.alias.cmp(&b.alias));
336    Ok(aliases)
337}
338
339fn get_by_id(db: &Database, id: Uuid) -> Result<Option<CachedTarget>, CacheError> {
340    let id_str = id.to_string();
341    let txn = db.begin_read().map_err(cache_err)?;
342    let targets = txn.open_table(TARGETS).map_err(cache_err)?;
343    let Some(bytes) = targets.get(id_str.as_str()).map_err(cache_err)? else {
344        return Ok(None);
345    };
346    let st: StoredTarget = serde_json::from_slice(bytes.value()).map_err(cache_err)?;
347    drop(bytes);
348    let aliases = aliases_for(db, &id_str)?;
349    Ok(Some(st.into_target(id, aliases)))
350}
351
352fn get_by_simbad_oid(db: &Database, oid: i64) -> Result<Option<CachedTarget>, CacheError> {
353    let found = {
354        let txn = db.begin_read().map_err(cache_err)?;
355        let targets = txn.open_table(TARGETS).map_err(cache_err)?;
356        let mut hit: Option<String> = None;
357        for entry in targets.iter().map_err(cache_err)? {
358            let (k, v) = entry.map_err(cache_err)?;
359            let st: StoredTarget = serde_json::from_slice(v.value()).map_err(cache_err)?;
360            if st.simbad_oid == Some(oid) {
361                hit = Some(k.value().to_string());
362                break;
363            }
364        }
365        hit
366    };
367    match found {
368        None => Ok(None),
369        Some(id_str) => {
370            let id = Uuid::parse_str(&id_str).map_err(|e| CacheError::InvalidUuid(id_str, e))?;
371            get_by_id(db, id)
372        }
373    }
374}
375
376fn get_by_normalized(db: &Database, normalized: &str) -> Result<Option<CachedTarget>, CacheError> {
377    let found = {
378        let txn = db.begin_read().map_err(cache_err)?;
379        let table = txn.open_table(ALIASES).map_err(cache_err)?;
380        let mut hit: Option<String> = None;
381        for entry in table.iter().map_err(cache_err)? {
382            let (_, v) = entry.map_err(cache_err)?;
383            let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
384            if sa.alias.normalized == normalized {
385                hit = Some(sa.target_id);
386                break;
387            }
388        }
389        hit
390    };
391    match found {
392        None => Ok(None),
393        Some(id_str) => {
394            let id = Uuid::parse_str(&id_str).map_err(|e| CacheError::InvalidUuid(id_str, e))?;
395            get_by_id(db, id)
396        }
397    }
398}
399
400/// The best-ranked alias hit seen so far for one target during search dedup.
401struct Best {
402    alias: String,
403    normalized_len: usize,
404    rank: u8,
405}
406
407impl Best {
408    /// A lower rank wins; ties break on the shorter matched alias.
409    fn is_better_than(&self, other: &Self) -> bool {
410        (self.rank, self.normalized_len) < (other.rank, other.normalized_len)
411    }
412}
413
414fn search(db: &Database, query: &str, limit: usize) -> Result<Vec<SearchHit>, CacheError> {
415    let q = normalize(query);
416    if q.is_empty() || limit == 0 {
417        return Ok(Vec::new());
418    }
419
420    let mut best_by_target: HashMap<String, Best> = HashMap::new();
421    {
422        let txn = db.begin_read().map_err(cache_err)?;
423        let table = txn.open_table(ALIASES).map_err(cache_err)?;
424        for entry in table.iter().map_err(cache_err)? {
425            let (_, v) = entry.map_err(cache_err)?;
426            let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
427            let normalized = &sa.alias.normalized;
428            let rank = if *normalized == q {
429                RANK_EXACT
430            } else if normalized.starts_with(&q) {
431                RANK_PREFIX
432            } else if normalized.contains(&q) {
433                RANK_SUBSTRING
434            } else {
435                continue;
436            };
437            let candidate =
438                Best { alias: sa.alias.alias.clone(), normalized_len: normalized.len(), rank };
439            match best_by_target.entry(sa.target_id) {
440                std::collections::hash_map::Entry::Occupied(mut e) => {
441                    if candidate.is_better_than(e.get()) {
442                        e.insert(candidate);
443                    }
444                }
445                std::collections::hash_map::Entry::Vacant(e) => {
446                    e.insert(candidate);
447                }
448            }
449        }
450    }
451
452    let mut ranked: Vec<(String, Best)> = best_by_target.into_iter().collect();
453    ranked.sort_by(|(_, a), (_, b)| {
454        (a.rank, a.normalized_len, a.alias.as_str()).cmp(&(
455            b.rank,
456            b.normalized_len,
457            b.alias.as_str(),
458        ))
459    });
460    ranked.truncate(limit);
461
462    let mut hits = Vec::with_capacity(ranked.len());
463    for (target_id, best) in ranked {
464        let id = Uuid::parse_str(&target_id).map_err(|e| CacheError::InvalidUuid(target_id, e))?;
465        if let Some(target) = get_by_id(db, id)? {
466            hits.push(SearchHit { target, matched_alias: best.alias, rank: best.rank });
467        }
468    }
469    Ok(hits)
470}
471
472/// How [`rewrite_aliases`] finds a target's current alias row ids to retire.
473///
474/// Mirrors [`OidLookup`]: `Scan` (single-item `upsert`, one call so an O(n)
475/// walk of `aliases` is fine) vs. `Index` (`upsert_batch`, an O(1) lookup
476/// against a batch-local `target_id -> alias ids` index built once up front
477/// by [`build_alias_index`] and kept in sync). Without this, `upsert_batch`'s
478/// oid-index fix alone still left this scan re-walking the (growing)
479/// `aliases` table once per entry — the other half of alm#695's O(n²).
480enum AliasLookup<'a> {
481    Scan,
482    Index(&'a mut HashMap<String, Vec<String>>),
483}
484
485/// Replace all alias rows for `target_id` wholesale, ensuring the primary
486/// designation is present as a `designation` alias and deduping by normalized
487/// form (mirrors the in-memory backend's `rewrite_aliases`).
488fn rewrite_aliases(
489    w: &redb::WriteTransaction,
490    target_id: &str,
491    identity: &ResolvedIdentity,
492    alias_lookup: &mut AliasLookup,
493) -> Result<(), CacheError> {
494    let mut table = w.open_table(ALIASES).map_err(cache_err)?;
495
496    let stale: Vec<String> = match alias_lookup {
497        AliasLookup::Scan => {
498            #[cfg(test)]
499            FULL_TABLE_SCAN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
500            let mut keys = Vec::new();
501            for entry in table.iter().map_err(cache_err)? {
502                let (k, v) = entry.map_err(cache_err)?;
503                let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
504                if sa.target_id == target_id {
505                    keys.push(k.value().to_string());
506                }
507            }
508            keys
509        }
510        AliasLookup::Index(index) => index.remove(target_id).unwrap_or_default(),
511    };
512    for k in &stale {
513        table.remove(k.as_str()).map_err(cache_err)?;
514    }
515
516    let mut aliases = identity.aliases.clone();
517    let primary_norm = normalize(&identity.primary_designation);
518    if !aliases.iter().any(|a| a.normalized == primary_norm) {
519        aliases
520            .push(ResolvedAlias::new(identity.primary_designation.clone(), AliasKind::Designation));
521    }
522
523    let mut seen = HashSet::with_capacity(aliases.len());
524    let mut written = Vec::with_capacity(aliases.len());
525    for alias in aliases {
526        if !seen.insert(alias.normalized.clone()) {
527            continue; // tolerate duplicate normalized forms within one identity
528        }
529        let alias_id = Uuid::new_v4().to_string();
530        let sa = StoredAlias { target_id: target_id.to_owned(), alias };
531        let bytes = serde_json::to_vec(&sa).map_err(cache_err)?;
532        table.insert(alias_id.as_str(), bytes.as_slice()).map_err(cache_err)?;
533        written.push(alias_id);
534    }
535
536    if let AliasLookup::Index(index) = alias_lookup {
537        index.insert(target_id.to_owned(), written);
538    }
539    Ok(())
540}
541
542/// One full scan of `aliases`, indexing every row's owning `target_id`.
543/// `upsert_batch` runs this exactly once per batch — the alias-side twin of
544/// [`build_oid_index`], fixing the other half of the O(n²) blowup.
545fn build_alias_index(
546    w: &redb::WriteTransaction,
547) -> Result<HashMap<String, Vec<String>>, CacheError> {
548    #[cfg(test)]
549    FULL_TABLE_SCAN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
550    let table = w.open_table(ALIASES).map_err(cache_err)?;
551    let mut index: HashMap<String, Vec<String>> = HashMap::new();
552    for entry in table.iter().map_err(cache_err)? {
553        let (k, v) = entry.map_err(cache_err)?;
554        let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
555        index.entry(sa.target_id).or_default().push(k.value().to_string());
556    }
557    Ok(index)
558}
559
560/// Test-only: counts every full-table scan done to find a target by oid
561/// (`OidLookup::Scan` / [`build_oid_index`]) or a target's aliases
562/// (`AliasLookup::Scan` / [`build_alias_index`]), so a unit test can assert
563/// `upsert_batch` collapses those scans to one each regardless of batch size
564/// (see the `upsert_batch_*` tests below). Zero cost outside test builds.
565#[cfg(test)]
566static FULL_TABLE_SCAN_COUNT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
567
568/// How [`upsert_within`] finds a row that already carries a given SIMBAD oid.
569///
570/// A single [`upsert`] call scans (`Scan`): one call, so an O(n) walk of
571/// `targets` is fine and this keeps that path byte-for-byte what it always
572/// was. [`upsert_batch`] instead builds one O(1) `oid -> (id, source)` index
573/// up front (`Index`, via [`build_oid_index`]) and keeps it in sync as the
574/// batch writes — the fix for nightwatch-astro/alm#695's O(n²) blowup: an
575/// n-entry batch used to re-scan the (growing) table once per entry.
576enum OidLookup<'a> {
577    /// Full-table scan, once per call.
578    Scan,
579    /// O(1) lookup against a batch-local index, updated after every write so
580    /// later entries in the same batch see accurate dedup state.
581    Index(&'a mut HashMap<i64, (String, TargetSource)>),
582}
583
584/// Upsert one identity against tables already open in `w`, without
585/// committing. Shared by [`upsert`] (one identity, one transaction) and
586/// [`upsert_batch`] (many identities, one transaction) so a batch gets the
587/// exact same per-entry dedup + precedence decision as a sequential loop of
588/// single upserts — including deduping against an earlier identity of the
589/// same batch, since reads here see this transaction's own uncommitted
590/// writes.
591fn upsert_within(
592    w: &redb::WriteTransaction,
593    identity: &ResolvedIdentity,
594    namespace: &Uuid,
595    oid_lookup: &mut OidLookup,
596    alias_lookup: &mut AliasLookup,
597) -> Result<(Uuid, UpsertOutcome), CacheError> {
598    let derived_id =
599        target_id_from_designation(namespace, &identity.primary_designation).to_string();
600
601    // `existing`'s third field is the row's oid *before* this write (`None` if
602    // it never had one), so the tail below can retire a stale index entry if
603    // this write changes or clears the row's oid.
604    let (id_str, outcome, wrote_row, prior_oid) = {
605        let mut targets = w.open_table(TARGETS).map_err(cache_err)?;
606
607        // Find the row to upsert into: by oid when Some, else by derived id.
608        let mut existing: Option<(String, TargetSource, Option<i64>)> = None;
609        if let Some(oid) = identity.simbad_oid {
610            existing = match oid_lookup {
611                OidLookup::Scan => {
612                    #[cfg(test)]
613                    FULL_TABLE_SCAN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
614                    let mut found = None;
615                    for entry in targets.iter().map_err(cache_err)? {
616                        let (k, v) = entry.map_err(cache_err)?;
617                        let st: StoredTarget =
618                            serde_json::from_slice(v.value()).map_err(cache_err)?;
619                        if st.simbad_oid == Some(oid) {
620                            found = Some((k.value().to_string(), st.source, Some(oid)));
621                            break;
622                        }
623                    }
624                    found
625                }
626                OidLookup::Index(index) => {
627                    index.get(&oid).map(|(id, source)| (id.clone(), *source, Some(oid)))
628                }
629            };
630        }
631        if existing.is_none() {
632            if let Some(v) = targets.get(derived_id.as_str()).map_err(cache_err)? {
633                let st: StoredTarget = serde_json::from_slice(v.value()).map_err(cache_err)?;
634                existing = Some((derived_id.clone(), st.source, st.simbad_oid));
635            }
636        }
637
638        match existing {
639            Some((id, source, _)) if !identity.source.may_overwrite(source) => {
640                (id, UpsertOutcome::SkippedUserOverride, false, None)
641            }
642            Some((id, _, prior_oid)) => {
643                let bytes = serde_json::to_vec(&StoredTarget::from_identity(identity))
644                    .map_err(cache_err)?;
645                targets.insert(id.as_str(), bytes.as_slice()).map_err(cache_err)?;
646                (id, UpsertOutcome::Updated, true, prior_oid)
647            }
648            None => {
649                let bytes = serde_json::to_vec(&StoredTarget::from_identity(identity))
650                    .map_err(cache_err)?;
651                targets.insert(derived_id.as_str(), bytes.as_slice()).map_err(cache_err)?;
652                (derived_id.clone(), UpsertOutcome::Inserted, true, None)
653            }
654        }
655    };
656
657    if wrote_row {
658        rewrite_aliases(w, &id_str, identity, alias_lookup)?;
659        if let OidLookup::Index(index) = oid_lookup {
660            if prior_oid != identity.simbad_oid {
661                if let Some(stale) = prior_oid {
662                    index.remove(&stale);
663                }
664            }
665            if let Some(oid) = identity.simbad_oid {
666                index.insert(oid, (id_str.clone(), identity.source));
667            }
668        }
669    }
670
671    let id = Uuid::parse_str(&id_str).map_err(|e| CacheError::InvalidUuid(id_str, e))?;
672    Ok((id, outcome))
673}
674
675/// One full scan of `targets`, indexing every row that currently has an oid.
676/// `upsert_batch` runs this exactly once per batch (not once per entry) —
677/// that single scan is what turns an n-entry batch's total table-scan work
678/// from O(n²) back to O(n).
679fn build_oid_index(
680    w: &redb::WriteTransaction,
681) -> Result<HashMap<i64, (String, TargetSource)>, CacheError> {
682    #[cfg(test)]
683    FULL_TABLE_SCAN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
684    let targets = w.open_table(TARGETS).map_err(cache_err)?;
685    let mut index = HashMap::new();
686    for entry in targets.iter().map_err(cache_err)? {
687        let (k, v) = entry.map_err(cache_err)?;
688        let st: StoredTarget = serde_json::from_slice(v.value()).map_err(cache_err)?;
689        if let Some(oid) = st.simbad_oid {
690            index.insert(oid, (k.value().to_string(), st.source));
691        }
692    }
693    Ok(index)
694}
695
696/// Test-only: counts write transactions opened for an upsert (single or
697/// batch), so a unit test can assert `upsert_batch` collapses N transactions
698/// into 1 (see the `upsert_batch_*` tests below). Zero cost outside test
699/// builds.
700#[cfg(test)]
701static UPSERT_WRITE_TXN_COUNT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
702
703/// Begin the one write transaction an upsert (single or batch) runs in,
704/// counting it in test builds via [`UPSERT_WRITE_TXN_COUNT`].
705fn begin_upsert_txn(db: &Database) -> Result<redb::WriteTransaction, CacheError> {
706    #[cfg(test)]
707    UPSERT_WRITE_TXN_COUNT.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
708    db.begin_write().map_err(cache_err)
709}
710
711fn upsert(
712    db: &Database,
713    identity: &ResolvedIdentity,
714    namespace: &Uuid,
715) -> Result<(Uuid, UpsertOutcome), CacheError> {
716    let w = begin_upsert_txn(db)?;
717    let result =
718        upsert_within(&w, identity, namespace, &mut OidLookup::Scan, &mut AliasLookup::Scan)?;
719    w.commit().map_err(cache_err)?;
720    Ok(result)
721}
722
723/// Upsert every identity in `identities` in one write transaction (one
724/// backend commit total instead of one per entry — see `docs/adr/` and issue
725/// nightwatch-astro/alm#695 for why this matters for large seed warms), at
726/// the store's configured [`BatchDurability`] (see [`Store::open_with`]).
727///
728/// Per-entry semantics are identical to calling [`upsert`] in a loop: each
729/// entry is deduped/precedence-checked against both already-committed rows and
730/// rows written earlier in this same batch. If any entry errors, the whole
731/// transaction is dropped unread (redb aborts an uncommitted write
732/// transaction), so a batch either fully applies or leaves the store
733/// untouched.
734fn upsert_batch(
735    db: &Database,
736    identities: &[ResolvedIdentity],
737    namespace: &Uuid,
738    durability: BatchDurability,
739) -> Result<Vec<(Uuid, UpsertOutcome)>, CacheError> {
740    let mut w = begin_upsert_txn(db)?;
741    // Only touch durability for the non-default case, so the `Durable` path
742    // is byte-for-byte what it always was (no new fallible call on it).
743    if durability == BatchDurability::Eventual {
744        w.set_durability(redb::Durability::None).map_err(cache_err)?;
745    }
746    let mut oid_index = build_oid_index(&w)?;
747    let mut alias_index = build_alias_index(&w)?;
748    let mut results = Vec::with_capacity(identities.len());
749    for identity in identities {
750        results.push(upsert_within(
751            &w,
752            identity,
753            namespace,
754            &mut OidLookup::Index(&mut oid_index),
755            &mut AliasLookup::Index(&mut alias_index),
756        )?);
757    }
758    w.commit().map_err(cache_err)?;
759    Ok(results)
760}
761
762/// Force one fully durable (fsync'd) write commit, touching no data. redb
763/// commits are cumulative — each transaction's root builds on the last — so
764/// this persists every prior [`BatchDurability::Eventual`] `upsert_batch`
765/// commit too, not just anything new. See [`RedbCache::flush`].
766fn flush_durable(db: &Database) -> Result<(), CacheError> {
767    let w = db.begin_write().map_err(cache_err)?;
768    w.commit().map_err(cache_err)?;
769    Ok(())
770}
771
772fn add_user_alias(db: &Database, target_id: Uuid, alias: &str) -> Result<bool, CacheError> {
773    let normalized = normalize(alias);
774    if normalized.is_empty() {
775        return Ok(false);
776    }
777    let tid = target_id.to_string();
778    let w = db.begin_write().map_err(cache_err)?;
779    let inserted = {
780        let mut table = w.open_table(ALIASES).map_err(cache_err)?;
781        let exists = {
782            let mut found = false;
783            for entry in table.iter().map_err(cache_err)? {
784                let (_, v) = entry.map_err(cache_err)?;
785                let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
786                if sa.target_id == tid && sa.alias.normalized == normalized {
787                    found = true;
788                    break;
789                }
790            }
791            found
792        };
793        if exists {
794            false
795        } else {
796            let alias_id = Uuid::new_v4().to_string();
797            let sa = StoredAlias {
798                target_id: tid.clone(),
799                alias: ResolvedAlias::new(alias, AliasKind::User),
800            };
801            let bytes = serde_json::to_vec(&sa).map_err(cache_err)?;
802            table.insert(alias_id.as_str(), bytes.as_slice()).map_err(cache_err)?;
803            true
804        }
805    };
806    w.commit().map_err(cache_err)?;
807    Ok(inserted)
808}
809
810fn remove_user_alias(db: &Database, alias_id: &str) -> Result<bool, CacheError> {
811    let w = db.begin_write().map_err(cache_err)?;
812    let removed = {
813        let mut table = w.open_table(ALIASES).map_err(cache_err)?;
814        // Copy the row out so the read guard is dropped before the write borrow.
815        let existing = table.get(alias_id).map_err(cache_err)?.map(|v| v.value().to_vec());
816        match existing {
817            None => false,
818            Some(raw) => {
819                let sa: StoredAlias = serde_json::from_slice(&raw).map_err(cache_err)?;
820                if sa.alias.kind == AliasKind::User {
821                    table.remove(alias_id).map_err(cache_err)?;
822                    true
823                } else {
824                    false
825                }
826            }
827        }
828    };
829    w.commit().map_err(cache_err)?;
830    Ok(removed)
831}
832
833fn list(db: &Database) -> Result<Vec<CachedTarget>, CacheError> {
834    let txn = db.begin_read().map_err(cache_err)?;
835    let aliases_tbl = txn.open_table(ALIASES).map_err(cache_err)?;
836    let mut aliases_by: HashMap<String, Vec<ResolvedAlias>> = HashMap::new();
837    for entry in aliases_tbl.iter().map_err(cache_err)? {
838        let (_, v) = entry.map_err(cache_err)?;
839        let sa: StoredAlias = serde_json::from_slice(v.value()).map_err(cache_err)?;
840        aliases_by.entry(sa.target_id).or_default().push(sa.alias);
841    }
842
843    let targets = txn.open_table(TARGETS).map_err(cache_err)?;
844    let mut out = Vec::new();
845    for entry in targets.iter().map_err(cache_err)? {
846        let (k, v) = entry.map_err(cache_err)?;
847        let id_str = k.value().to_string();
848        let st: StoredTarget = serde_json::from_slice(v.value()).map_err(cache_err)?;
849        let id =
850            Uuid::parse_str(&id_str).map_err(|e| CacheError::InvalidUuid(id_str.clone(), e))?;
851        let mut aliases = aliases_by.remove(&id_str).unwrap_or_default();
852        aliases.sort_by(|a, b| a.alias.cmp(&b.alias));
853        out.push(st.into_target(id, aliases));
854    }
855    out.sort_by(|a, b| a.primary_designation.cmp(&b.primary_designation));
856    Ok(out)
857}
858
859#[async_trait::async_trait]
860impl Cache for RedbCache {
861    async fn get_by_id(&self, id: Uuid) -> Result<Option<CachedTarget>, CacheError> {
862        let db = self.db.clone();
863        tokio::task::spawn_blocking(move || get_by_id(&db, id)).await.map_err(cache_err)?
864    }
865
866    async fn get_by_simbad_oid(&self, oid: i64) -> Result<Option<CachedTarget>, CacheError> {
867        let db = self.db.clone();
868        tokio::task::spawn_blocking(move || get_by_simbad_oid(&db, oid)).await.map_err(cache_err)?
869    }
870
871    async fn get_by_normalized(
872        &self,
873        normalized: &str,
874    ) -> Result<Option<CachedTarget>, CacheError> {
875        let db = self.db.clone();
876        let normalized = normalized.to_owned();
877        tokio::task::spawn_blocking(move || get_by_normalized(&db, &normalized))
878            .await
879            .map_err(cache_err)?
880    }
881
882    async fn search(&self, query: &str, limit: usize) -> Result<Vec<SearchHit>, CacheError> {
883        let db = self.db.clone();
884        let query = query.to_owned();
885        tokio::task::spawn_blocking(move || search(&db, &query, limit)).await.map_err(cache_err)?
886    }
887
888    async fn upsert(
889        &self,
890        identity: &ResolvedIdentity,
891        namespace: &Uuid,
892    ) -> Result<(Uuid, UpsertOutcome), CacheError> {
893        let db = self.db.clone();
894        let identity = identity.clone();
895        let namespace = *namespace;
896        tokio::task::spawn_blocking(move || upsert(&db, &identity, &namespace))
897            .await
898            .map_err(cache_err)?
899    }
900
901    async fn upsert_batch(
902        &self,
903        identities: &[ResolvedIdentity],
904        namespace: &Uuid,
905    ) -> Result<Vec<(Uuid, UpsertOutcome)>, CacheError> {
906        let db = self.db.clone();
907        let identities = identities.to_vec();
908        let namespace = *namespace;
909        let durability = self.bulk_durability;
910        tokio::task::spawn_blocking(move || upsert_batch(&db, &identities, &namespace, durability))
911            .await
912            .map_err(cache_err)?
913    }
914
915    async fn add_user_alias(&self, target_id: Uuid, alias: &str) -> Result<bool, CacheError> {
916        let db = self.db.clone();
917        let alias = alias.to_owned();
918        tokio::task::spawn_blocking(move || add_user_alias(&db, target_id, &alias))
919            .await
920            .map_err(cache_err)?
921    }
922
923    async fn remove_user_alias(&self, alias_id: &str) -> Result<bool, CacheError> {
924        let db = self.db.clone();
925        let alias_id = alias_id.to_owned();
926        tokio::task::spawn_blocking(move || remove_user_alias(&db, &alias_id))
927            .await
928            .map_err(cache_err)?
929    }
930
931    async fn list(&self) -> Result<Vec<CachedTarget>, CacheError> {
932        let db = self.db.clone();
933        tokio::task::spawn_blocking(move || list(&db)).await.map_err(cache_err)?
934    }
935}
936
937impl RedbCache {
938    /// Force one fully durable (fsync'd) commit against this store, touching
939    /// no data. Inherent (not on the `Cache` trait) because durability is a
940    /// redb-specific, storage-engine concept, not a portable identity-store
941    /// operation — callers need a concrete [`RedbCache`] (via
942    /// [`Store::cache`]), not just `impl Cache`/`dyn Cache`.
943    ///
944    /// Call this once right after the last chunk of a
945    /// [`BatchDurability::Eventual`] bulk load (see [`Store::open_with`]) —
946    /// don't rely on the store closing naturally to persist those chunks, as
947    /// it may stay open for the rest of the process's lifetime and a crash
948    /// any time before it closes would lose everything since the last durable
949    /// commit (see [`BatchDurability`] for the full crash-vs-clean-shutdown
950    /// distinction). redb commits are cumulative, so this one fsync persists
951    /// every prior `Eventual` `upsert_batch` commit too, not just this call.
952    /// A no-op-but-safe-to-call if this store's bulk durability is
953    /// [`BatchDurability::Durable`] (every write already fsyncs on its own).
954    ///
955    /// # Errors
956    ///
957    /// [`CacheError::Backend`] if the (empty) transaction fails to commit.
958    pub async fn flush(&self) -> Result<(), CacheError> {
959        let db = self.db.clone();
960        tokio::task::spawn_blocking(move || flush_durable(&db)).await.map_err(cache_err)?
961    }
962}
963
964// ── Queue sync operations ─────────────────────────────────────────────────────
965
966fn enqueue(db: &Database, id: &str, query: &str) -> Result<(), QueueError> {
967    let w = db.begin_write().map_err(queue_err)?;
968    {
969        let mut pending = w.open_table(PENDING).map_err(queue_err)?;
970        if pending.get(id).map_err(queue_err)?.is_none() {
971            let mut meta = w.open_table(META).map_err(queue_err)?;
972            let seq = meta.get(PENDING_SEQ_KEY).map_err(queue_err)?.map_or(0, |g| g.value());
973            meta.insert(PENDING_SEQ_KEY, seq + 1).map_err(queue_err)?;
974            let sp = StoredPending {
975                query: query.to_owned(),
976                state: PendingState::Pending.as_wire().to_owned(),
977                attempts: 0,
978                target_id: None,
979                seq,
980            };
981            let bytes = serde_json::to_vec(&sp).map_err(queue_err)?;
982            pending.insert(id, bytes.as_slice()).map_err(queue_err)?;
983        }
984    }
985    w.commit().map_err(queue_err)?;
986    Ok(())
987}
988
989fn claim_pending(db: &Database, n: usize) -> Result<Vec<PendingItem>, QueueError> {
990    let txn = db.begin_read().map_err(queue_err)?;
991    let pending = txn.open_table(PENDING).map_err(queue_err)?;
992    let mut rows: Vec<(String, StoredPending)> = Vec::new();
993    for entry in pending.iter().map_err(queue_err)? {
994        let (k, v) = entry.map_err(queue_err)?;
995        let sp: StoredPending = serde_json::from_slice(v.value()).map_err(queue_err)?;
996        if sp.state == PendingState::Pending.as_wire() {
997            rows.push((k.value().to_string(), sp));
998        }
999    }
1000    rows.sort_by_key(|(_, sp)| sp.seq);
1001    rows.truncate(n);
1002    rows.into_iter().map(|(id, sp)| sp.into_item(id)).collect()
1003}
1004
1005/// Read-modify-write one pending row (a no-op if the id is absent).
1006fn update_pending(
1007    db: &Database,
1008    id: &str,
1009    mutate: impl FnOnce(&mut StoredPending),
1010) -> Result<(), QueueError> {
1011    let w = db.begin_write().map_err(queue_err)?;
1012    {
1013        let mut pending = w.open_table(PENDING).map_err(queue_err)?;
1014        // Copy the row out so the read guard is dropped before the write borrow.
1015        let existing = pending.get(id).map_err(queue_err)?.map(|v| v.value().to_vec());
1016        if let Some(raw) = existing {
1017            let mut sp: StoredPending = serde_json::from_slice(&raw).map_err(queue_err)?;
1018            mutate(&mut sp);
1019            let bytes = serde_json::to_vec(&sp).map_err(queue_err)?;
1020            pending.insert(id, bytes.as_slice()).map_err(queue_err)?;
1021        }
1022    }
1023    w.commit().map_err(queue_err)?;
1024    Ok(())
1025}
1026
1027fn get(db: &Database, id: &str) -> Result<Option<PendingItem>, QueueError> {
1028    let txn = db.begin_read().map_err(queue_err)?;
1029    let pending = txn.open_table(PENDING).map_err(queue_err)?;
1030    match pending.get(id).map_err(queue_err)? {
1031        None => Ok(None),
1032        Some(v) => {
1033            let sp: StoredPending = serde_json::from_slice(v.value()).map_err(queue_err)?;
1034            Ok(Some(sp.into_item(id.to_owned())?))
1035        }
1036    }
1037}
1038
1039fn pending_count(db: &Database) -> Result<usize, QueueError> {
1040    let txn = db.begin_read().map_err(queue_err)?;
1041    let pending = txn.open_table(PENDING).map_err(queue_err)?;
1042    let mut count = 0usize;
1043    for entry in pending.iter().map_err(queue_err)? {
1044        let (_, v) = entry.map_err(queue_err)?;
1045        let sp: StoredPending = serde_json::from_slice(v.value()).map_err(queue_err)?;
1046        if sp.state == PendingState::Pending.as_wire() {
1047            count += 1;
1048        }
1049    }
1050    Ok(count)
1051}
1052
1053#[async_trait::async_trait]
1054impl Queue for RedbQueue {
1055    async fn enqueue(&self, id: &str, query: &str) -> Result<(), QueueError> {
1056        let db = self.db.clone();
1057        let (id, query) = (id.to_owned(), query.to_owned());
1058        tokio::task::spawn_blocking(move || enqueue(&db, &id, &query)).await.map_err(queue_err)?
1059    }
1060
1061    async fn claim_pending(&self, n: usize) -> Result<Vec<PendingItem>, QueueError> {
1062        let db = self.db.clone();
1063        tokio::task::spawn_blocking(move || claim_pending(&db, n)).await.map_err(queue_err)?
1064    }
1065
1066    async fn mark_resolved(&self, id: &str, target_id: Uuid) -> Result<(), QueueError> {
1067        let db = self.db.clone();
1068        let id = id.to_owned();
1069        tokio::task::spawn_blocking(move || {
1070            update_pending(&db, &id, |sp| {
1071                PendingState::Resolved.as_wire().clone_into(&mut sp.state);
1072                sp.target_id = Some(target_id.to_string());
1073            })
1074        })
1075        .await
1076        .map_err(queue_err)?
1077    }
1078
1079    async fn mark_unresolved(&self, id: &str) -> Result<(), QueueError> {
1080        let db = self.db.clone();
1081        let id = id.to_owned();
1082        tokio::task::spawn_blocking(move || {
1083            update_pending(&db, &id, |sp| {
1084                PendingState::Unresolved.as_wire().clone_into(&mut sp.state);
1085                sp.attempts += 1;
1086            })
1087        })
1088        .await
1089        .map_err(queue_err)?
1090    }
1091
1092    async fn release(&self, id: &str) -> Result<(), QueueError> {
1093        let db = self.db.clone();
1094        let id = id.to_owned();
1095        tokio::task::spawn_blocking(move || {
1096            update_pending(&db, &id, |sp| {
1097                PendingState::Pending.as_wire().clone_into(&mut sp.state);
1098            })
1099        })
1100        .await
1101        .map_err(queue_err)?
1102    }
1103
1104    async fn get(&self, id: &str) -> Result<Option<PendingItem>, QueueError> {
1105        let db = self.db.clone();
1106        let id = id.to_owned();
1107        tokio::task::spawn_blocking(move || get(&db, &id)).await.map_err(queue_err)?
1108    }
1109
1110    async fn pending_count(&self) -> Result<usize, QueueError> {
1111        let db = self.db.clone();
1112        tokio::task::spawn_blocking(move || pending_count(&db)).await.map_err(queue_err)?
1113    }
1114}
1115
1116#[cfg(test)]
1117mod tests {
1118    //! Covers `remove_user_alias`, whose real-removal path needs an opaque
1119    //! alias id the public API never exposes — the dashmap backend tested this
1120    //! via internals too, so it lives here rather than in `tests/cache.rs`.
1121    use super::*;
1122
1123    fn m31() -> ResolvedIdentity {
1124        ResolvedIdentity {
1125            simbad_oid: Some(1_575_544),
1126            primary_designation: "M 31".to_owned(),
1127            common_name: Some("Andromeda Galaxy".to_owned()),
1128            object_type: ObjectType::Galaxy,
1129            otype_raw: "G".to_owned(),
1130            ra_deg: 10.684_708,
1131            dec_deg: 41.268_75,
1132            v_mag: Some(3.44),
1133            aliases: vec![
1134                ResolvedAlias::new("M 31", AliasKind::Designation),
1135                ResolvedAlias::new("NGC 224", AliasKind::Designation),
1136                ResolvedAlias::new("Andromeda Galaxy", AliasKind::CommonName),
1137            ],
1138            source: TargetSource::Resolved,
1139        }
1140    }
1141
1142    /// Recover an opaque alias id by its display form (test-only introspection).
1143    fn alias_id_of(db: &Database, display: &str) -> String {
1144        let txn = db.begin_read().unwrap();
1145        let table = txn.open_table(ALIASES).unwrap();
1146        for entry in table.iter().unwrap() {
1147            let (k, v) = entry.unwrap();
1148            let sa: StoredAlias = serde_json::from_slice(v.value()).unwrap();
1149            if sa.alias.alias == display {
1150                return k.value().to_string();
1151            }
1152        }
1153        panic!("alias {display:?} not found");
1154    }
1155
1156    /// Serializes every test in this module that calls `upsert`/`upsert_batch`
1157    /// against [`UPSERT_WRITE_TXN_COUNT`]/[`FULL_TABLE_SCAN_COUNT`] readers —
1158    /// `cargo test` runs tests on concurrent threads within one binary, and
1159    /// those counters are process-wide statics, so an unguarded interleaving
1160    /// would flake the counts. `tokio::sync::Mutex` (not `std::sync::Mutex`)
1161    /// because the guard is held across `.await` points.
1162    static TXN_COUNT_GUARD: std::sync::LazyLock<tokio::sync::Mutex<()>> =
1163        std::sync::LazyLock::new(|| tokio::sync::Mutex::new(()));
1164
1165    #[tokio::test]
1166    async fn remove_user_alias_only_removes_user_kind() {
1167        let _guard = TXN_COUNT_GUARD.lock().await;
1168        let store = Store::in_memory().unwrap();
1169        let cache = store.cache();
1170        let ns = crate::identity::namespace("redb.tests");
1171        let (id, _) = cache.upsert(&m31(), &ns).await.unwrap();
1172        cache.add_user_alias(id, "M31 favorite").await.unwrap();
1173
1174        let user_alias_id = alias_id_of(&store.db, "M31 favorite");
1175        assert!(cache.remove_user_alias(&user_alias_id).await.unwrap());
1176        assert_eq!(cache.get_by_id(id).await.unwrap().unwrap().aliases.len(), 3);
1177
1178        // A designation alias's id must not be removable via remove_user_alias.
1179        let designation_id = alias_id_of(&store.db, "M 31");
1180        assert!(!cache.remove_user_alias(&designation_id).await.unwrap());
1181        assert_eq!(cache.get_by_id(id).await.unwrap().unwrap().aliases.len(), 3);
1182    }
1183
1184    /// `identities[i]` is a distinct target: distinct oid, designation, and
1185    /// aliases, so batching them never collides on dedup.
1186    fn distinct_identities(n: usize) -> Vec<ResolvedIdentity> {
1187        (0..n)
1188            .map(|i| {
1189                let idx = u32::try_from(i).expect("test batch sizes fit in u32");
1190                let designation = format!("Batch Target {i}");
1191                ResolvedIdentity {
1192                    simbad_oid: Some(9_000_000 + i64::from(idx)),
1193                    primary_designation: designation.clone(),
1194                    common_name: None,
1195                    object_type: ObjectType::Galaxy,
1196                    otype_raw: "G".to_owned(),
1197                    ra_deg: f64::from(idx % 360),
1198                    dec_deg: 0.0,
1199                    v_mag: None,
1200                    aliases: vec![ResolvedAlias::new(designation, AliasKind::Designation)],
1201                    source: TargetSource::Seed,
1202                }
1203            })
1204            .collect()
1205    }
1206
1207    #[tokio::test]
1208    async fn upsert_batch_uses_one_write_transaction_regardless_of_batch_size() {
1209        let _guard = TXN_COUNT_GUARD.lock().await;
1210        UPSERT_WRITE_TXN_COUNT.store(0, std::sync::atomic::Ordering::Relaxed);
1211
1212        let store = Store::in_memory().unwrap();
1213        let cache = store.cache();
1214        let ns = crate::identity::namespace("redb.tests.batch-txn-count");
1215        let identities = distinct_identities(25);
1216
1217        let results = cache.upsert_batch(&identities, &ns).await.unwrap();
1218        assert_eq!(results.len(), 25);
1219        assert_eq!(
1220            UPSERT_WRITE_TXN_COUNT.load(std::sync::atomic::Ordering::Relaxed),
1221            1,
1222            "one upsert_batch call of 25 identities must open exactly one write transaction"
1223        );
1224
1225        UPSERT_WRITE_TXN_COUNT.store(0, std::sync::atomic::Ordering::Relaxed);
1226        for identity in &identities {
1227            cache.upsert(identity, &ns).await.unwrap();
1228        }
1229        assert_eq!(
1230            UPSERT_WRITE_TXN_COUNT.load(std::sync::atomic::Ordering::Relaxed),
1231            25,
1232            "25 sequential upsert calls must open one write transaction each"
1233        );
1234    }
1235
1236    /// Regression guard for nightwatch-astro/alm#695's O(n²) defect:
1237    /// `upsert_within`'s old oid dedup *and* its `rewrite_aliases` call both
1238    /// re-scanned their whole (growing) table once per entry. `upsert_batch`
1239    /// must instead do exactly one full scan of each (`build_oid_index` +
1240    /// `build_alias_index`) per batch call, regardless of batch size —
1241    /// asserted here directly via the scan counter rather than by timing,
1242    /// since a count assertion can't flake on a slow CI runner.
1243    #[tokio::test]
1244    async fn upsert_batch_does_one_full_scan_per_table_regardless_of_batch_size() {
1245        let _guard = TXN_COUNT_GUARD.lock().await;
1246        FULL_TABLE_SCAN_COUNT.store(0, std::sync::atomic::Ordering::Relaxed);
1247
1248        let store = Store::in_memory().unwrap();
1249        let cache = store.cache();
1250        let ns = crate::identity::namespace("redb.tests.batch-scan-count");
1251        let identities = distinct_identities(50);
1252
1253        cache.upsert_batch(&identities, &ns).await.unwrap();
1254        assert_eq!(
1255            FULL_TABLE_SCAN_COUNT.load(std::sync::atomic::Ordering::Relaxed),
1256            2,
1257            "one upsert_batch call of 50 identities must do exactly one full-table oid scan \
1258             (build_oid_index) plus one full-table alias scan (build_alias_index), total 2"
1259        );
1260
1261        FULL_TABLE_SCAN_COUNT.store(0, std::sync::atomic::Ordering::Relaxed);
1262        for identity in &identities {
1263            cache.upsert(identity, &ns).await.unwrap();
1264        }
1265        assert_eq!(
1266            FULL_TABLE_SCAN_COUNT.load(std::sync::atomic::Ordering::Relaxed),
1267            100,
1268            "50 sequential upsert calls must each do their own oid scan + alias scan, total 100"
1269        );
1270    }
1271
1272    /// `upsert_batch` must apply the exact same per-entry dedup + precedence
1273    /// rules as a sequential loop of single `upsert` calls — including
1274    /// `SkippedUserOverride`, and including dedup against an earlier entry of
1275    /// the *same* batch (a batch may legitimately re-touch a target, e.g. a
1276    /// seed re-warm after a user override was already recorded).
1277    #[tokio::test]
1278    async fn upsert_batch_matches_sequential_upsert_semantics() {
1279        // This test doesn't read UPSERT_WRITE_TXN_COUNT, but it does call
1280        // upsert/upsert_batch, which increments that shared static — hold the
1281        // same guard so it can't skew a concurrently-running txn-count test.
1282        let _guard = TXN_COUNT_GUARD.lock().await;
1283        let ns = crate::identity::namespace("redb.tests.batch-semantics");
1284
1285        // A user override recorded first must survive a batch that later
1286        // tries to overwrite the same oid with a lower-precedence source.
1287        let store = Store::in_memory().unwrap();
1288        let cache = store.cache();
1289        let (override_id, _) = cache.upsert(&m31(), &ns).await.unwrap(); // TargetSource::Resolved
1290        let mut user_override = m31();
1291        user_override.source = TargetSource::UserOverride;
1292        "My Andromeda".clone_into(&mut user_override.primary_designation);
1293        cache.upsert(&user_override, &ns).await.unwrap();
1294
1295        let mut reseed = m31(); // TargetSource::Resolved, same oid: must be skipped
1296        "WRONG".clone_into(&mut reseed.primary_designation);
1297        let mut other = distinct_identities(1).remove(0);
1298        let batch = vec![other.clone(), reseed.clone()];
1299        let outcomes = cache.upsert_batch(&batch, &ns).await.unwrap();
1300        assert_eq!(outcomes[1].0, override_id);
1301        assert_eq!(outcomes[1].1, UpsertOutcome::SkippedUserOverride);
1302        let got = cache.get_by_id(override_id).await.unwrap().unwrap();
1303        assert_eq!(got.primary_designation, "My Andromeda", "user override stays sticky");
1304
1305        // A batch that upserts the same never-before-seen designation twice
1306        // (no oid, so dedup falls back to the derived id) must dedup the
1307        // second entry against the *first entry of the same batch*, not just
1308        // against already-committed rows.
1309        other.simbad_oid = None;
1310        "Repeat Target".clone_into(&mut other.primary_designation);
1311        let mut again = other.clone();
1312        again.dec_deg = 12.5;
1313        let batch2 = vec![other.clone(), again];
1314        let outcomes2 = cache.upsert_batch(&batch2, &ns).await.unwrap();
1315        assert_eq!(outcomes2[0].1, UpsertOutcome::Inserted, "first-ever row for this designation");
1316        assert_eq!(outcomes2[1].1, UpsertOutcome::Updated, "dedups against entry 0 of this batch");
1317        assert_eq!(outcomes2[0].0, outcomes2[1].0, "same derived id, same row");
1318        let got2 = cache.get_by_id(outcomes2[1].0).await.unwrap().unwrap();
1319        assert!((got2.dec_deg - 12.5).abs() < f64::EPSILON, "batch entry 1's value won");
1320    }
1321}