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