Skip to main content

khive_runtime/operations/
edge_query.rs

1use std::collections::HashMap;
2
3use serde::Serialize;
4use uuid::Uuid;
5
6use khive_db::stores::graph::edge_hard_delete_statement;
7use khive_storage::graph::{SymmetricEdgeUpdateOutcome, SymmetricEdgeUpdateRequest};
8use khive_storage::types::{
9    DeleteMode, EdgeSortField, LinkId, PageRequest, SeekCursor, SortOrder, SqlRow, SqlStatement,
10    SqlValue,
11};
12use khive_storage::{Edge, EdgeRelation};
13use khive_types::{EventKind, SubstrateKind};
14
15use crate::error::{RuntimeError, RuntimeResult};
16use crate::runtime::{KhiveRuntime, NamespaceToken};
17
18use super::{canonical_edge_endpoints, static_impossible_edge_pattern_warnings, EdgeReadWindow};
19
20/// Result of a GQL/SPARQL query with optional validation warnings.
21#[derive(Clone, Debug, Serialize)]
22pub struct QueryResult {
23    pub rows: Vec<SqlRow>,
24    #[serde(skip_serializing_if = "Vec::is_empty")]
25    pub warnings: Vec<String>,
26    /// Zero-based offset of this deterministic result page.
27    pub offset: usize,
28    /// Effective payload bound after composing query `LIMIT` and server page size.
29    pub page_size: usize,
30    /// `true` when at least one additional match exists after this page.
31    pub has_more: bool,
32    /// GQL continuation offset. Present exactly when GQL has another page.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub next_offset: Option<usize>,
35    /// Backward-compatible alias for `has_more` (#1168, #1247, #1601).
36    pub truncated: bool,
37}
38
39impl KhiveRuntime {
40    // ---- Query operations ----
41
42    /// Execute a GQL or SPARQL query string, returning raw SQL rows.
43    ///
44    /// The query is compiled to SQL with namespace and own-mailbox scopes applied.
45    /// GQL syntax: `MATCH (a:concept)-[e:extends]->(b) RETURN a, b LIMIT 10`
46    /// SPARQL syntax: `SELECT ?a WHERE { ?a :kind "concept" . }`
47    pub async fn query(&self, token: &NamespaceToken, query: &str) -> RuntimeResult<Vec<SqlRow>> {
48        Ok(self
49            .query_with_metadata(token, query, khive_query::CompileOptions::default())
50            .await?
51            .rows)
52    }
53
54    /// Execute a GQL/SPARQL query, returning rows and any validation warnings.
55    pub async fn query_with_metadata(
56        &self,
57        token: &NamespaceToken,
58        query: &str,
59        mut opts: khive_query::CompileOptions,
60    ) -> RuntimeResult<QueryResult> {
61        use khive_query::QueryValue;
62        use khive_storage::types::SqlValue;
63
64        let (language, ast) = khive_query::language::parse_auto_with_language(query)?;
65        if opts.max_limit == 0 {
66            return Err(RuntimeError::InvalidInput(
67                "query page size must be at least 1".into(),
68            ));
69        }
70        let offset = ast.offset;
71        let page_size = ast.limit.unwrap_or(opts.max_limit).min(opts.max_limit);
72        opts.scopes = token
73            .visible_namespaces()
74            .iter()
75            .map(|ns| ns.as_str().to_string())
76            .collect();
77        let mailbox = crate::MailboxView {
78            actor_id: token.actor().id.clone(),
79            delegated: false,
80        }
81        .note_scope(token);
82        let compiled = khive_query::compile_with_mailbox(
83            &ast,
84            &opts,
85            &khive_query::QueryMailboxScope {
86                actor_id: mailbox.actor_id,
87                legacy_local: mailbox.legacy_local,
88            },
89        )?;
90        let mut warnings = compiled.warnings;
91        let truncation_check = compiled.truncation_check;
92
93        warnings.extend(self.with_pack_edge_rules(|pack_rules| {
94            ast.patterns()
95                .flat_map(|pattern| {
96                    static_impossible_edge_pattern_warnings(language, pattern, pack_rules)
97                })
98                .collect::<Vec<_>>()
99        }));
100
101        // Convert QueryValue params (query-layer type) to SqlValue (storage-layer type)
102        // at the query–storage boundary.
103        let params: Vec<SqlValue> = compiled
104            .params
105            .into_iter()
106            .map(|qv| match qv {
107                QueryValue::Null => SqlValue::Null,
108                QueryValue::Integer(n) => SqlValue::Integer(n),
109                QueryValue::Float(f) => SqlValue::Float(f),
110                QueryValue::Text(s) => SqlValue::Text(s),
111                QueryValue::Blob(b) => SqlValue::Blob(b),
112            })
113            .collect();
114
115        let mut reader = self.sql().reader().await?;
116        let stmt = SqlStatement {
117            sql: compiled.sql,
118            params,
119            label: None,
120        };
121        let mut rows = reader.query_all(stmt).await?;
122
123        // When the effective page size was the binding constraint, the compiled
124        // SQL asked for one extra (sentinel) row. Its presence in the actual
125        // result set — not the requested LIMIT — is the continuation signal.
126        let mut truncated = false;
127        if let Some(check) = truncation_check {
128            if rows.len() > check.max_limit {
129                rows.truncate(check.max_limit);
130                truncated = true;
131            }
132        }
133
134        let next_offset = if truncated && language == khive_query::QueryLanguage::Gql {
135            let next = offset.checked_add(rows.len()).ok_or_else(|| {
136                RuntimeError::InvalidInput("GQL next_offset exceeds usize::MAX".into())
137            })?;
138            if next == offset {
139                return Err(RuntimeError::InvalidInput(
140                    "query page did not advance; page size must be at least 1".into(),
141                ));
142            }
143            i64::try_from(next).map_err(|_| {
144                RuntimeError::InvalidInput("GQL next_offset exceeds i64::MAX".into())
145            })?;
146            Some(next)
147        } else {
148            None
149        };
150
151        if truncated {
152            let Some(check) = truncation_check else {
153                return Err(RuntimeError::Internal(
154                    "truncated query result is missing sentinel metadata".into(),
155                ));
156            };
157            let bound = match check.requested_limit {
158                Some(requested) => {
159                    format!("requested query LIMIT {requested} exceeds the effective page size")
160                }
161                None => "the query has no explicit LIMIT".to_string(),
162            };
163            let warning = match language {
164                khive_query::QueryLanguage::Gql => {
165                    let Some(next) = next_offset else {
166                        return Err(RuntimeError::Internal(
167                            "truncated GQL result is missing its continuation offset".into(),
168                        ));
169                    };
170                    format!(
171                        "result page capped at {} rows because {bound}; more matches exist. \
172                         Continue the same GQL query with `SKIP {next}` (the machine-readable \
173                         `next_offset`) and keep the same page size.",
174                        check.max_limit
175                    )
176                }
177                khive_query::QueryLanguage::Sparql => format!(
178                    "result page capped at {} rows because {bound}; more matches exist. \
179                     SPARQL OFFSET paging is not part of the supported dialect.",
180                    check.max_limit
181                ),
182            };
183            warnings.push(warning);
184        }
185
186        Ok(QueryResult {
187            rows,
188            warnings,
189            offset,
190            page_size,
191            has_more: truncated,
192            next_offset,
193            truncated,
194        })
195    }
196
197    // ---- Edge CRUD operations ----
198
199    /// Fetch a single edge by id.
200    ///
201    /// UUID v4 is globally unique: returns the edge regardless of which
202    /// namespace the token carries. `Ok(None)` means the edge does not exist at all.
203    pub async fn get_edge(
204        &self,
205        _token: &NamespaceToken,
206        edge_id: Uuid,
207    ) -> RuntimeResult<Option<Edge>> {
208        self.get_edge_by_id_inner(edge_id, false).await
209    }
210
211    /// Read live edges by ID in input order, without a visibility predicate.
212    ///
213    /// Stored namespaces are validated before the corresponding edge decode.
214    /// Each namespace group uses its own graph capability; missing rows remain
215    /// `None`. Group failures belong to their first input, and the earliest
216    /// input error wins after all groups in that bounded window are observed.
217    /// Metadata statement failures are fatal batch errors. Windows are separate
218    /// read observations, not a snapshot of the whole request.
219    pub async fn get_edges_by_id(
220        &self,
221        _token: &NamespaceToken,
222        ids: &[Uuid],
223    ) -> RuntimeResult<Vec<Option<Edge>>> {
224        let mut edges = Vec::with_capacity(ids.len());
225        for chunk in ids.chunks(900) {
226            let window = self.prepare_edge_read_window(chunk).await?;
227            edges.extend(
228                Self::hydrate_edge_read_window(chunk, window, |record_token| {
229                    self.graph(record_token)
230                })
231                .await?,
232            );
233        }
234        Ok(edges)
235    }
236
237    pub(super) async fn prepare_edge_read_window(
238        &self,
239        ids: &[Uuid],
240    ) -> RuntimeResult<EdgeReadWindow> {
241        let placeholders = (1..=ids.len())
242            .map(|index| format!("?{index}"))
243            .collect::<Vec<_>>()
244            .join(",");
245        let mut reader = self.sql().reader().await?;
246        let rows = reader
247            .query_all(SqlStatement {
248                sql: format!(
249                    "SELECT id, namespace FROM graph_edges WHERE id IN ({placeholders}) AND deleted_at IS NULL"
250                ),
251                params: ids.iter().map(|id| SqlValue::Text(id.to_string())).collect(),
252                label: Some("get_edge_namespace".into()),
253            })
254            .await?;
255        let mut namespaces = HashMap::with_capacity(rows.len());
256        for row in rows {
257            let Some(SqlValue::Text(id)) = row.columns.first().map(|column| &column.value) else {
258                return Err(RuntimeError::Internal(
259                    "edge namespace lookup returned an invalid id".into(),
260                ));
261            };
262            let id = Uuid::parse_str(id).map_err(|e| {
263                RuntimeError::Internal(format!("edge namespace lookup returned an invalid id: {e}"))
264            })?;
265            let value = row
266                .columns
267                .get(1)
268                .map(|column| column.value.clone())
269                .unwrap_or(SqlValue::Null);
270            namespaces.insert(id, value);
271        }
272        let mut window = EdgeReadWindow {
273            outcomes: (0..ids.len()).map(|_| Some(Ok(None))).collect(),
274            groups: Vec::new(),
275        };
276        let mut group_indices = HashMap::new();
277        for (index, id) in ids.iter().enumerate() {
278            let Some(SqlValue::Text(record_ns)) = namespaces.get(id) else {
279                continue;
280            };
281            match khive_types::Namespace::parse(record_ns) {
282                Ok(namespace) => {
283                    let next_group = window.groups.len();
284                    let group = *group_indices.entry(record_ns.clone()).or_insert(next_group);
285                    if group == next_group {
286                        window.groups.push((namespace, Vec::new()));
287                    }
288                    window.groups[group].1.push(index);
289                    window.outcomes[index] = None;
290                }
291                Err(error) => {
292                    window.outcomes[index] = Some(Err(RuntimeError::Internal(format!(
293                        "edge namespace invalid: {error}"
294                    ))));
295                }
296            }
297        }
298        Ok(window)
299    }
300
301    pub(super) async fn hydrate_edge_read_window<F>(
302        ids: &[Uuid],
303        mut window: EdgeReadWindow,
304        mut graph: F,
305    ) -> RuntimeResult<Vec<Option<Edge>>>
306    where
307        F: FnMut(&NamespaceToken) -> RuntimeResult<std::sync::Arc<dyn khive_storage::GraphStore>>,
308    {
309        for (namespace, indices) in window.groups {
310            let record_token = NamespaceToken::for_namespace(namespace);
311            let group_ids: Vec<LinkId> = indices
312                .iter()
313                .map(|&index| LinkId::from(ids[index]))
314                .collect();
315            let outcomes = match graph(&record_token) {
316                Ok(store) => store
317                    .get_edge_read_outcomes(&group_ids)
318                    .await
319                    .map_err(RuntimeError::from),
320                Err(error) => Err(error),
321            };
322            match outcomes {
323                Ok(outcomes) if outcomes.len() == indices.len() => {
324                    for (index, outcome) in indices.into_iter().zip(outcomes) {
325                        window.outcomes[index] = Some(outcome.map_err(RuntimeError::from));
326                    }
327                }
328                Ok(_) => {
329                    window.outcomes[indices[0]] = Some(Err(RuntimeError::Internal(
330                        "edge batch returned an invalid outcome count".into(),
331                    )));
332                }
333                Err(error) => {
334                    window.outcomes[indices[0]] = Some(Err(error));
335                }
336            }
337        }
338        window
339            .outcomes
340            .into_iter()
341            .map(|outcome| {
342                outcome.unwrap_or_else(|| {
343                    Err(RuntimeError::Internal(
344                        "edge batch omitted an input outcome".into(),
345                    ))
346                })
347            })
348            .collect()
349    }
350
351    /// Fetch a single edge by id.
352    ///
353    /// Delegates to `get_edge`: no visible-set check.  By-ID ops are
354    /// namespace-agnostic; UUID v4 is globally unique.
355    pub async fn get_edge_visible(
356        &self,
357        token: &NamespaceToken,
358        edge_id: Uuid,
359    ) -> RuntimeResult<Option<Edge>> {
360        self.get_edge(token, edge_id).await
361    }
362
363    /// Fetch an edge by UUID including soft-deleted rows.
364    ///
365    /// Returns the edge regardless of which namespace the token carries:
366    /// UUID v4 is globally unique. Used by the hard-delete path so that a
367    /// soft-deleted edge can still be purged via its edge ID.
368    pub async fn get_edge_including_deleted(
369        &self,
370        _token: &NamespaceToken,
371        edge_id: Uuid,
372    ) -> RuntimeResult<Option<Edge>> {
373        self.get_edge_by_id_inner(edge_id, true).await
374    }
375
376    async fn get_edge_by_id_inner(
377        &self,
378        edge_id: Uuid,
379        include_deleted: bool,
380    ) -> RuntimeResult<Option<Edge>> {
381        let (sql, label) = if include_deleted {
382            (
383                "SELECT namespace FROM graph_edges WHERE id = ?1 LIMIT 1",
384                "get_edge_including_deleted_namespace",
385            )
386        } else {
387            (
388                "SELECT namespace FROM graph_edges \
389                 WHERE id = ?1 AND deleted_at IS NULL LIMIT 1",
390                "get_edge_namespace",
391            )
392        };
393        let mut reader = self.sql().reader().await?;
394        let record_ns = reader
395            .query_scalar(SqlStatement {
396                sql: sql.into(),
397                params: vec![SqlValue::Text(edge_id.to_string())],
398                label: Some(label.into()),
399            })
400            .await?;
401
402        let Some(SqlValue::Text(record_ns)) = record_ns else {
403            return Ok(None);
404        };
405        // Route through the record's own namespace store (no namespace equality check).
406        let record_tok = NamespaceToken::for_namespace(
407            khive_types::Namespace::parse(&record_ns)
408                .map_err(|e| RuntimeError::Internal(format!("edge namespace invalid: {e}")))?,
409        );
410        let graph = self.graph(&record_tok)?;
411        Ok(if include_deleted {
412            graph
413                .get_edge_including_deleted(LinkId::from(edge_id))
414                .await?
415        } else {
416            graph.get_edge(LinkId::from(edge_id)).await?
417        })
418    }
419
420    /// Fetch an edge by natural key (namespace, canonical source/target, relation)
421    /// including soft-deleted rows. Unlike [`Self::list_edges`]/[`Self::list_edges_after`],
422    /// which always filter `deleted_at IS NULL`, this can render a tombstoned symmetric-edge
423    /// survivor (ADR-039 DO NOTHING conflict absorption) — used by the atomic-apply
424    /// post-commit result renderer, which otherwise reports "not found" for a committed
425    /// update whose surviving row happens to be soft-deleted.
426    ///
427    /// `token` selects the store instance; `namespace` is the natural key's own
428    /// namespace and is bound into the query explicitly. These can legitimately differ:
429    /// the record namespace is fixed at prepare time (`EdgeNaturalKey::namespace`) and by-ID
430    /// edge updates are namespace-agnostic (ADR-007 Rev 6), so the caller's ambient `token`
431    /// namespace is never a safe substitute for the record's own — the prior implicit
432    /// `self.namespace` scoping is exactly the bug this parameter closes (khive#1213/#1214).
433    pub async fn get_edge_by_natural_key_including_deleted(
434        &self,
435        token: &NamespaceToken,
436        namespace: &str,
437        source_id: Uuid,
438        target_id: Uuid,
439        relation: EdgeRelation,
440    ) -> RuntimeResult<Option<Edge>> {
441        Ok(self
442            .graph(token)?
443            .get_edge_by_natural_key_including_deleted(namespace, source_id, target_id, relation)
444            .await?)
445    }
446
447    /// Maximum rows returned by a single [`Self::list_edges`] /
448    /// [`Self::list_edges_after`] page. A lower bound the docs promise callers
449    /// can rely on; kept as a named constant so tests can exercise pagination
450    /// (page tiling, out-of-range offsets) without needing >1000 real rows.
451    pub const EDGE_LIST_MAX_LIMIT: u32 = 1000;
452
453    /// List edges matching `filter`, paging by `offset`. `limit` is capped at
454    /// [`Self::EDGE_LIST_MAX_LIMIT`]; defaults to 100. For O(1)-at-depth walks
455    /// over large edge populations, prefer [`Self::list_edges_after`] instead
456    /// of paging offset deep.
457    pub async fn list_edges(
458        &self,
459        token: &NamespaceToken,
460        filter: crate::curation::EdgeListFilter,
461        limit: u32,
462        offset: u32,
463    ) -> RuntimeResult<Vec<Edge>> {
464        let limit = limit.min(Self::EDGE_LIST_MAX_LIMIT);
465        let visible = token.visible_namespaces();
466
467        // Common case: a single visible namespace — page directly against the
468        // store so `offset`/`limit` reach SQL unmodified.
469        if let [ns] = visible {
470            let temp = NamespaceToken::for_namespace(ns.clone());
471            let page = self
472                .graph(&temp)?
473                .query_edges(
474                    filter.into(),
475                    vec![SortOrder {
476                        field: EdgeSortField::CreatedAt,
477                        direction: khive_storage::types::SortDirection::Asc,
478                    }],
479                    PageRequest {
480                        offset: offset.into(),
481                        limit,
482                    },
483                )
484                .await?;
485            return Ok(page.items);
486        }
487
488        // Multi-namespace visibility: one deterministic query with
489        // `namespace IN (...)` and real SQL paging, mirroring
490        // `list_entities`. Fetching per-namespace prefixes and slicing a
491        // client-side merge re-sorted by UUID floats the offset window
492        // between calls — pages silently duplicate and skip rows, so
493        // enumeration never covers the set (#2088).
494        let ns_strs: Vec<String> = visible.iter().map(|ns| ns.as_str().to_owned()).collect();
495        let sort = vec![SortOrder {
496            field: EdgeSortField::CreatedAt,
497            direction: khive_storage::types::SortDirection::Asc,
498        }];
499        let graph = self.graph(token)?;
500        match graph
501            .query_edges_in_namespaces(
502                &ns_strs,
503                filter.clone().into(),
504                sort.clone(),
505                PageRequest {
506                    offset: offset.into(),
507                    limit,
508                },
509            )
510            .await
511        {
512            Ok(page) => Ok(page.items),
513            Err(khive_storage::StorageError::Unsupported { operation, .. })
514                if operation == "query_edges_in_namespaces" =>
515            {
516                // Backend exercises the trait default (no batched
517                // namespace query support): fall back to one `query_edges`
518                // call per namespace. Unlike the pre-image fix for #2088,
519                // this fetches an `offset + limit` prefix from every
520                // namespace and merges by the *same* `(created_at, id)` key
521                // each per-namespace fetch already orders by — the
522                // pre-image bug sorted the merged set by UUID alone, a key
523                // unrelated to the order each per-namespace prefix was cut
524                // at, which floated the offset window and silently
525                // duplicated/skipped rows across pages. Sorting by the
526                // fetch's own order key keeps the top `offset + limit` of
527                // the merge exactly equal to the true global prefix.
528                let fetch_limit = offset.saturating_add(limit);
529                let mut namespace_prefixes = Vec::new();
530                for ns in visible {
531                    let temp = NamespaceToken::for_namespace(ns.clone());
532                    let page = self
533                        .graph(&temp)?
534                        .query_edges(
535                            filter.clone().into(),
536                            sort.clone(),
537                            PageRequest {
538                                offset: 0,
539                                limit: fetch_limit,
540                            },
541                        )
542                        .await?;
543                    namespace_prefixes.push(page.items);
544                }
545                Ok(Self::merge_paged_namespace_edges(
546                    namespace_prefixes,
547                    offset,
548                    limit,
549                ))
550            }
551            Err(error) => Err(error.into()),
552        }
553    }
554
555    /// Merge per-namespace `(created_at, id)`-ordered edge prefixes (each
556    /// already fetched up to `offset + limit` from its own namespace, as
557    /// [`Self::list_edges`]'s trait-default fallback does) into one global
558    /// `[offset, offset + limit)` page.
559    ///
560    /// Sorting by the *same key each prefix was already cut at* is what
561    /// keeps this exact: the top `offset + limit` of the merged set is then
562    /// provably equal to the true global prefix (a standard k-way merge
563    /// argument — no element beyond position `offset + limit` in any single
564    /// namespace can appear before that position in the global order). The
565    /// pre-image #2088 bug instead re-sorted the merged set by UUID alone —
566    /// a key unrelated to the order each namespace's prefix was fetched in —
567    /// which floated the offset window and silently duplicated/skipped rows
568    /// across pages.
569    pub(super) fn merge_paged_namespace_edges(
570        namespace_prefixes: Vec<Vec<Edge>>,
571        offset: u32,
572        limit: u32,
573    ) -> Vec<Edge> {
574        let mut results: Vec<Edge> = namespace_prefixes.into_iter().flatten().collect();
575        results.sort_by_key(|e| (e.created_at, Uuid::from(e.id)));
576        let start = (offset as usize).min(results.len());
577        let end = (start + limit as usize).min(results.len());
578        results[start..end].to_vec()
579    }
580
581    /// Keyset (seek) page of edges matching `filter`, ordered by immutable
582    /// database-assigned insertion sequence. `after` is the last edge id from the
583    /// previous page (exclusive); omit to start from the beginning. Returns
584    /// `(items, next_after)` — `next_after` is `Some` when more rows remain
585    /// past this page.
586    ///
587    /// Unlike [`Self::list_edges`], this is O(log n + limit) at any depth and
588    /// genuinely new inserts are appended after already-issued boundaries. The
589    /// cursor row is resolved including tombstones; a hard-deleted or
590    /// out-of-scope cursor fails explicitly rather than hiding an incomplete
591    /// traversal.
592    pub async fn list_edges_after(
593        &self,
594        token: &NamespaceToken,
595        filter: crate::curation::EdgeListFilter,
596        after: Option<Uuid>,
597        limit: u32,
598    ) -> RuntimeResult<(Vec<Edge>, Option<Uuid>)> {
599        let limit = limit.clamp(1, Self::EDGE_LIST_MAX_LIMIT);
600        let visible = token.visible_namespaces();
601        let limit_usize = limit as usize;
602        let cursor_store = self.graph(token)?;
603        let after = match after {
604            Some(id) => {
605                let edge = self
606                    .get_edge_including_deleted(token, id)
607                    .await?
608                    .ok_or_else(|| RuntimeError::NotFound(format!("edge cursor {id}")))?;
609                Self::ensure_namespace_visible(&edge.namespace, token)?;
610                let sequence = cursor_store.edge_sequence(id).await?.ok_or_else(|| {
611                    RuntimeError::Internal(format!(
612                        "edge cursor {id} has no insertion-sequence ledger row"
613                    ))
614                })?;
615                Some(SeekCursor { sequence, id })
616            }
617            None => None,
618        };
619
620        if let [ns] = visible {
621            let temp = NamespaceToken::for_namespace(ns.clone());
622            let page = self
623                .graph(&temp)?
624                .query_edges_sequence_after(filter.into(), after, limit)
625                .await?;
626            return Ok((page.items, page.next_after.map(|cursor| cursor.id)));
627        }
628
629        // Multi-namespace visibility: seek each namespace from the same
630        // immutable boundary, merge in global insertion order, then take the head of
631        // the merged set as this page.
632        let probe_limit = limit.saturating_add(1);
633        let mut results = Vec::new();
634        for ns in visible {
635            let temp = NamespaceToken::for_namespace(ns.clone());
636            let page = self
637                .graph(&temp)?
638                .query_edges_sequence_after(filter.clone().into(), after, probe_limit)
639                .await?;
640            results.extend(page.items);
641        }
642        let ids = results
643            .iter()
644            .map(|edge| Uuid::from(edge.id))
645            .collect::<Vec<_>>();
646        let sequences = cursor_store
647            .edge_sequences(&ids)
648            .await?
649            .into_iter()
650            .collect::<HashMap<_, _>>();
651        if let Some(missing) = ids.iter().find(|id| !sequences.contains_key(id)) {
652            return Err(RuntimeError::Internal(format!(
653                "edge {missing} has no insertion-sequence ledger row"
654            )));
655        }
656        results.sort_by_key(|edge| {
657            let id = Uuid::from(edge.id);
658            (sequences[&id], id)
659        });
660        results.dedup_by_key(|e| Uuid::from(e.id));
661        let has_more = results.len() > limit_usize;
662        if has_more {
663            results.truncate(limit_usize);
664        }
665        let next_after = if has_more {
666            results.last().map(|e| Uuid::from(e.id))
667        } else {
668            None
669        };
670        Ok((results, next_after))
671    }
672
673    /// Count edges by relation, ignoring soft-deleted rows. Used by
674    /// `stats()` to report the true per-relation population so full-graph
675    /// audits know what they're sampling from before they walk it.
676    pub async fn count_edges_by_relation(
677        &self,
678        token: &NamespaceToken,
679    ) -> RuntimeResult<std::collections::HashMap<String, u64>> {
680        let namespaces: Vec<String> = token
681            .visible_namespaces()
682            .iter()
683            .map(|namespace| namespace.as_str().to_owned())
684            .collect();
685        let graph = self.graph(token)?;
686        let counts = match graph
687            .count_edges_by_relation_in_namespaces(&namespaces)
688            .await
689        {
690            Ok(counts) => counts,
691            Err(khive_storage::StorageError::Unsupported { operation, .. })
692                if operation == "count_edges_by_relation_in_namespaces" =>
693            {
694                let mut totals = HashMap::new();
695                for namespace in token.visible_namespaces() {
696                    let scoped = NamespaceToken::for_namespace(namespace.clone());
697                    for (relation, count) in self.graph(&scoped)?.count_edges_by_relation().await? {
698                        *totals.entry(relation).or_insert(0) += count;
699                    }
700                }
701                return Ok(totals
702                    .into_iter()
703                    .map(|(relation, count)| (relation.to_string(), count))
704                    .collect());
705            }
706            Err(error) => return Err(error.into()),
707        };
708        Ok(counts
709            .into_iter()
710            .map(|(relation, count)| (relation.to_string(), count))
711            .collect())
712    }
713
714    /// Count edges by the base each endpoint resolves against. Used by
715    /// `stats()` so a caller can name the denominator of a density figure
716    /// instead of inheriting the flat edge total, which on a real store is
717    /// mostly provenance.
718    ///
719    /// The per-namespace fallback sums the same buckets, so the aggregate and
720    /// the fallback are checkable against each other and against
721    /// `count_edges` by the invariant that the buckets sum to the total.
722    pub async fn count_edges_by_endpoint_base(
723        &self,
724        token: &NamespaceToken,
725    ) -> RuntimeResult<khive_storage::types::EdgeEndpointBaseCounts> {
726        use khive_storage::types::EdgeEndpointBaseCounts;
727
728        let namespaces: Vec<String> = token
729            .visible_namespaces()
730            .iter()
731            .map(|namespace| namespace.as_str().to_owned())
732            .collect();
733        let graph = self.graph(token)?;
734        match graph
735            .count_edges_by_endpoint_base_in_namespaces(&namespaces)
736            .await
737        {
738            Ok(counts) => Ok(counts),
739            Err(khive_storage::StorageError::Unsupported { operation, .. })
740                if operation == "count_edges_by_endpoint_base_in_namespaces"
741                    || operation == "count_edges_by_endpoint_base" =>
742            {
743                let mut totals = EdgeEndpointBaseCounts::default();
744                for namespace in token.visible_namespaces() {
745                    let scoped = NamespaceToken::for_namespace(namespace.clone());
746                    let counts = self.graph(&scoped)?.count_edges_by_endpoint_base().await?;
747                    totals.entity_entity =
748                        totals.entity_entity.saturating_add(counts.entity_entity);
749                    totals.entity_note = totals.entity_note.saturating_add(counts.entity_note);
750                    totals.note_entity = totals.note_entity.saturating_add(counts.note_entity);
751                    totals.note_note = totals.note_note.saturating_add(counts.note_note);
752                    totals.unresolved = totals.unresolved.saturating_add(counts.unresolved);
753                }
754                Ok(totals)
755            }
756            Err(error) => Err(error.into()),
757        }
758    }
759
760    /// Return the live edge total, its relation counts and its endpoint-base
761    /// counts for `stats`.
762    ///
763    /// The three describe one population: live edges with live endpoints in
764    /// the caller's visible namespaces. A backend with the combined aggregate
765    /// answers all of them from one grouped read, and the total is the sum of
766    /// its groups, so the invariants `stats` reports on (relation counts and
767    /// endpoint-base buckets each summing to the total) hold by construction.
768    /// A backend without it gets the three single-purpose counts.
769    pub async fn edge_stats_counts(
770        &self,
771        token: &NamespaceToken,
772    ) -> RuntimeResult<super::EdgeStatsCounts> {
773        let namespaces: Vec<String> = token
774            .visible_namespaces()
775            .iter()
776            .map(|namespace| namespace.as_str().to_owned())
777            .collect();
778        let graph = self.graph(token)?;
779        match graph
780            .count_edges_by_relation_and_endpoint_base_in_namespaces(&namespaces)
781            .await
782        {
783            Ok(groups) => {
784                let mut counts = super::EdgeStatsCounts::default();
785                for (relation, by_base) in groups {
786                    let relation_total = by_base.total();
787                    counts.edges = counts.edges.saturating_add(relation_total);
788                    let slot = counts
789                        .edges_by_relation
790                        .entry(relation.to_string())
791                        .or_insert(0);
792                    *slot = slot.saturating_add(relation_total);
793                    let totals = &mut counts.edges_by_endpoint_base;
794                    totals.entity_entity =
795                        totals.entity_entity.saturating_add(by_base.entity_entity);
796                    totals.entity_note = totals.entity_note.saturating_add(by_base.entity_note);
797                    totals.note_entity = totals.note_entity.saturating_add(by_base.note_entity);
798                    totals.note_note = totals.note_note.saturating_add(by_base.note_note);
799                    totals.unresolved = totals.unresolved.saturating_add(by_base.unresolved);
800                }
801                Ok(counts)
802            }
803            Err(khive_storage::StorageError::Unsupported { operation, .. })
804                if operation == "count_edges_by_relation_and_endpoint_base_in_namespaces" =>
805            {
806                Ok(super::EdgeStatsCounts {
807                    edges: self
808                        .count_edges(token, crate::curation::EdgeListFilter::default())
809                        .await?,
810                    edges_by_relation: self.count_edges_by_relation(token).await?,
811                    edges_by_endpoint_base: self.count_edges_by_endpoint_base(token).await?,
812                })
813            }
814            Err(error) => Err(error.into()),
815        }
816    }
817
818    /// Patch-style edge update. Only `Some(_)` fields are applied.
819    ///
820    /// When `relation` is `Some(new_rel)`, validates that the edge's existing endpoints
821    /// are legal for `new_rel` before persisting. Weight-only updates (`relation = None`)
822    /// skip validation. Returns `InvalidInput` if the new relation would violate the
823    /// three-case endpoint contract; the edge is NOT mutated on error.
824    ///
825    /// For symmetric relations (`competes_with`, `composed_with`), endpoint order is
826    /// canonicalised to `source_uuid < target_uuid` after validation. If a canonical
827    /// row already exists at the target triple, the non-canonical edge is deleted and
828    /// the existing canonical row is preserved unchanged (ADR-039 ON CONFLICT DO
829    /// NOTHING, mirroring `merge_entity_sql`) — its attributes, including a soft-deleted
830    /// `deleted_at`, are never overwritten by the discarded edge's patch.
831    pub async fn update_edge(
832        &self,
833        token: &NamespaceToken,
834        edge_id: Uuid,
835        patch: crate::curation::EdgePatch,
836    ) -> RuntimeResult<Edge> {
837        // Fetch the edge by UUID: ID-only, no namespace check.
838        // get_edge already uses the record's stored namespace internally.
839        let graph_for_fetch = self.graph(token)?;
840        let mut edge = graph_for_fetch
841            .get_edge(LinkId::from(edge_id))
842            .await?
843            .ok_or_else(|| crate::RuntimeError::NotFound(format!("edge {edge_id}")))?;
844        let expected_updated_at = edge.updated_at;
845        let expected_deleted_at = edge.deleted_at;
846        #[cfg(test)]
847        crate::curation::race_seam::pause_after_read().await;
848
849        // After fetching, all mutations and validation must use the
850        // RECORD's namespace, not the caller's.  Derive record_tok from the stored edge
851        // namespace so that endpoint validation, raw-SQL predicates, and graph routing
852        // all address the correct backend partition.
853        let record_ns: String = edge.namespace.clone();
854        let record_tok = token.with_namespace(
855            khive_types::Namespace::parse(&record_ns)
856                .map_err(|e| RuntimeError::Internal(format!("edge namespace invalid: {e}")))?,
857        );
858        let graph = self.graph(&record_tok)?;
859
860        let mut changed_fields: Vec<&'static str> = Vec::new();
861        if let Some(r) = patch.relation {
862            // Validate before mutating — use the existing endpoints with the new relation.
863            // Use record_tok so that endpoint existence checks look in the edge's own namespace.
864            self.validate_edge_relation_endpoints(&record_tok, edge.source_id, edge.target_id, r)
865                .await?;
866            edge.relation = r;
867            changed_fields.push("relation");
868        }
869        if let Some(w) = patch.weight {
870            // Reject non-finite or out-of-range weight explicitly; do not silently
871            // clamp invalid caller input (coding-standards §608-622).
872            if !khive_types::validate_edge_weight(w) {
873                return Err(RuntimeError::InvalidInput(format!(
874                    "edge weight must be a finite value in [0.0, 1.0]; got {w}"
875                )));
876            }
877            edge.weight = w;
878            changed_fields.push("weight");
879        }
880        if let Some(props) = patch.properties {
881            crate::secret_gate::reject_reserved_secret_gate_property(Some(&props))?;
882            edge.metadata = Self::merge_edge_properties(&edge.metadata, props);
883        }
884
885        // For symmetric relations, canonicalise endpoint order and check
886        // for natural-key conflicts regardless of whether endpoints were flipped.
887        //
888        // The guarded graph operation is used for ALL symmetric relations because `upsert_edge`
889        // resolves ON CONFLICT(namespace,id) first and cannot detect a duplicate at
890        // the natural key (namespace, source_id, target_id, relation) with a different
891        // id. Bug-fix: this path must also run when endpoints are already canonical
892        // (endpoints_flipped=false) to catch conflicts arising from a relation change
893        // that collides with an existing canonical row.
894        let (canon_src, canon_tgt) =
895            canonical_edge_endpoints(edge.relation, edge.source_id, edge.target_id);
896
897        if edge.relation.is_symmetric() {
898            let outcome = graph
899                .update_symmetric_edge_if_unchanged(SymmetricEdgeUpdateRequest {
900                    namespace: record_ns.clone(),
901                    id: edge_id.into(),
902                    source_id: canon_src,
903                    target_id: canon_tgt,
904                    relation: edge.relation,
905                    weight: edge.weight,
906                    metadata: edge.metadata.clone(),
907                    expected_updated_at_micros: expected_updated_at.timestamp_micros(),
908                    expected_deleted_at_micros: expected_deleted_at.map(|v| v.timestamp_micros()),
909                })
910                .await?;
911
912            match outcome {
913                SymmetricEdgeUpdateOutcome::Absorbed(sid) => {
914                    // A conflict was absorbed (ADR-039 DO NOTHING): re-fetch the surviving
915                    // canonical row so the caller receives its real, UNMODIFIED attributes —
916                    // including soft-deleted rows, since the survivor's tombstone state (if
917                    // any) must not be resurrected by the absorbed update either. Use
918                    // record_tok — the surviving row lives in the same namespace as the
919                    // original.
920                    let surviving_uuid = Uuid::parse_str(&sid).map_err(|e| {
921                        RuntimeError::Internal(format!(
922                            "update_edge: surviving id parse failed: {e}"
923                        ))
924                    })?;
925                    edge = self
926                        .get_edge_including_deleted(&record_tok, surviving_uuid)
927                        .await?
928                        .ok_or_else(|| {
929                            RuntimeError::Internal(format!(
930                                "update_edge: surviving canonical row {surviving_uuid} vanished after update"
931                            ))
932                        })?;
933                }
934                SymmetricEdgeUpdateOutcome::Updated => {
935                    // Reflect canonical endpoints in the returned edge (no conflict absorbed).
936                    edge.source_id = canon_src;
937                    edge.target_id = canon_tgt;
938                }
939                SymmetricEdgeUpdateOutcome::Stale => {
940                    return Err(crate::curation::stale_edge_snapshot_error(edge_id));
941                }
942            }
943        } else {
944            // Non-symmetric: replace_edge_if_unchanged takes namespace from edge.namespace
945            // (not from the graph store's routing namespace), so this is already
946            // record-namespace correct. `graph` is already self.graph(&record_tok)?.
947            // Guarded on the fetched snapshot's revision — a concurrent writer that moved
948            // this edge between the fetch above and this write must be refused, not
949            // silently overwritten by a full-row replacement derived from stale state.
950            // `updated_at` must advance past the snapshot: the guard requires the
951            // replacement revision to be strictly greater than the persisted one.
952            // Make it strictly advance even when two operations land inside one
953            // clock microsecond; saturating to i64::MAX would let the CAS accept
954            // a write without advancing its revision, so that is not a valid
955            // fallback (mirrors the note path).
956            let minimum_updated_at_micros = expected_updated_at
957                .timestamp_micros()
958                .checked_add(1)
959                .ok_or_else(|| {
960                RuntimeError::Internal(format!(
961                    "edge {edge_id} updated_at is already at i64::MAX and cannot advance"
962                ))
963            })?;
964            let now_micros = chrono::Utc::now()
965                .timestamp_micros()
966                .max(minimum_updated_at_micros);
967            edge.updated_at =
968                chrono::DateTime::from_timestamp_micros(now_micros).ok_or_else(|| {
969                    RuntimeError::Internal(format!(
970                        "edge {edge_id}: computed updated_at {now_micros} is not a valid timestamp"
971                    ))
972                })?;
973            let persisted = graph
974                .replace_edge_if_unchanged(edge.clone(), expected_updated_at, expected_deleted_at)
975                .await?;
976            if !persisted {
977                return Err(crate::curation::stale_edge_snapshot_error(edge_id));
978            }
979        }
980
981        // Audit event: use the record's namespace (record_ns) for the event payload.
982        let event_store = self.events(&record_tok)?;
983        let event = khive_storage::event::Event::new(
984            record_ns.clone(),
985            "update",
986            EventKind::EdgeUpdated,
987            SubstrateKind::Entity,
988            "",
989        )
990        .with_target(edge_id)
991        .with_payload(
992            serde_json::json!({"id": edge_id, "namespace": record_ns, "changed_fields": changed_fields}),
993        );
994        event_store.append_event(event).await.map_err(|e| {
995            RuntimeError::Internal(format!("update_edge: event store write failed: {e}"))
996        })?;
997
998        Ok(edge)
999    }
1000
1001    /// Hard-delete an edge by id.
1002    ///
1003    /// Cascades to remove any `annotates` edges whose target is the deleted edge
1004    /// (`annotates` is note → anything; deleting an edge target leaves annotation
1005    /// edges dangling if not cleaned up). Returns `true` if the primary
1006    /// edge was removed.
1007    ///
1008    /// If `edge_id` does not refer to an edge (e.g. the caller passes an entity or
1009    /// note UUID by mistake), this method returns `Ok(false)` immediately with no
1010    /// side effects — it does **not** cascade inbound edges of the non-edge record.
1011    pub async fn delete_edge(
1012        &self,
1013        token: &NamespaceToken,
1014        edge_id: Uuid,
1015        hard: bool,
1016    ) -> RuntimeResult<bool> {
1017        let mode = if hard {
1018            DeleteMode::Hard
1019        } else {
1020            DeleteMode::Soft
1021        };
1022
1023        // Fetch the edge first to obtain the record's own namespace.
1024        // By-ID ops cross namespace boundaries; all graph routing and audit
1025        // events must use the record namespace, not the caller's (mirrors update_edge).
1026        // For hard delete we also check soft-deleted rows so a soft-deleted edge
1027        // can still be purged via its edge ID.
1028        let edge = if hard {
1029            self.get_edge_including_deleted(token, edge_id).await?
1030        } else {
1031            self.get_edge(token, edge_id).await?
1032        };
1033        let Some(edge) = edge else {
1034            return Ok(false);
1035        };
1036
1037        // Derive record_ns / record_tok from the fetched edge (mirrors update_edge).
1038        let record_ns: String = edge.namespace.clone();
1039        let record_tok = token.with_namespace(
1040            khive_types::Namespace::parse(&record_ns)
1041                .map_err(|e| RuntimeError::Internal(format!("edge namespace invalid: {e}")))?,
1042        );
1043        let graph = self.graph(&record_tok)?;
1044        let actor = format!("{}:{}", token.actor().kind, token.actor().id);
1045
1046        // Cascade: on hard delete, remove ALL annotates edges targeting this edge — including
1047        // already-soft-deleted ones: to prevent dangling graph_edges rows. The row
1048        // delete and the cascade purge run as ONE write transaction: see
1049        // `atomic_hard_delete_with_edge_purge`.
1050        // On soft delete the cascade is skipped (data-vs-view principle: soft-deleting the base
1051        // edge does not cascade to annotation edges; only a hard purge cleans up incident rows).
1052        let deleted = if hard {
1053            self.atomic_hard_delete_with_edge_purge(
1054                edge_hard_delete_statement(edge_id),
1055                edge_id,
1056                &record_ns,
1057                &actor,
1058                SubstrateKind::Entity,
1059            )
1060            .await?
1061        } else {
1062            graph.delete_edge(LinkId::from(edge_id), mode).await?
1063        };
1064        if deleted {
1065            // Audit event: use the record's namespace (record_ns), not the caller's namespace.
1066            let event_store = self.events(&record_tok)?;
1067            let event = khive_storage::event::Event::new(
1068                record_ns.clone(),
1069                "delete",
1070                EventKind::EdgeDeleted,
1071                SubstrateKind::Entity,
1072                "",
1073            )
1074            .with_target(edge_id)
1075            .with_payload(serde_json::json!({"id": edge_id, "namespace": record_ns, "hard": hard}));
1076            event_store.append_event(event).await.map_err(|e| {
1077                RuntimeError::Internal(format!("delete_edge: event store write failed: {e}"))
1078            })?;
1079        }
1080        Ok(deleted)
1081    }
1082
1083    /// Count edges matching `filter` across the caller's visible namespaces.
1084    pub async fn count_edges(
1085        &self,
1086        token: &NamespaceToken,
1087        filter: crate::curation::EdgeListFilter,
1088    ) -> RuntimeResult<u64> {
1089        let namespaces: Vec<String> = token
1090            .visible_namespaces()
1091            .iter()
1092            .map(|namespace| namespace.as_str().to_owned())
1093            .collect();
1094        let graph = self.graph(token)?;
1095        match graph
1096            .count_edges_in_namespaces(&namespaces, filter.clone().into())
1097            .await
1098        {
1099            Ok(count) => Ok(count),
1100            Err(khive_storage::StorageError::Unsupported { operation, .. })
1101                if operation == "count_edges_in_namespaces" =>
1102            {
1103                let mut total = 0;
1104                for namespace in token.visible_namespaces() {
1105                    let scoped = NamespaceToken::for_namespace(namespace.clone());
1106                    total += self
1107                        .graph(&scoped)?
1108                        .count_edges(filter.clone().into())
1109                        .await?;
1110                }
1111                Ok(total)
1112            }
1113            Err(error) => Err(error.into()),
1114        }
1115    }
1116}