Skip to main content

khive_runtime/
curation.rs

1// Licensed under the Apache License, Version 2.0.
2
3// FILE SIZE JUSTIFICATION: curation.rs holds entity/note/edge patch types alongside
4// their update and merge implementations. The implementations share private helpers
5// (merge_properties, namespace checks, dedup policy) that need pub(crate) access to
6// runtime internals. Inline tests cover merge semantics that require direct access to
7// those helpers. Split plan: extract patch types into `curation/patch.rs` and merge
8// logic into `curation/merge.rs` once the dedup policy API stabilises.
9//! Curation operations: entity update/merge and edge-list filter type.
10
11use std::collections::{HashMap, HashSet, VecDeque};
12
13use serde::{Deserialize, Serialize};
14use serde_json::Value;
15use uuid::Uuid;
16
17use khive_db::SqliteError;
18use khive_storage::note::Note;
19use khive_storage::types::{EdgeFilter, TextDocument};
20use khive_storage::{EdgeRelation, Entity, SubstrateKind};
21use khive_types::{Details, EdgeEndpointRule, EventKind, KhiveError};
22use rusqlite::OptionalExtension;
23
24use crate::error::{RuntimeError, RuntimeResult};
25use crate::operations::{base_entity_rule_allows, canonical_edge_endpoints, endpoint_matches};
26use crate::runtime::{KhiveRuntime, NamespaceToken};
27
28/// Immutable embedding-registry view for one logical write.
29///
30/// Document byte budgets are derived from the model name at the embedding seam,
31/// so retaining the exact name set keeps merge cleanup, table preparation, and
32/// survivor reindexing on one plan during concurrent registration.
33#[derive(Clone, Debug, Default)]
34struct EmbeddingModelPlan {
35    model_names: Vec<String>,
36}
37
38impl EmbeddingModelPlan {
39    fn capture(runtime: &KhiveRuntime) -> Self {
40        Self {
41            model_names: runtime.registered_embedding_model_names(),
42        }
43    }
44
45    fn is_empty(&self) -> bool {
46        self.model_names.is_empty()
47    }
48
49    fn model_names(&self) -> &[String] {
50        &self.model_names
51    }
52
53    fn vector_tables(&self) -> Vec<String> {
54        self.model_names
55            .iter()
56            .map(|name| format!("vec_{}", crate::config::sanitize_key(name)))
57            .collect()
58    }
59}
60
61// ---------------------------------------------------------------------------
62// Public types
63// ---------------------------------------------------------------------------
64
65/// Patch for `update_entity`. Only `Some(_)` fields are applied; `None` means "leave unchanged".
66///
67/// For `description`:
68/// - `None` (outer) — leave the current description as-is
69/// - `Some(None)` — clear the description (set to NULL)
70/// - `Some(Some(s))` — set the description to `s`
71///
72/// For `properties` (deep-merge semantics):
73/// - `None` — leave properties as-is
74/// - `Some(value)` — deep-merge `value` into existing properties. Keys present in
75///   the patch overwrite existing keys; keys absent from the patch are preserved.
76///   Removing a key requires explicit replacement of the parent object (or a future
77///   `unset`/`null-marker` extension).
78///
79/// For `tags` — replace semantics: `Some(vec)` sets tags to exactly `vec`. To add
80/// a tag without losing existing tags, read the entity first, push the new tag,
81/// and pass the full list back.
82#[derive(Clone, Debug, Default)]
83pub struct EntityPatch {
84    pub name: Option<String>,
85    pub description: Option<Option<String>>,
86    pub properties: Option<Value>,
87    pub tags: Option<Vec<String>>,
88}
89
90/// Policy used when deduplicating two entities.
91#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
92#[serde(rename_all = "snake_case")]
93pub enum EntityDedupMergePolicy {
94    /// `into` values win on conflict. Tags are unioned. Properties from `from` fill in
95    /// keys that `into` doesn't have. This is the default.
96    #[default]
97    PreferInto,
98    /// `from` values win on conflict.
99    PreferFrom,
100    /// Deep-merge: object properties merge recursively. Scalar conflicts go to `into`.
101    Union,
102}
103
104/// Safety-floor guard that refused an explicit entity merge.
105#[derive(Clone, Copy, Debug, PartialEq, Eq)]
106pub enum EntityMergeGuard {
107    EntityKind,
108    NameSimilarity,
109    ProjectCompatibility,
110}
111
112impl EntityMergeGuard {
113    pub fn as_str(self) -> &'static str {
114        match self {
115            Self::EntityKind => "entity_kind",
116            Self::NameSimilarity => "name_similarity",
117            Self::ProjectCompatibility => "project_compatibility",
118        }
119    }
120}
121
122/// Validate the non-forced entity-merge safety floor.
123pub fn validate_entity_merge_floor(into: &Entity, from: &Entity) -> Result<(), EntityMergeGuard> {
124    if into.kind != from.kind {
125        return Err(EntityMergeGuard::EntityKind);
126    }
127    if !names_are_similar(&into.name, &from.name) {
128        return Err(EntityMergeGuard::NameSimilarity);
129    }
130    if projects_are_disjoint(into, from) {
131        return Err(EntityMergeGuard::ProjectCompatibility);
132    }
133    Ok(())
134}
135
136/// Convert a safety-floor refusal into the merge verb's structured conflict contract.
137pub fn entity_merge_guard_error(guard: EntityMergeGuard) -> RuntimeError {
138    RuntimeError::Khive(
139        KhiveError::conflict(format!(
140            "entity merge refused by {} guard; use force=true only when the caller accepts responsibility",
141            guard.as_str()
142        ))
143        .with_details(Details::new([
144            ("guard", guard.as_str()),
145            ("override", "force=true"),
146        ])),
147    )
148}
149
150fn names_are_similar(left: &str, right: &str) -> bool {
151    let left = normalize_name(left);
152    let right = normalize_name(right);
153    if left.is_empty() || right.is_empty() {
154        return false;
155    }
156    if left == right {
157        return true;
158    }
159
160    let shorter_len = left.chars().count().min(right.chars().count());
161    if shorter_len >= 3 && (left.starts_with(&right) || right.starts_with(&left)) {
162        return true;
163    }
164
165    let left_trigrams = trigrams(&left);
166    let right_trigrams = trigrams(&right);
167    if left_trigrams.is_empty() || right_trigrams.is_empty() {
168        return false;
169    }
170    let overlap = left_trigrams.intersection(&right_trigrams).count();
171    overlap.saturating_mul(4) >= left_trigrams.len().saturating_add(right_trigrams.len())
172}
173
174fn normalize_name(name: &str) -> String {
175    let mut normalized = String::with_capacity(name.len());
176    let mut pending_space = false;
177    for ch in name.chars().flat_map(char::to_lowercase) {
178        if ch.is_whitespace() {
179            pending_space = !normalized.is_empty();
180        } else {
181            if pending_space {
182                normalized.push(' ');
183                pending_space = false;
184            }
185            normalized.push(ch);
186        }
187    }
188    normalized
189}
190
191fn trigrams(value: &str) -> HashSet<[char; 3]> {
192    let chars: Vec<char> = value.chars().collect();
193    chars
194        .windows(3)
195        .map(|window| [window[0], window[1], window[2]])
196        .collect()
197}
198
199fn projects_are_disjoint(into: &Entity, from: &Entity) -> bool {
200    let Some(into_projects) = into
201        .properties
202        .as_ref()
203        .and_then(|properties| properties.get("projects"))
204        .and_then(Value::as_array)
205    else {
206        return false;
207    };
208    let Some(from_projects) = from
209        .properties
210        .as_ref()
211        .and_then(|properties| properties.get("projects"))
212        .and_then(Value::as_array)
213    else {
214        return false;
215    };
216    if into_projects.is_empty() || from_projects.is_empty() {
217        return false;
218    }
219
220    let (indexed, candidates) = if into_projects.len() <= from_projects.len() {
221        (into_projects, from_projects)
222    } else {
223        (from_projects, into_projects)
224    };
225    let mut indexed_strings = HashSet::new();
226    let mut indexed_values = HashSet::new();
227    for value in indexed {
228        if let Some(value) = value.as_str() {
229            indexed_strings.insert(normalize_project_string(value));
230        } else {
231            indexed_values.insert(value.clone());
232        }
233    }
234    !candidates.iter().any(|candidate| {
235        if let Some(candidate) = candidate.as_str() {
236            indexed_strings.contains(&normalize_project_string(candidate))
237        } else {
238            indexed_values.contains(candidate)
239        }
240    })
241}
242
243fn normalize_project_string(value: &str) -> String {
244    value.trim().to_ascii_lowercase()
245}
246
247/// Strategy for merging note content when two notes are combined.
248#[derive(Clone, Copy, Debug, Default, Serialize, Deserialize, PartialEq, Eq)]
249#[serde(rename_all = "snake_case")]
250pub enum ContentMergeStrategy {
251    #[default]
252    Append,
253    PreferInto,
254    PreferFrom,
255}
256
257/// Result returned by `merge_entity` / `merge_note`.
258#[derive(Clone, Debug, Serialize, Deserialize)]
259pub struct MergeSummary {
260    pub kept_id: Uuid,
261    pub removed_id: Uuid,
262    pub edges_rewired: usize,
263    /// Incident edges dropped instead of rewired because the rewired
264    /// `(source, relation, target)` triple would violate the pack endpoint
265    /// contract `link` enforces (khive#1216) — consistent with the existing
266    /// dangling-endpoint skip behavior, never silently rewired into a
267    /// contract-violating edge.
268    #[serde(default)]
269    pub edges_contract_skipped: usize,
270    /// Full preimages for natural-key edge conflicts resolved by this merge.
271    /// Each entry names the surviving row, the dropped duplicate, and every
272    /// incident edge cascaded with it so the destructive step is reversible.
273    #[serde(default)]
274    pub edge_conflict_preimages: Vec<MergeEdgeConflictPreimage>,
275    pub properties_merged: usize,
276    pub tags_unioned: usize,
277    pub content_appended: bool,
278    pub dry_run: bool,
279    /// Actual embedding-input truncation observed while reindexing the survivor.
280    #[serde(skip)]
281    pub embedding_truncation: crate::retrieval::EmbeddingTruncationReport,
282}
283
284/// Complete stored state of an edge removed while resolving a merge conflict.
285///
286/// Timestamps use the storage layer's microsecond representation. `relation`
287/// remains a string so a legacy row predating the closed relation enum can
288/// still be captured without making an otherwise valid merge fail.
289#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
290pub struct MergeEdgePreimage {
291    pub id: Uuid,
292    pub namespace: String,
293    pub source_id: Uuid,
294    pub target_id: Uuid,
295    pub relation: String,
296    pub weight: f64,
297    pub created_at: i64,
298    pub updated_at: i64,
299    pub deleted_at: Option<i64>,
300    pub target_backend: Option<String>,
301    pub metadata: Option<Value>,
302}
303
304/// One natural-key collision resolved by a direct entity or note merge.
305#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
306pub struct MergeEdgeConflictPreimage {
307    pub surviving_edge_id: Uuid,
308    pub dropped_edge: MergeEdgePreimage,
309    /// Edges removed by the hard-delete cascade because they referenced the
310    /// dropped edge as a node. Under the accepted endpoint contract these are
311    /// `annotates` edges, including already-soft-deleted rows.
312    #[serde(default, skip_serializing_if = "Vec::is_empty")]
313    pub incident_edge_preimages: Vec<MergeEdgePreimage>,
314}
315
316/// Patch for `update_edge`. Only `Some(_)` fields are applied; `None` means "leave unchanged".
317///
318/// For `properties` — replacement semantics (not deep merge): `Some(value)` replaces
319/// the entire metadata object. `None` leaves metadata unchanged.
320#[derive(Clone, Debug, Default)]
321pub struct EdgePatch {
322    pub relation: Option<EdgeRelation>,
323    pub weight: Option<f64>,
324    pub properties: Option<Value>,
325}
326
327/// Patch for `update_note`. Only `Some(_)` fields are applied; `None` means "leave unchanged".
328///
329/// For `salience`/`decay_factor`:
330/// - `None` (outer) — leave unchanged
331/// - `Some(None)` — clear the value
332/// - `Some(Some(v))` — set to v
333#[derive(Clone, Debug, Default)]
334pub struct NotePatch {
335    pub name: Option<Option<String>>,
336    pub content: Option<String>,
337    pub salience: Option<Option<f64>>,
338    pub decay_factor: Option<Option<f64>>,
339    pub properties: Option<Value>,
340    pub(crate) kind_status: Option<String>,
341}
342
343impl NotePatch {
344    /// Construct a `NotePatch` from the public fields only.
345    /// Use this from external crates; `kind_status` is set to `None`.
346    pub fn new(
347        name: Option<Option<String>>,
348        content: Option<String>,
349        salience: Option<Option<f64>>,
350        decay_factor: Option<Option<f64>>,
351        properties: Option<Value>,
352    ) -> Self {
353        Self {
354            name,
355            content,
356            salience,
357            decay_factor,
358            properties,
359            kind_status: None,
360        }
361    }
362}
363
364/// Filter for `list_edges` / `count_edges`.
365#[derive(Clone, Debug, Default)]
366pub struct EdgeListFilter {
367    pub source_id: Option<Uuid>,
368    pub target_id: Option<Uuid>,
369    /// Empty = any relation.
370    pub relations: Vec<EdgeRelation>,
371    pub min_weight: Option<f64>,
372    pub max_weight: Option<f64>,
373}
374
375impl From<EdgeListFilter> for EdgeFilter {
376    fn from(f: EdgeListFilter) -> Self {
377        EdgeFilter {
378            source_ids: f.source_id.into_iter().collect(),
379            target_ids: f.target_id.into_iter().collect(),
380            relations: f.relations,
381            min_weight: f.min_weight,
382            max_weight: f.max_weight,
383            ..Default::default()
384        }
385    }
386}
387
388// ---------------------------------------------------------------------------
389// Private types
390// ---------------------------------------------------------------------------
391
392#[derive(Clone, Copy, Debug, PartialEq, Eq)]
393enum EntityMergeValidation {
394    LegacyKind,
395    SafetyFloor,
396    Forced,
397}
398
399#[derive(Debug)]
400enum EntityMergeRefusal {
401    LegacyKind {
402        into_id: Uuid,
403        into_kind: String,
404        from_id: Uuid,
405        from_kind: String,
406    },
407    SafetyFloor(EntityMergeGuard),
408}
409
410impl EntityMergeRefusal {
411    fn into_runtime_error(self) -> RuntimeError {
412        match self {
413            Self::LegacyKind {
414                into_id,
415                into_kind,
416                from_id,
417                from_kind,
418            } => RuntimeError::InvalidInput(format!(
419                "cannot merge entities of different kinds: into={into_id} ({into_kind}), \
420                 from={from_id} ({from_kind}); merge requires both entities to share the same kind"
421            )),
422            Self::SafetyFloor(guard) => entity_merge_guard_error(guard),
423        }
424    }
425}
426
427#[derive(Debug)]
428enum MergeEntitySqlError {
429    Sqlite(SqliteError),
430    Refusal(EntityMergeRefusal),
431}
432
433impl std::fmt::Display for MergeEntitySqlError {
434    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
435        match self {
436            Self::Sqlite(error) => std::fmt::Display::fmt(error, f),
437            Self::Refusal(_) => f.write_str("entity merge refused by transactional policy"),
438        }
439    }
440}
441
442impl std::error::Error for MergeEntitySqlError {}
443
444impl From<SqliteError> for MergeEntitySqlError {
445    fn from(error: SqliteError) -> Self {
446        Self::Sqlite(error)
447    }
448}
449
450impl From<rusqlite::Error> for MergeEntitySqlError {
451    fn from(error: rusqlite::Error) -> Self {
452        Self::Sqlite(SqliteError::Rusqlite(error))
453    }
454}
455
456fn map_merge_entity_storage_error(error: khive_storage::StorageError) -> RuntimeError {
457    match error {
458        khive_storage::StorageError::Driver {
459            capability,
460            operation,
461            source,
462        } => match source.downcast::<MergeEntitySqlError>() {
463            Ok(error) => match *error {
464                MergeEntitySqlError::Sqlite(error) => RuntimeError::Sqlite(error),
465                MergeEntitySqlError::Refusal(error) => error.into_runtime_error(),
466            },
467            Err(source) => RuntimeError::Storage(khive_storage::StorageError::Driver {
468                capability,
469                operation,
470                source,
471            }),
472        },
473        error => RuntimeError::Storage(error),
474    }
475}
476
477// REASON: EdgeRow fields are populated via rusqlite row mapping. The struct is fully
478// constructed even when not all fields are read back after construction. The complete
479// field mapping guards against column-order bugs when the schema changes.
480#[derive(Clone)]
481struct EdgeRow {
482    id: Uuid,
483    /// The edge's own attribution namespace (khive#1236) — may differ from the
484    /// merge's target namespace, since by-ID edge endpoints are namespace-agnostic
485    /// (ADR-007 Rev 6) and an edge is stamped with its *creator's* namespace, not
486    /// either endpoint's. All row-scoped SQL against this edge (conflict probe,
487    /// update, delete) must key off this field, never the merge's `namespace` arg.
488    namespace: String,
489    source_id: Uuid,
490    target_id: Uuid,
491    relation: String,
492    weight: f64,
493    created_at: i64,
494    updated_at: i64,
495    deleted_at: Option<i64>,
496    target_backend: Option<String>,
497    metadata: Option<String>,
498}
499
500fn edge_row_preimage(edge: &EdgeRow) -> Result<MergeEdgePreimage, SqliteError> {
501    let metadata = edge
502        .metadata
503        .as_deref()
504        .map(serde_json::from_str)
505        .transpose()
506        .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
507    Ok(MergeEdgePreimage {
508        id: edge.id,
509        namespace: edge.namespace.clone(),
510        source_id: edge.source_id,
511        target_id: edge.target_id,
512        relation: edge.relation.clone(),
513        weight: edge.weight,
514        created_at: edge.created_at,
515        updated_at: edge.updated_at,
516        deleted_at: edge.deleted_at,
517        target_backend: edge.target_backend.clone(),
518        metadata,
519    })
520}
521
522/// Capture every row that the accepted hard-edge-delete cascade would remove
523/// when `root_edge_id` is purged. The traversal is recursive because an
524/// `annotates` edge may itself be an annotation target. Rows that also touch a
525/// merge participant use their transaction-start snapshot from `original_edges`
526/// so the preimage never reflects an earlier rewire in the same merge.
527fn collect_conflict_incident_edge_preimages(
528    conn: &rusqlite::Connection,
529    root_edge_id: Uuid,
530    original_edges: &HashMap<Uuid, EdgeRow>,
531) -> Result<Vec<MergeEdgePreimage>, SqliteError> {
532    let parse_id =
533        |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
534    let mut queue = VecDeque::from([root_edge_id]);
535    let mut seen = HashSet::from([root_edge_id]);
536    let mut preimages = Vec::new();
537
538    while let Some(target_edge_id) = queue.pop_front() {
539        let mut stmt = conn.prepare(
540            "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
541                    updated_at, deleted_at, target_backend, metadata \
542             FROM graph_edges WHERE source_id = ?1 OR target_id = ?1 ORDER BY id",
543        )?;
544        let mut rows = stmt.query(rusqlite::params![target_edge_id.to_string()])?;
545        while let Some(row) = rows.next()? {
546            let edge = EdgeRow {
547                id: parse_id(row.get(0)?)?,
548                namespace: row.get(1)?,
549                source_id: parse_id(row.get(2)?)?,
550                target_id: parse_id(row.get(3)?)?,
551                relation: row.get(4)?,
552                weight: row.get(5)?,
553                created_at: row.get(6)?,
554                updated_at: row.get(7)?,
555                deleted_at: row.get(8)?,
556                target_backend: row.get(9)?,
557                metadata: row.get(10)?,
558            };
559            if !seen.insert(edge.id) {
560                continue;
561            }
562            let preimage = match original_edges.get(&edge.id) {
563                Some(original) => edge_row_preimage(original)?,
564                None => edge_row_preimage(&edge)?,
565            };
566            queue.push_back(edge.id);
567            preimages.push(preimage);
568        }
569    }
570
571    Ok(preimages)
572}
573
574fn delete_conflict_incident_edges(
575    conn: &rusqlite::Connection,
576    preimages: &[MergeEdgePreimage],
577) -> Result<(), SqliteError> {
578    for edge in preimages.iter().rev() {
579        conn.execute(
580            khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
581            rusqlite::params![&edge.namespace, edge.id.to_string()],
582        )?;
583    }
584    Ok(())
585}
586
587/// Resolves the substrate (`"entity"` or `"note"`), kind, and entity_type (entities
588/// only) of an edge endpoint by id, namespace-agnostically — by-ID resolution is
589/// namespace-agnostic by design (ADR-007 Rev 6), and an edge's non-merging endpoint
590/// may live in any namespace. Returns `None` if `id` resolves to neither table
591/// (e.g. a hard-deleted or otherwise absent record); callers must treat that as
592/// "the endpoint contract cannot be evaluated" and drop the edge rather than
593/// silently allow it through.
594/// `(substrate, kind, entity_type)` for a resolved merge-edge endpoint.
595type MergeEdgeEndpointInfo = (&'static str, String, Option<String>);
596
597fn resolve_merge_edge_endpoint(
598    conn: &rusqlite::Connection,
599    id: Uuid,
600) -> Result<Option<MergeEdgeEndpointInfo>, SqliteError> {
601    let id_str = id.to_string();
602    if let Some((kind, entity_type)) = conn
603        .query_row(
604            "SELECT kind, entity_type FROM entities WHERE id = ?1",
605            rusqlite::params![&id_str],
606            |row| Ok((row.get::<_, String>(0)?, row.get::<_, Option<String>>(1)?)),
607        )
608        .optional()
609        .map_err(SqliteError::Rusqlite)?
610    {
611        return Ok(Some(("entity", kind, entity_type)));
612    }
613    if let Some(kind) = conn
614        .query_row(
615            "SELECT kind FROM notes WHERE id = ?1",
616            rusqlite::params![&id_str],
617            |row| row.get::<_, String>(0),
618        )
619        .optional()
620        .map_err(SqliteError::Rusqlite)?
621    {
622        return Ok(Some(("note", kind, None)));
623    }
624    Ok(None)
625}
626
627/// `true` if `(src_sub, src_kind, src_type) -[relation]-> (tgt_sub, tgt_kind, tgt_type)`
628/// is permitted under the base ADR-002 entity allowlist or a pack-declared
629/// `EdgeEndpointRule` — the exact same `endpoint_matches` semantics `link`'s
630/// `validate_edge_relation_endpoints` applies (khive-runtime/src/operations.rs),
631/// reused here rather than re-derived, per the #543/#621 lesson that a parallel
632/// matcher drifts out of sync with the validator.
633///
634/// `annotates` is exempt: its source-must-be-a-note constraint is enforced at
635/// edge creation and unchanged by rewiring (an entity merge only ever rewires
636/// its unfiltered target; a note merge rewiring the source substitutes another
637/// note), and its target may be any substrate. Callers short-circuit `annotates`
638/// before endpoint resolution — an annotates target may be an event or an edge,
639/// which `resolve_merge_edge_endpoint` cannot resolve; the exemption here is
640/// kept as defense in depth.
641// REASON: the two endpoints each need substrate/kind/entity_type independently —
642// collapsing them into a tuple/struct would obscure which side is which at call
643// sites that already pass them as separate locals.
644#[allow(clippy::too_many_arguments)]
645fn merge_rewire_endpoint_contract_allows(
646    pack_rules: &[EdgeEndpointRule],
647    relation: EdgeRelation,
648    src_sub: &str,
649    src_kind: &str,
650    src_type: Option<&str>,
651    tgt_sub: &str,
652    tgt_kind: &str,
653    tgt_type: Option<&str>,
654) -> bool {
655    if relation == EdgeRelation::Annotates {
656        return true;
657    }
658    // Same-substrate relations permit any note→note pair unconditionally,
659    // matching `validate_edge_relation_endpoints`'s `(Note, Note) => {}` arm.
660    if src_sub == "note" && tgt_sub == "note" && crate::pack::is_special_relation(relation) {
661        return true;
662    }
663    if src_sub == "entity"
664        && tgt_sub == "entity"
665        && base_entity_rule_allows(src_kind, relation, tgt_kind)
666    {
667        return true;
668    }
669    pack_rules.iter().any(|r| {
670        r.relation == relation
671            && endpoint_matches(&r.source, src_sub, src_kind, src_type)
672            && endpoint_matches(&r.target, tgt_sub, tgt_kind, tgt_type)
673    })
674}
675
676// ---------------------------------------------------------------------------
677// Implementation
678// ---------------------------------------------------------------------------
679
680impl KhiveRuntime {
681    /// Patch-style entity update.
682    ///
683    /// Only fields set to `Some(_)` are changed. Re-indexes FTS5 (and vectors if configured)
684    /// when `name` or `description` changes; skips re-indexing for property/tag-only patches.
685    ///
686    /// Returns `RuntimeError::NotFound` if the entity does not exist or belongs to a different
687    /// namespace. Namespace isolation is enforced at the runtime layer.
688    /// Computes the patched `Entity`, `text_changed`, and `changed_fields` without
689    /// writing anything, so both the normal write path and the atomic-prepare path
690    /// share one source of truth for what a patched entity looks like.
691    pub(crate) async fn prepare_update_entity(
692        &self,
693        token: &NamespaceToken,
694        id: Uuid,
695        patch: EntityPatch,
696    ) -> RuntimeResult<(Entity, bool, Vec<&'static str>)> {
697        if let Some(ref name) = patch.name {
698            crate::secret_gate::check(name)?;
699        }
700        if let Some(Some(ref desc)) = patch.description {
701            crate::secret_gate::check(desc)?;
702        }
703        if let Some(ref props) = patch.properties {
704            crate::secret_gate::check_json(props)?;
705        }
706        if let Some(ref tags) = patch.tags {
707            crate::secret_gate::check_tags(tags)?;
708        }
709        let store = self.entities(token)?;
710        let mut entity = store
711            .get_entity(id)
712            .await?
713            .ok_or_else(|| RuntimeError::NotFound(format!("entity {id}")))?;
714
715        let mut text_changed = false;
716        let mut changed_fields: Vec<&'static str> = Vec::new();
717
718        if let Some(name) = patch.name {
719            text_changed |= entity.name != name;
720            entity.name = name;
721            changed_fields.push("name");
722        }
723        if let Some(desc_patch) = patch.description {
724            text_changed |= entity.description != desc_patch;
725            entity.description = desc_patch;
726            changed_fields.push("description");
727        }
728        if let Some(props) = patch.properties {
729            let (merged, _) = merge_properties(
730                &entity.properties,
731                &Some(props),
732                EntityDedupMergePolicy::PreferFrom,
733            );
734            entity.properties = merged;
735            changed_fields.push("properties");
736        }
737        if let Some(tags) = patch.tags {
738            entity.tags = tags;
739            changed_fields.push("tags");
740        }
741
742        entity.updated_at = chrono::Utc::now().timestamp_micros();
743        Ok((entity, text_changed, changed_fields))
744    }
745
746    pub async fn update_entity(
747        &self,
748        token: &NamespaceToken,
749        id: Uuid,
750        patch: EntityPatch,
751    ) -> RuntimeResult<Entity> {
752        Ok(self
753            .update_entity_with_embedding_report(token, id, patch)
754            .await?
755            .0)
756    }
757
758    pub async fn update_entity_with_embedding_report(
759        &self,
760        token: &NamespaceToken,
761        id: Uuid,
762        patch: EntityPatch,
763    ) -> RuntimeResult<(Entity, crate::retrieval::EmbeddingTruncationReport)> {
764        let (entity, text_changed, changed_fields) =
765            self.prepare_update_entity(token, id, patch).await?;
766
767        let store = self.entities(token)?;
768        store.upsert_entity(entity.clone()).await?;
769
770        let embedding_report = if text_changed {
771            self.reindex_entity(token, &entity).await?
772        } else {
773            crate::retrieval::EmbeddingTruncationReport::default()
774        };
775
776        let event_store = self.events(token)?;
777        let event = khive_storage::event::Event::new(
778            entity.namespace.clone(),
779            "update",
780            EventKind::EntityUpdated,
781            SubstrateKind::Entity,
782            "",
783        )
784        .with_target(entity.id)
785        .with_payload(serde_json::json!({
786            "id": entity.id,
787            "namespace": entity.namespace,
788            "changed_fields": changed_fields,
789        }));
790        event_store.append_event(event).await.map_err(|e| {
791            RuntimeError::Internal(format!("update_entity: event store write failed: {e}"))
792        })?;
793
794        Ok((entity, embedding_report))
795    }
796
797    /// Merge `from_id` into `into_id`.
798    ///
799    /// All edges incident to `from_id` are rewired to `into_id`. Self-loops that would
800    /// result from the rewire are dropped. Properties and tags are merged per `strategy`.
801    /// `from_id` is tombstoned with merge provenance and removed from indexes. Returns a summary.
802    ///
803    /// If `dry_run` is true, computes and returns the planned summary without mutating any rows.
804    ///
805    /// Atomic: all SQL (entity reads/writes, edge rewires, FTS updates, vec-index delete)
806    /// runs on a single pool connection inside one `BEGIN IMMEDIATE` transaction via
807    /// `merge_entity_sql`. If embedding vectors are configured, the vector re-insert for
808    /// `into_id` is performed after the transaction (requires async embedding computation).
809    pub async fn merge_entity(
810        &self,
811        token: &NamespaceToken,
812        into_id: Uuid,
813        from_id: Uuid,
814        strategy: EntityDedupMergePolicy,
815        content_strategy: ContentMergeStrategy,
816        dry_run: bool,
817    ) -> RuntimeResult<MergeSummary> {
818        self.merge_entity_with_reason(
819            token,
820            into_id,
821            from_id,
822            strategy,
823            content_strategy,
824            dry_run,
825            None,
826        )
827        .await
828    }
829
830    /// Merge `from_id` into `into_id` and include an optional reason in the audit event.
831    // REASON: these arguments mirror the merge verb's policy, content strategy,
832    // dry-run, and audit-reason fields; a builder would only move that surface.
833    #[allow(clippy::too_many_arguments)]
834    pub async fn merge_entity_with_reason(
835        &self,
836        token: &NamespaceToken,
837        into_id: Uuid,
838        from_id: Uuid,
839        strategy: EntityDedupMergePolicy,
840        content_strategy: ContentMergeStrategy,
841        dry_run: bool,
842        reason: Option<String>,
843    ) -> RuntimeResult<MergeSummary> {
844        self.merge_entity_with_validation(
845            token,
846            into_id,
847            from_id,
848            strategy,
849            content_strategy,
850            dry_run,
851            reason,
852            EntityMergeValidation::LegacyKind,
853        )
854        .await
855    }
856
857    /// Merge two entities with an explicit override for the entity safety floor.
858    ///
859    /// Non-forced calls enforce entity kind, name similarity, and project compatibility
860    /// against the rows reread inside the merge transaction. Legacy merge methods retain
861    /// their historical same-kind-only policy.
862    /// A non-dry-run override is recorded as `force: true` in the merge event.
863    // REASON: these arguments mirror the merge verb's policy, content strategy,
864    // dry-run, audit-reason, and force fields; a builder would only move that surface.
865    #[allow(clippy::too_many_arguments)]
866    pub async fn merge_entity_with_reason_and_force(
867        &self,
868        token: &NamespaceToken,
869        into_id: Uuid,
870        from_id: Uuid,
871        strategy: EntityDedupMergePolicy,
872        content_strategy: ContentMergeStrategy,
873        dry_run: bool,
874        reason: Option<String>,
875        force: bool,
876    ) -> RuntimeResult<MergeSummary> {
877        let validation = if force {
878            EntityMergeValidation::Forced
879        } else {
880            EntityMergeValidation::SafetyFloor
881        };
882        self.merge_entity_with_validation(
883            token,
884            into_id,
885            from_id,
886            strategy,
887            content_strategy,
888            dry_run,
889            reason,
890            validation,
891        )
892        .await
893    }
894
895    #[allow(clippy::too_many_arguments)]
896    async fn merge_entity_with_validation(
897        &self,
898        token: &NamespaceToken,
899        into_id: Uuid,
900        from_id: Uuid,
901        strategy: EntityDedupMergePolicy,
902        content_strategy: ContentMergeStrategy,
903        dry_run: bool,
904        reason: Option<String>,
905        validation: EntityMergeValidation,
906    ) -> RuntimeResult<MergeSummary> {
907        if let Some(reason) = reason.as_deref() {
908            crate::secret_gate::check(reason)?;
909        }
910        if into_id == from_id {
911            return Err(RuntimeError::InvalidInput(
912                "cannot merge an entity into itself".into(),
913            ));
914        }
915        let ns = token.namespace().as_str().to_owned();
916        let fts_table = "fts_entities".to_string();
917        // One immutable registry view governs transactional deletion, table
918        // preparation, and survivor reindex. A late model belongs to a later
919        // write/backfill rather than only one leg of this merge.
920        let embedding_plan = EmbeddingModelPlan::capture(self);
921        let vec_tables = embedding_plan.vector_tables();
922        // Loaded once here (sync, cheap) so the rewire loop can evaluate the
923        // endpoint contract without an async round-trip per edge (khive#1216).
924        let pack_rules = self.pack_edge_rules();
925
926        // Ensure all required tables exist (idempotent DDL) before the transaction.
927        let _ = self.entities(token)?;
928        let _ = self.graph(token)?;
929        let _ = self.text(token)?;
930        // vectors_for_model (not the default-model-only self.vectors()) so
931        // custom-only runtimes (no default embedding_model) still get DDL primed.
932        for model_name in embedding_plan.model_names() {
933            let _ = self.vectors_for_model(token, model_name)?;
934        }
935
936        let pool = self.backend().pool_arc();
937        // When the write queue is enabled, route this multi-statement merge through
938        // the single-writer task instead of the pool's writer mutex. A lookup
939        // failure degrades to the legacy mutex path rather than failing the merge.
940        let writer_task = pool.writer_task_handle().ok().flatten();
941
942        let (mut summary, updated_entity) = if let Some(writer_task) = writer_task {
943            writer_task
944                .send(move |conn| {
945                    merge_entity_sql(
946                        conn,
947                        ns,
948                        fts_table,
949                        vec_tables,
950                        into_id,
951                        from_id,
952                        strategy,
953                        content_strategy,
954                        dry_run,
955                        pack_rules,
956                        validation,
957                    )
958                    .map_err(|e| {
959                        khive_storage::StorageError::driver(
960                            khive_storage::StorageCapability::Entities,
961                            "merge_entity",
962                            e,
963                        )
964                    })
965                })
966                .await
967                .map_err(map_merge_entity_storage_error)?
968        } else {
969            tokio::task::spawn_blocking(move || {
970                let guard = pool.writer()?;
971                let mut refusal = None;
972                let result = guard.transaction(|conn| {
973                    merge_entity_sql(
974                        conn,
975                        ns,
976                        fts_table,
977                        vec_tables,
978                        into_id,
979                        from_id,
980                        strategy,
981                        content_strategy,
982                        dry_run,
983                        pack_rules,
984                        validation,
985                    )
986                    .map_err(|error| match error {
987                        MergeEntitySqlError::Sqlite(error) => error,
988                        MergeEntitySqlError::Refusal(error) => {
989                            refusal = Some(error);
990                            SqliteError::InvalidData(
991                                "entity merge refused by transactional policy".to_string(),
992                            )
993                        }
994                    })
995                });
996                match refusal {
997                    Some(error) => Err(error.into_runtime_error()),
998                    None => result.map_err(RuntimeError::from),
999                }
1000            })
1001            .await
1002            .map_err(|e| RuntimeError::Internal(e.to_string()))??
1003        };
1004
1005        // FTS and vec-deletes already committed inside the transaction above;
1006        // only the embedding re-insert needs an async step outside it.
1007        if !dry_run && !embedding_plan.is_empty() {
1008            summary.embedding_truncation = self
1009                .reindex_entity_with_plan(token, &updated_entity, &embedding_plan)
1010                .await?;
1011        }
1012
1013        // Dry-run is a read-only preview: it must not append a merge event.
1014        if !dry_run {
1015            let event_store = self.events(token)?;
1016            // Mirror the wire-level strategy spelling from MergeParams so consumers
1017            // can round-trip the policy string back into a request.
1018            let policy_str = match strategy {
1019                EntityDedupMergePolicy::PreferInto => "prefer_into",
1020                EntityDedupMergePolicy::PreferFrom => "prefer_from",
1021                EntityDedupMergePolicy::Union => "union",
1022            };
1023            let mut payload = serde_json::json!({
1024                "into_id": summary.kept_id,
1025                "from_id": summary.removed_id,
1026                "policy": policy_str,
1027                "content_strategy": format!("{:?}", content_strategy),
1028                "edges_rewired": summary.edges_rewired,
1029                "edges_contract_skipped": summary.edges_contract_skipped,
1030                "edge_conflict_preimages": &summary.edge_conflict_preimages,
1031            });
1032            if let Some(reason) = reason {
1033                payload["reason"] = serde_json::Value::String(reason);
1034            }
1035            if validation == EntityMergeValidation::Forced {
1036                payload["force"] = serde_json::Value::Bool(true);
1037            }
1038            let event = khive_storage::event::Event::new(
1039                updated_entity.namespace.clone(),
1040                "merge",
1041                EventKind::EntityMerged,
1042                SubstrateKind::Entity,
1043                "",
1044            )
1045            .with_target(summary.kept_id)
1046            .with_payload(payload);
1047            event_store.append_event(event).await.map_err(|e| {
1048                RuntimeError::Internal(format!("merge_entity: event store write failed: {e}"))
1049            })?;
1050        }
1051
1052        Ok(summary)
1053    }
1054
1055    // ---- Internal helpers ----
1056
1057    /// Re-upsert FTS5 document and vector(s) for the entity across all registered models.
1058    ///
1059    /// Uses `entity.namespace` — the authoritative namespace stored on the record — rather
1060    /// than the caller-supplied `namespace` parameter. This prevents a cross-namespace
1061    /// reindex from writing the search document into the wrong namespace's FTS index.
1062    ///
1063    /// Best-effort for vectors: if embedding or inserting for a particular model fails,
1064    /// logs a warning and continues to the next model. The FTS step is fail-closed
1065    /// (propagates error). Callers (update_entity, merge_entity) have already committed
1066    /// the entity row, so a partial embed miss leaves a stale vector rather than
1067    /// rolling back the update — acceptable because SqliteVecStore::insert is an upsert
1068    /// (the prior vector stays intact on failure, keeping the record searchable).
1069    pub(crate) async fn reindex_entity(
1070        &self,
1071        token: &NamespaceToken,
1072        entity: &Entity,
1073    ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1074        let embedding_plan = EmbeddingModelPlan::capture(self);
1075        self.reindex_entity_with_plan(token, entity, &embedding_plan)
1076            .await
1077    }
1078
1079    async fn reindex_entity_with_plan(
1080        &self,
1081        token: &NamespaceToken,
1082        entity: &Entity,
1083        embedding_plan: &EmbeddingModelPlan,
1084    ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1085        // Use entity.namespace (authoritative) rather than token.namespace().as_str() (caller claim).
1086        let ns = entity.namespace.clone();
1087        let doc = entity_fts_document(entity);
1088        let embed_body = doc.body.clone();
1089        self.text(token)?.upsert_document(doc).await?;
1090
1091        let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1092        for model_name in embedding_plan.model_names() {
1093            match self
1094                .embed_document_with_model_outcome_for_token(token, model_name, &embed_body)
1095                .await
1096            {
1097                Ok(outcome) => {
1098                    report.observe(&outcome);
1099                    match self.vectors_for_model(token, model_name) {
1100                        Ok(vs) => {
1101                            if let Err(e) = vs
1102                                .insert(
1103                                    entity.id,
1104                                    SubstrateKind::Entity,
1105                                    &ns,
1106                                    "entity.body",
1107                                    vec![outcome.vector],
1108                                )
1109                                .await
1110                            {
1111                                tracing::warn!(
1112                                    model = model_name,
1113                                    id = %entity.id,
1114                                    "reindex_entity: vector insert failed, skipping model: {e}"
1115                                );
1116                            }
1117                        }
1118                        Err(e) => {
1119                            tracing::warn!(
1120                                model = model_name,
1121                                id = %entity.id,
1122                                "reindex_entity: could not access vector store for model, skipping: {e}"
1123                            );
1124                        }
1125                    }
1126                }
1127                Err(e) => {
1128                    tracing::warn!(
1129                        model = model_name,
1130                        id = %entity.id,
1131                        "reindex_entity: embed failed for model, skipping: {e}"
1132                    );
1133                }
1134            }
1135        }
1136
1137        Ok(report)
1138    }
1139
1140    /// Remove an entity from FTS5 and vector indexes across all registered models.
1141    pub(crate) async fn remove_from_indexes(
1142        &self,
1143        token: &NamespaceToken,
1144        id: Uuid,
1145    ) -> RuntimeResult<()> {
1146        let ns = token.namespace().as_str().to_owned();
1147        self.text(token)?.delete_document(&ns, id).await?;
1148        for model_name in self.registered_embedding_model_names() {
1149            self.vectors_for_model(token, &model_name)?
1150                .delete(id)
1151                .await?;
1152        }
1153        Ok(())
1154    }
1155
1156    /// Re-upsert FTS5 document and vector(s) for the note across all registered models.
1157    ///
1158    /// Best-effort for vectors: mirrors reindex_entity's warn-and-continue policy.
1159    pub(crate) async fn reindex_note(
1160        &self,
1161        token: &NamespaceToken,
1162        note: &khive_storage::note::Note,
1163    ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1164        let embedding_plan = EmbeddingModelPlan::capture(self);
1165        self.reindex_note_with_plan(token, note, &embedding_plan)
1166            .await
1167    }
1168
1169    async fn reindex_note_with_plan(
1170        &self,
1171        token: &NamespaceToken,
1172        note: &khive_storage::note::Note,
1173        embedding_plan: &EmbeddingModelPlan,
1174    ) -> RuntimeResult<crate::retrieval::EmbeddingTruncationReport> {
1175        self.text_for_notes(token)?
1176            .upsert_document(note_fts_document(note))
1177            .await?;
1178
1179        let ns = note.namespace.clone();
1180        let mut report = crate::retrieval::EmbeddingTruncationReport::default();
1181        for model_name in embedding_plan.model_names() {
1182            match self
1183                .embed_document_with_model_outcome_for_token(
1184                    token,
1185                    model_name,
1186                    &note_embedding_text(note),
1187                )
1188                .await
1189            {
1190                Ok(outcome) => {
1191                    report.observe(&outcome);
1192                    match self.vectors_for_model(token, model_name) {
1193                        Ok(vs) => {
1194                            if let Err(e) = vs
1195                                .insert(
1196                                    note.id,
1197                                    SubstrateKind::Note,
1198                                    &ns,
1199                                    "note.content",
1200                                    vec![outcome.vector],
1201                                )
1202                                .await
1203                            {
1204                                tracing::warn!(
1205                                    model = model_name,
1206                                    id = %note.id,
1207                                    "reindex_note: vector insert failed, skipping model: {e}"
1208                                );
1209                            }
1210                        }
1211                        Err(e) => {
1212                            tracing::warn!(
1213                                model = model_name,
1214                                id = %note.id,
1215                                "reindex_note: could not access vector store for model, skipping: {e}"
1216                            );
1217                        }
1218                    }
1219                }
1220                Err(e) => {
1221                    tracing::warn!(
1222                        model = model_name,
1223                        id = %note.id,
1224                        "reindex_note: embed failed for model, skipping: {e}"
1225                    );
1226                }
1227            }
1228        }
1229        Ok(report)
1230    }
1231
1232    /// Computes the patched `Note` and `text_changed` without writing, mirroring
1233    /// `prepare_update_entity` so both the normal write path and the
1234    /// atomic-prepare path share one source of truth.
1235    pub(crate) async fn prepare_update_note(
1236        &self,
1237        token: &NamespaceToken,
1238        id: Uuid,
1239        patch: NotePatch,
1240    ) -> RuntimeResult<(khive_storage::note::Note, bool)> {
1241        if let Some(ref content) = patch.content {
1242            crate::secret_gate::check(content)?;
1243        }
1244        if let Some(Some(ref name)) = patch.name {
1245            crate::secret_gate::check(name)?;
1246        }
1247        if let Some(ref props) = patch.properties {
1248            crate::secret_gate::check_json(props)?;
1249        }
1250        let store = self.notes(token)?;
1251        let mut note = store
1252            .get_note(id)
1253            .await?
1254            .ok_or_else(|| RuntimeError::NotFound(format!("note {id}")))?;
1255
1256        reject_pack_managed_schedule_mutation(&note, "update")?;
1257
1258        let mut text_changed = false;
1259
1260        if let Some(name_patch) = patch.name {
1261            text_changed |= note.name != name_patch;
1262            note.name = name_patch;
1263        }
1264        if let Some(content) = patch.content {
1265            text_changed |= note.content != content;
1266            note.content = content;
1267        }
1268        if let Some(salience_patch) = patch.salience {
1269            // Reject invalid salience rather than silently clamping caller input.
1270            if let Some(s) = salience_patch {
1271                if !s.is_finite() || !(0.0..=1.0).contains(&s) {
1272                    return Err(crate::RuntimeError::InvalidInput(format!(
1273                        "salience must be a finite value in [0.0, 1.0]; got {s}"
1274                    )));
1275                }
1276            }
1277            note.salience = salience_patch;
1278        }
1279        if let Some(decay_patch) = patch.decay_factor {
1280            // Reject invalid decay_factor rather than silently clamping caller input.
1281            if let Some(d) = decay_patch {
1282                if !d.is_finite() || d < 0.0 {
1283                    return Err(crate::RuntimeError::InvalidInput(format!(
1284                        "decay_factor must be a finite value >= 0.0; got {d}"
1285                    )));
1286                }
1287            }
1288            note.decay_factor = decay_patch;
1289        }
1290        if let Some(props) = patch.properties {
1291            let (merged, _) = merge_properties(
1292                &note.properties,
1293                &Some(props),
1294                EntityDedupMergePolicy::PreferFrom,
1295            );
1296            note.properties = merged;
1297        }
1298        if let Some(status) = patch.kind_status {
1299            note.status = status;
1300        }
1301
1302        note.updated_at = chrono::Utc::now().timestamp_micros();
1303        Ok((note, text_changed))
1304    }
1305
1306    /// Patch-style note update.
1307    pub async fn update_note(
1308        &self,
1309        token: &NamespaceToken,
1310        id: Uuid,
1311        patch: NotePatch,
1312    ) -> RuntimeResult<khive_storage::note::Note> {
1313        Ok(self
1314            .update_note_with_embedding_report(token, id, patch)
1315            .await?
1316            .0)
1317    }
1318
1319    pub async fn update_note_with_embedding_report(
1320        &self,
1321        token: &NamespaceToken,
1322        id: Uuid,
1323        patch: NotePatch,
1324    ) -> RuntimeResult<(
1325        khive_storage::note::Note,
1326        crate::retrieval::EmbeddingTruncationReport,
1327    )> {
1328        let (note, text_changed) = self.prepare_update_note(token, id, patch).await?;
1329
1330        let store = self.notes(token)?;
1331        store.upsert_note(note.clone()).await?;
1332
1333        let embedding_report = if text_changed {
1334            let report = self.reindex_note(token, &note).await?;
1335            // Notify any pack-owned vector cache (e.g. a warm ANN index) that this
1336            // note's embedding changed, via a generic hook so khive-runtime/pack-kg
1337            // never take a dependency on the consuming pack. No-op if unregistered.
1338            self.fire_note_mutation_hook(&note.kind, note.id).await;
1339            report
1340        } else {
1341            crate::retrieval::EmbeddingTruncationReport::default()
1342        };
1343
1344        Ok((note, embedding_report))
1345    }
1346
1347    /// Merge `from_id` note into `into_id` note.
1348    ///
1349    /// Both notes must exist in the namespace and have the same `kind`. Content is merged
1350    /// per `content_strategy`. Properties are merged per `strategy`. `from_id` is
1351    /// tombstoned (status='deleted', deleted_at set). Returns a summary.
1352    ///
1353    /// If `dry_run` is true, computes and returns the planned summary without mutating
1354    /// any rows, edges, or indexes.
1355    pub async fn merge_note(
1356        &self,
1357        token: &NamespaceToken,
1358        into_id: Uuid,
1359        from_id: Uuid,
1360        strategy: EntityDedupMergePolicy,
1361        content_strategy: ContentMergeStrategy,
1362        dry_run: bool,
1363    ) -> RuntimeResult<MergeSummary> {
1364        self.merge_note_with_reason(
1365            token,
1366            into_id,
1367            from_id,
1368            strategy,
1369            content_strategy,
1370            dry_run,
1371            None,
1372        )
1373        .await
1374    }
1375
1376    /// Merge `from_id` note into `into_id` note and include an optional audit reason.
1377    // REASON: these arguments mirror the merge verb's policy, content strategy,
1378    // dry-run, and audit-reason fields; a builder would only move that surface.
1379    #[allow(clippy::too_many_arguments)]
1380    pub async fn merge_note_with_reason(
1381        &self,
1382        token: &NamespaceToken,
1383        into_id: Uuid,
1384        from_id: Uuid,
1385        strategy: EntityDedupMergePolicy,
1386        content_strategy: ContentMergeStrategy,
1387        dry_run: bool,
1388        reason: Option<String>,
1389    ) -> RuntimeResult<MergeSummary> {
1390        if let Some(reason) = reason.as_deref() {
1391            crate::secret_gate::check(reason)?;
1392        }
1393        if into_id == from_id {
1394            return Err(RuntimeError::InvalidInput(
1395                "cannot merge a note into itself".into(),
1396            ));
1397        }
1398        let ns = token.namespace().as_str().to_string();
1399        let fts_table = "fts_notes".to_string();
1400        // Keep deletion, table preparation, and survivor reindex on the same
1401        // immutable registry view; see the entity merge path above.
1402        let embedding_plan = EmbeddingModelPlan::capture(self);
1403        let vec_tables = embedding_plan.vector_tables();
1404        let pack_rules = self.pack_edge_rules();
1405
1406        let note_store = self.notes(token)?;
1407        let into_note = note_store
1408            .get_note(into_id)
1409            .await?
1410            .ok_or_else(|| RuntimeError::NotFound("not found in this namespace".into()))?;
1411        Self::ensure_namespace(&into_note.namespace, &ns)?;
1412
1413        let from_note = note_store
1414            .get_note(from_id)
1415            .await?
1416            .ok_or_else(|| RuntimeError::NotFound("not found in this namespace".into()))?;
1417        Self::ensure_namespace(&from_note.namespace, &ns)?;
1418
1419        reject_pack_managed_schedule_mutation(&into_note, "merge")?;
1420        reject_pack_managed_schedule_mutation(&from_note, "merge")?;
1421
1422        let _ = self.graph(token)?;
1423        let _ = self.text_for_notes(token)?;
1424        for model_name in embedding_plan.model_names() {
1425            let _ = self.vectors_for_model(token, model_name)?;
1426        }
1427
1428        let pool = self.backend().pool_arc();
1429        let writer_task = pool.writer_task_handle().ok().flatten();
1430
1431        let (mut summary, updated_note) = if let Some(writer_task) = writer_task {
1432            writer_task
1433                .send(move |conn| {
1434                    merge_note_sql(
1435                        conn,
1436                        ns,
1437                        fts_table,
1438                        vec_tables,
1439                        into_id,
1440                        from_id,
1441                        strategy,
1442                        content_strategy,
1443                        dry_run,
1444                        pack_rules,
1445                    )
1446                    .map_err(|e| {
1447                        khive_storage::StorageError::driver(
1448                            khive_storage::StorageCapability::Notes,
1449                            "merge_note",
1450                            e,
1451                        )
1452                    })
1453                })
1454                .await
1455                .map_err(RuntimeError::Storage)?
1456        } else {
1457            tokio::task::spawn_blocking(move || {
1458                let guard = pool.writer()?;
1459                guard.transaction(|conn| {
1460                    merge_note_sql(
1461                        conn,
1462                        ns,
1463                        fts_table,
1464                        vec_tables,
1465                        into_id,
1466                        from_id,
1467                        strategy,
1468                        content_strategy,
1469                        dry_run,
1470                        pack_rules,
1471                    )
1472                })
1473            })
1474            .await
1475            .map_err(|e| RuntimeError::Internal(e.to_string()))??
1476        };
1477
1478        if !dry_run && !embedding_plan.is_empty() {
1479            summary.embedding_truncation = self
1480                .reindex_note_with_plan(token, &updated_note, &embedding_plan)
1481                .await?;
1482            // A merge changes the same ANN corpus as update_note's text_changed
1483            // branch, so fire the same mutation hook regardless of which public
1484            // write path reached the corpus change.
1485            self.fire_note_mutation_hook(&updated_note.kind, updated_note.id)
1486                .await;
1487        }
1488
1489        // Dry-run is a read-only preview: it must not append a merge event.
1490        if !dry_run {
1491            let event_store = self.events(token)?;
1492            // Mirror the wire-level strategy spelling from MergeParams so consumers
1493            // can round-trip the policy string back into a request.
1494            let policy_str = match strategy {
1495                EntityDedupMergePolicy::PreferInto => "prefer_into",
1496                EntityDedupMergePolicy::PreferFrom => "prefer_from",
1497                EntityDedupMergePolicy::Union => "union",
1498            };
1499            let mut payload = serde_json::json!({
1500                "into_id": summary.kept_id,
1501                "from_id": summary.removed_id,
1502                "policy": policy_str,
1503                "content_strategy": format!("{:?}", content_strategy),
1504                "edges_rewired": summary.edges_rewired,
1505                "edges_contract_skipped": summary.edges_contract_skipped,
1506                "edge_conflict_preimages": &summary.edge_conflict_preimages,
1507            });
1508            if let Some(reason) = reason {
1509                payload["reason"] = serde_json::Value::String(reason);
1510            }
1511            let event = khive_storage::event::Event::new(
1512                updated_note.namespace.clone(),
1513                "merge",
1514                EventKind::NoteMerged,
1515                SubstrateKind::Note,
1516                "",
1517            )
1518            .with_target(summary.kept_id)
1519            .with_payload(payload);
1520            event_store.append_event(event).await.map_err(|e| {
1521                RuntimeError::Internal(format!("merge_note: event store write failed: {e}"))
1522            })?;
1523        }
1524
1525        Ok(summary)
1526    }
1527}
1528
1529/// Keep executable schedule intent behind the schedule pack's state-machine verbs.
1530///
1531/// `scheduled_event` notes carry both replay payloads and lifecycle state. Allowing
1532/// generic note update/merge to rewrite either would turn the immutable creator event
1533/// into a bearer credential for attacker-selected work: replay would attribute the
1534/// changed row to its original creator. Schedule's own transitions use its private
1535/// note-store CAS helpers and therefore do not pass through this generic curation seam.
1536fn reject_pack_managed_schedule_mutation(
1537    note: &khive_storage::note::Note,
1538    operation: &str,
1539) -> RuntimeResult<()> {
1540    if note.kind == "scheduled_event" {
1541        return Err(RuntimeError::InvalidInput(format!(
1542            "cannot {operation} a schedule-managed `scheduled_event` note through generic KG \
1543             mutation; use schedule.cancel or create a replacement schedule"
1544        )));
1545    }
1546    Ok(())
1547}
1548
1549// ---------------------------------------------------------------------------
1550// FTS document construction
1551// ---------------------------------------------------------------------------
1552
1553/// Build the canonical text embedded for an entity on create, update, merge,
1554/// and repair paths.
1555pub fn entity_embedding_text(entity: &Entity) -> String {
1556    match &entity.description {
1557        Some(description) if !description.is_empty() => {
1558            format!("{} {description}", entity.name)
1559        }
1560        _ => entity.name.clone(),
1561    }
1562}
1563
1564/// Build the canonical text embedded for a note when no explicit bounded
1565/// embedding prefix was supplied at creation time.
1566pub fn note_embedding_text(note: &Note) -> String {
1567    note.content.clone()
1568}
1569
1570/// Build the `TextDocument` for an entity. This is the single source of truth for
1571/// entity FTS document shape; all write paths (create, update, merge, reindex, backfill)
1572/// must go through this function so search parity is guaranteed.
1573///
1574/// Body rule: when the entity has a non-empty description, prepend the name
1575/// (`"<name> <description>"`). Otherwise the body is just the name. This
1576/// matches the FTS index contract: `title` and `body` are the ranked columns;
1577/// `tags`, `metadata`, and `namespace` are UNINDEXED.
1578///
1579/// `updated_at` is taken from the entity's own timestamp so that backfill and
1580/// reindex runs record the entity's actual mutation time rather than the
1581/// reindex execution time.
1582pub fn entity_fts_document(entity: &Entity) -> TextDocument {
1583    let updated_at =
1584        chrono::DateTime::from_timestamp_micros(entity.updated_at).unwrap_or_else(chrono::Utc::now);
1585    TextDocument {
1586        subject_id: entity.id,
1587        kind: SubstrateKind::Entity,
1588        title: Some(entity.name.clone()),
1589        body: entity_embedding_text(entity),
1590        tags: entity.tags.clone(),
1591        namespace: entity.namespace.clone(),
1592        metadata: entity.properties.clone(),
1593        updated_at,
1594    }
1595}
1596
1597/// Build the `TextDocument` for a note. This is the single source of truth for
1598/// note FTS document shape; all write paths (create, update, reindex) must go
1599/// through this function so recall parity is guaranteed. Changes here apply to
1600/// every caller automatically.
1601///
1602/// Body rule: when the note has a `name`, prepend it to the content
1603/// (`"<name> <content>"`). This matches the FTS index contract: title and body
1604/// both contribute to ranking, and the name is the most salient signal.
1605///
1606/// `updated_at` is taken from the note's own timestamp (not `Utc::now()`) so
1607/// that backfill and reindex runs record the note's actual mutation time rather
1608/// than the reindex execution time.
1609pub fn note_fts_document(note: &Note) -> TextDocument {
1610    let body = match &note.name {
1611        Some(n) => format!("{n} {}", note.content),
1612        None => note.content.clone(),
1613    };
1614    let updated_at =
1615        chrono::DateTime::from_timestamp_micros(note.updated_at).unwrap_or_else(chrono::Utc::now);
1616    TextDocument {
1617        subject_id: note.id,
1618        kind: SubstrateKind::Note,
1619        title: note.name.clone(),
1620        body,
1621        tags: vec![],
1622        namespace: note.namespace.clone(),
1623        metadata: note.properties.clone(),
1624        updated_at,
1625    }
1626}
1627
1628/// SQL-bind–ready scalars derived from [`note_fts_document`].
1629///
1630/// Used by `merge_note_sql` to guarantee that the raw SQL FTS INSERT stores
1631/// exactly what [`Fts5TextSearch::upsert_document`] would write, preventing
1632/// null/empty-string divergence on the `title` column for nameless notes.
1633pub(crate) struct NoteFtsScalars {
1634    /// Empty string when `note.name` is `None` — matches the `unwrap_or("")` in
1635    /// `Fts5TextSearch::upsert_document`.
1636    pub title: String,
1637    pub body: String,
1638    /// Always the JSON array `"[]"`.
1639    pub tags: String,
1640    /// Serialised `note.properties`, or `None` when properties are absent.
1641    pub metadata: Option<String>,
1642    /// `note.updated_at` converted to `DateTime<Utc>` timestamp_micros.
1643    pub updated_at_micros: i64,
1644}
1645
1646/// Derive [`NoteFtsScalars`] from a [`Note`].
1647///
1648/// All values match the encoding that [`Fts5TextSearch::upsert_document`]
1649/// applies when given the output of [`note_fts_document`].
1650pub(crate) fn note_fts_scalars(note: &Note) -> NoteFtsScalars {
1651    let doc = note_fts_document(note);
1652    NoteFtsScalars {
1653        title: doc.title.unwrap_or_default(),
1654        body: doc.body,
1655        tags: "[]".to_string(),
1656        metadata: doc
1657            .metadata
1658            .as_ref()
1659            .map(|v| serde_json::to_string(v).unwrap_or_default()),
1660        updated_at_micros: doc.updated_at.timestamp_micros(),
1661    }
1662}
1663
1664// ---------------------------------------------------------------------------
1665// Transactional merge SQL helpers
1666// ---------------------------------------------------------------------------
1667
1668/// Read one entity row by ID within a namespace, returning `SqliteError` on missing/wrong-ns.
1669fn read_merge_entity(
1670    conn: &rusqlite::Connection,
1671    id: Uuid,
1672    namespace: &str,
1673) -> Result<Entity, SqliteError> {
1674    let id_str = id.to_string();
1675    let mut stmt = conn.prepare(
1676        "SELECT id, namespace, kind, entity_type, name, description, properties, tags, \
1677         created_at, updated_at, deleted_at, merged_into, merge_event_id, content_ref \
1678         FROM entities WHERE id = ?1 AND deleted_at IS NULL",
1679    )?;
1680    let mut rows = stmt.query(rusqlite::params![id_str])?;
1681    let row = rows
1682        .next()?
1683        .ok_or_else(|| SqliteError::InvalidData(format!("entity {id} not found")))?;
1684
1685    let id_s: String = row.get(0)?;
1686    let ns: String = row.get(1)?;
1687    let kind: String = row.get(2)?;
1688    let entity_type: Option<String> = row.get(3)?;
1689    let name: String = row.get(4)?;
1690    let description: Option<String> = row.get(5)?;
1691    let properties_str: Option<String> = row.get(6)?;
1692    let tags_str: String = row.get(7)?;
1693    let created_at: i64 = row.get(8)?;
1694    let updated_at: i64 = row.get(9)?;
1695    let deleted_at: Option<i64> = row.get(10)?;
1696    let merged_into_str: Option<String> = row.get(11)?;
1697    let merge_event_id_str: Option<String> = row.get(12)?;
1698    let content_ref: Option<String> = row.get(13)?;
1699
1700    if ns != namespace {
1701        return Err(SqliteError::InvalidData(format!(
1702            "entity {id} belongs to namespace '{ns}', not '{namespace}'"
1703        )));
1704    }
1705
1706    let entity_id = Uuid::parse_str(&id_s).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1707    let properties: Option<Value> = properties_str
1708        .map(|s| {
1709            serde_json::from_str::<Value>(&s).map_err(|e| SqliteError::InvalidData(e.to_string()))
1710        })
1711        .transpose()?;
1712    let tags: Vec<String> =
1713        serde_json::from_str(&tags_str).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1714    let merged_into = merged_into_str
1715        .as_deref()
1716        .map(Uuid::parse_str)
1717        .transpose()
1718        .map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1719    let merge_event_id = merge_event_id_str
1720        .as_deref()
1721        .map(Uuid::parse_str)
1722        .transpose()
1723        .map_err(|e| SqliteError::InvalidData(e.to_string()))?;
1724
1725    Ok(Entity {
1726        id: entity_id,
1727        namespace: ns,
1728        kind,
1729        entity_type,
1730        name,
1731        description,
1732        properties,
1733        tags,
1734        created_at,
1735        updated_at,
1736        deleted_at,
1737        merged_into,
1738        merge_event_id,
1739        content_ref,
1740    })
1741}
1742
1743/// All merge SQL on one connection inside an already-open `BEGIN IMMEDIATE` transaction.
1744///
1745/// Reads both entities, rewires/drops incident edges, merges entity fields, updates FTS,
1746/// deletes the `from` vec entry (if `vec_table` is Some), and tombstones `from` with merge
1747/// provenance.  Returns the updated `into` entity so the caller can do the async vec re-insert.
1748///
1749/// When `dry_run` is true, all reads and computations are performed but no writes are issued.
1750// REASON: merge requires both entity IDs, the namespace, FTS and vec table names, merge
1751// policy, and dry-run flag — all are load-bearing; reducing to a struct would obscure
1752// the sync/async boundary split that keeps this function off the async runtime.
1753#[allow(clippy::too_many_arguments)]
1754fn merge_entity_sql(
1755    conn: &rusqlite::Connection,
1756    namespace: String,
1757    fts_table: String,
1758    vec_tables: Vec<String>,
1759    into_id: Uuid,
1760    from_id: Uuid,
1761    strategy: EntityDedupMergePolicy,
1762    content_strategy: ContentMergeStrategy,
1763    dry_run: bool,
1764    pack_rules: Vec<EdgeEndpointRule>,
1765    validation: EntityMergeValidation,
1766) -> Result<(MergeSummary, Entity), MergeEntitySqlError> {
1767    let into_entity = read_merge_entity(conn, into_id, &namespace)?;
1768    let from_entity = read_merge_entity(conn, from_id, &namespace)?;
1769
1770    match validation {
1771        EntityMergeValidation::LegacyKind if into_entity.kind != from_entity.kind => {
1772            return Err(MergeEntitySqlError::Refusal(
1773                EntityMergeRefusal::LegacyKind {
1774                    into_id,
1775                    into_kind: into_entity.kind,
1776                    from_id,
1777                    from_kind: from_entity.kind,
1778                },
1779            ));
1780        }
1781        EntityMergeValidation::SafetyFloor => {
1782            validate_entity_merge_floor(&into_entity, &from_entity).map_err(|guard| {
1783                MergeEntitySqlError::Refusal(EntityMergeRefusal::SafetyFloor(guard))
1784            })?;
1785        }
1786        EntityMergeValidation::LegacyKind | EntityMergeValidation::Forced => {}
1787    }
1788
1789    // --- Collect edges incident to from_id ---
1790    let parse_id =
1791        |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
1792
1793    let from_str = from_id.to_string();
1794
1795    // Namespace-agnostic (khive#1236): edge endpoints resolve by-ID regardless of
1796    // namespace (ADR-007 Rev 6), and `link` stamps an edge with its *creator's*
1797    // namespace, not either endpoint's — so an edge incident to `from_id` can live
1798    // in any namespace. Scoping this collection to the merge's own namespace missed
1799    // those edges entirely. Each row's own `namespace` column is carried through
1800    // (`EdgeRow::namespace`) and used for every subsequent SQL op against that row.
1801    let mut outbound: Vec<EdgeRow> = Vec::new();
1802    {
1803        let mut stmt = conn.prepare(
1804            "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
1805                    updated_at, deleted_at, target_backend, metadata \
1806             FROM graph_edges WHERE source_id = ?1",
1807        )?;
1808        let mut rows = stmt.query(rusqlite::params![&from_str])?;
1809        while let Some(row) = rows.next()? {
1810            outbound.push(EdgeRow {
1811                id: parse_id(row.get(0)?)?,
1812                namespace: row.get(1)?,
1813                source_id: parse_id(row.get(2)?)?,
1814                target_id: parse_id(row.get(3)?)?,
1815                relation: row.get(4)?,
1816                weight: row.get(5)?,
1817                created_at: row.get(6)?,
1818                updated_at: row.get(7)?,
1819                deleted_at: row.get(8)?,
1820                target_backend: row.get(9)?,
1821                metadata: row.get(10)?,
1822            });
1823        }
1824    }
1825
1826    let mut inbound: Vec<EdgeRow> = Vec::new();
1827    {
1828        let mut stmt = conn.prepare(
1829            "SELECT id, namespace, source_id, target_id, relation, weight, created_at, \
1830                    updated_at, deleted_at, target_backend, metadata \
1831             FROM graph_edges WHERE target_id = ?1",
1832        )?;
1833        let mut rows = stmt.query(rusqlite::params![&from_str])?;
1834        while let Some(row) = rows.next()? {
1835            inbound.push(EdgeRow {
1836                id: parse_id(row.get(0)?)?,
1837                namespace: row.get(1)?,
1838                source_id: parse_id(row.get(2)?)?,
1839                target_id: parse_id(row.get(3)?)?,
1840                relation: row.get(4)?,
1841                weight: row.get(5)?,
1842                created_at: row.get(6)?,
1843                updated_at: row.get(7)?,
1844                deleted_at: row.get(8)?,
1845                target_backend: row.get(9)?,
1846                metadata: row.get(10)?,
1847            });
1848        }
1849    }
1850
1851    // Deduplicate by edge ID (a self-edge from_id→from_id appears in both lists).
1852    let mut seen: HashSet<Uuid> = HashSet::new();
1853    let mut all_edges: Vec<EdgeRow> = Vec::new();
1854    for edge in outbound.into_iter().chain(inbound) {
1855        if seen.insert(edge.id) {
1856            all_edges.push(edge);
1857        }
1858    }
1859    let original_edges: HashMap<Uuid, EdgeRow> = all_edges
1860        .iter()
1861        .map(|edge| (edge.id, edge.clone()))
1862        .collect();
1863
1864    // --- Merge entity fields ---
1865    let (merged_props, properties_merged) =
1866        merge_properties(&into_entity.properties, &from_entity.properties, strategy);
1867    let merged_name = merge_string_field(&into_entity.name, &from_entity.name, strategy);
1868    let (merged_description, content_appended) = match content_strategy {
1869        ContentMergeStrategy::Append => {
1870            let into_desc = into_entity.description.as_deref().unwrap_or("");
1871            let from_desc = from_entity.description.as_deref().unwrap_or("");
1872            if from_desc.is_empty() {
1873                (into_entity.description.clone(), false)
1874            } else if into_desc.is_empty() {
1875                (from_entity.description.clone(), true)
1876            } else {
1877                (Some(format!("{}\n\n---\n\n{}", into_desc, from_desc)), true)
1878            }
1879        }
1880        // Description selection follows `content_strategy` directly — it is a
1881        // deliberate, independently-settable choice, not derived from the
1882        // entity-field `strategy` (properties/name/tags merge policy).
1883        ContentMergeStrategy::PreferInto => (into_entity.description.clone(), false),
1884        ContentMergeStrategy::PreferFrom => (from_entity.description.clone(), false),
1885    };
1886    let (merged_tags, tags_unioned) = union_tags(&into_entity.tags, &from_entity.tags);
1887
1888    let now = chrono::Utc::now().timestamp_micros();
1889    let into_str = into_id.to_string();
1890    let props_str = merged_props
1891        .as_ref()
1892        .map(|v| serde_json::to_string(v).unwrap_or_default());
1893    let tags_json = serde_json::to_string(&merged_tags).unwrap_or_else(|_| "[]".to_string());
1894
1895    // Writes are gated on `!dry_run` below, but the loop itself always runs so a
1896    // dry-run response reports a predictive `edges_rewired` count instead of zero.
1897    let mut rewired_edge_ids = HashSet::new();
1898    let mut edges_contract_skipped = 0usize;
1899    let mut edge_conflict_preimages = Vec::new();
1900    let mut conflict_deleted_edge_ids = HashSet::new();
1901    for edge in all_edges {
1902        if conflict_deleted_edge_ids.contains(&edge.id) {
1903            continue;
1904        }
1905        let raw_src = if edge.source_id == from_id {
1906            into_id
1907        } else {
1908            edge.source_id
1909        };
1910        let raw_tgt = if edge.target_id == from_id {
1911            into_id
1912        } else {
1913            edge.target_id
1914        };
1915        let relation_typed = edge.relation.parse::<EdgeRelation>().ok();
1916        // Symmetric relations must be stored with source_uuid < target_uuid.
1917        // Apply canonicalization so the conflict check and UPDATE both use the canonical form.
1918        let (new_src, new_tgt) = match relation_typed {
1919            Some(rel) => canonical_edge_endpoints(rel, raw_src, raw_tgt),
1920            None => (raw_src, raw_tgt),
1921        };
1922
1923        if new_src == new_tgt {
1924            if !dry_run {
1925                conn.execute(
1926                    "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
1927                    rusqlite::params![&edge.namespace, edge.id.to_string()],
1928                )?;
1929            }
1930            continue;
1931        }
1932
1933        // Endpoint-contract check (khive#1216): the rewired triple must still pass
1934        // the same allowlist `link` enforces. `into_id` and `from_id` share `kind`
1935        // (enforced by the caller), but `entity_type` may differ between them, so a
1936        // pack rule scoped via `EntityOfType` can accept `from_id`'s edge yet reject
1937        // the post-rewrite pair against `into_id`. A violating edge is dropped and
1938        // counted, mirroring the existing dangling-endpoint skip behavior rather
1939        // than silently writing a contract-violating edge or aborting the merge.
1940        let contract_ok = match relation_typed {
1941            // `annotates` targets may be events or edges, which
1942            // `resolve_merge_edge_endpoint` cannot resolve — evaluate its
1943            // (unconditional) exemption before endpoint resolution so valid
1944            // annotates edges are not dropped as unresolvable.
1945            Some(EdgeRelation::Annotates) => true,
1946            Some(rel) => {
1947                let src_info = if new_src == into_id {
1948                    Some((
1949                        "entity",
1950                        into_entity.kind.clone(),
1951                        into_entity.entity_type.clone(),
1952                    ))
1953                } else {
1954                    resolve_merge_edge_endpoint(conn, new_src)?
1955                };
1956                let tgt_info = if new_tgt == into_id {
1957                    Some((
1958                        "entity",
1959                        into_entity.kind.clone(),
1960                        into_entity.entity_type.clone(),
1961                    ))
1962                } else {
1963                    resolve_merge_edge_endpoint(conn, new_tgt)?
1964                };
1965                match (src_info, tgt_info) {
1966                    (Some((src_sub, src_kind, src_type)), Some((tgt_sub, tgt_kind, tgt_type))) => {
1967                        merge_rewire_endpoint_contract_allows(
1968                            &pack_rules,
1969                            rel,
1970                            src_sub,
1971                            &src_kind,
1972                            src_type.as_deref(),
1973                            tgt_sub,
1974                            &tgt_kind,
1975                            tgt_type.as_deref(),
1976                        )
1977                    }
1978                    // An endpoint no longer resolves (e.g. concurrently hard-deleted)
1979                    // — cannot evaluate the contract, so drop rather than assume ok.
1980                    _ => false,
1981                }
1982            }
1983            // Relation string predates the closed EdgeRelation enum (pre-migration
1984            // data); leave existing behavior in place rather than guessing.
1985            None => true,
1986        };
1987        if !contract_ok {
1988            if !dry_run {
1989                conn.execute(
1990                    "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
1991                    rusqlite::params![&edge.namespace, edge.id.to_string()],
1992                )?;
1993            }
1994            tracing::warn!(
1995                edge_id = %edge.id,
1996                source = %new_src,
1997                target = %new_tgt,
1998                relation = %edge.relation,
1999                "merge_entity: dropping rewired edge — endpoint contract violation post-merge"
2000            );
2001            edges_contract_skipped += 1;
2002            continue;
2003        }
2004
2005        let now_ts = chrono::Utc::now().timestamp_micros();
2006        // Preserve the original edge ID where possible so callers can still get()
2007        // it by the ID returned from link(): update in-place when there's no
2008        // conflict; when into_id already owns this (source,target,relation), the
2009        // incoming (from-side) duplicate is dropped and the existing into-edge is
2010        // left untouched (ADR-039 `ON CONFLICT ... DO NOTHING` semantics).
2011        // Check for a conflict: does into_id already have this natural key?
2012        let conflict_id: Option<String> = {
2013            let conflict_src = new_src.to_string();
2014            let conflict_tgt = new_tgt.to_string();
2015            conn.query_row(
2016                khive_db::stores::graph::EDGE_SYMMETRIC_CONFLICT_PROBE_SQL,
2017                rusqlite::params![
2018                    &edge.namespace,
2019                    &conflict_src,
2020                    &conflict_tgt,
2021                    &edge.relation,
2022                    edge.id.to_string(),
2023                ],
2024                |row| row.get(0),
2025            )
2026            .optional()
2027            .map_err(SqliteError::Rusqlite)?
2028        };
2029
2030        if let Some(conflict_id) = conflict_id {
2031            // A live or soft-deleted row already owns this natural key: drop the
2032            // incoming duplicate. The surviving row's weight/metadata/deleted_at
2033            // are never mutated or resurrected. Capture the duplicate and the
2034            // complete hard-delete cascade before removing either, so the audit
2035            // event contains enough state to restore every destroyed row.
2036            let surviving_edge_id = Uuid::parse_str(&conflict_id)
2037                .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
2038            let incident_edge_preimages =
2039                collect_conflict_incident_edge_preimages(conn, edge.id, &original_edges)?;
2040            for incident in &incident_edge_preimages {
2041                conflict_deleted_edge_ids.insert(incident.id);
2042                rewired_edge_ids.remove(&incident.id);
2043            }
2044            conflict_deleted_edge_ids.insert(edge.id);
2045            rewired_edge_ids.insert(edge.id);
2046
2047            if !dry_run {
2048                delete_conflict_incident_edges(conn, &incident_edge_preimages)?;
2049                conn.execute(
2050                    khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
2051                    rusqlite::params![&edge.namespace, edge.id.to_string()],
2052                )?;
2053            }
2054            edge_conflict_preimages.push(MergeEdgeConflictPreimage {
2055                surviving_edge_id,
2056                dropped_edge: edge_row_preimage(&edge)?,
2057                incident_edge_preimages,
2058            });
2059        } else {
2060            if dry_run {
2061                rewired_edge_ids.insert(edge.id);
2062                continue;
2063            }
2064            let changed = conn.execute(
2065                "UPDATE graph_edges SET \
2066                     source_id = ?1, target_id = ?2, updated_at = ?3 \
2067                     WHERE namespace = ?4 AND id = ?5",
2068                rusqlite::params![
2069                    new_src.to_string(),
2070                    new_tgt.to_string(),
2071                    now_ts,
2072                    &edge.namespace,
2073                    edge.id.to_string(),
2074                ],
2075            )?;
2076            if changed > 0 {
2077                rewired_edge_ids.insert(edge.id);
2078            }
2079        }
2080    }
2081    let edges_rewired = rewired_edge_ids.len();
2082
2083    if !dry_run {
2084        // UPDATE only the merged fields — a full-row INSERT OR REPLACE silently
2085        // nulls any column missing from its list (entity_type and content_ref
2086        // were lost this way; khive#1214).
2087        conn.execute(
2088            "UPDATE entities SET \
2089                 name = ?1, description = ?2, properties = ?3, tags = ?4, \
2090                 updated_at = ?5, merged_into = NULL, merge_event_id = NULL \
2091             WHERE namespace = ?6 AND id = ?7",
2092            rusqlite::params![
2093                &merged_name,
2094                &merged_description,
2095                &props_str,
2096                &tags_json,
2097                now,
2098                &namespace,
2099                &into_str,
2100            ],
2101        )?;
2102
2103        // Body formula mirrors entity_fts_document (the canonical constructor):
2104        // this path is sync/spawn_blocking so it can't call it directly, but
2105        // must stay field-identical.
2106        let fts_body = match &merged_description {
2107            Some(d) if !d.is_empty() => format!("{} {}", merged_name, d),
2108            _ => merged_name.clone(),
2109        };
2110        let kind_str = SubstrateKind::Entity.to_string();
2111
2112        conn.execute(
2113            &format!(
2114                "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2115                fts_table
2116            ),
2117            rusqlite::params![&namespace, &into_str],
2118        )?;
2119        conn.execute(
2120            &format!(
2121                "INSERT INTO {} \
2122                 (subject_id, kind, title, body, tags, namespace, metadata, updated_at) \
2123                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2124                fts_table
2125            ),
2126            rusqlite::params![
2127                &into_str,
2128                &kind_str,
2129                &merged_name,
2130                &fts_body,
2131                &tags_json,
2132                &namespace,
2133                &props_str,
2134                now,
2135            ],
2136        )?;
2137
2138        conn.execute(
2139            &format!(
2140                "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2141                fts_table
2142            ),
2143            rusqlite::params![&namespace, &from_str],
2144        )?;
2145
2146        khive_db::stores::vectors::delete_subject_from_vector_tables(
2147            conn,
2148            &vec_tables,
2149            from_id,
2150            &namespace,
2151        )?;
2152
2153        let merge_event_id = Uuid::new_v4();
2154        conn.execute(
2155            "UPDATE entities \
2156             SET deleted_at = ?1, merged_into = ?2, merge_event_id = ?3, updated_at = ?1 \
2157             WHERE namespace = ?4 AND id = ?5 AND deleted_at IS NULL",
2158            rusqlite::params![
2159                now,
2160                into_str,
2161                merge_event_id.to_string(),
2162                &namespace,
2163                &from_str,
2164            ],
2165        )?;
2166    }
2167
2168    let updated_entity = Entity {
2169        id: into_id,
2170        namespace,
2171        kind: into_entity.kind,
2172        entity_type: into_entity.entity_type,
2173        name: merged_name,
2174        description: merged_description,
2175        properties: merged_props,
2176        tags: merged_tags,
2177        created_at: into_entity.created_at,
2178        updated_at: now,
2179        deleted_at: into_entity.deleted_at,
2180        merged_into: None,
2181        merge_event_id: None,
2182        content_ref: into_entity.content_ref,
2183    };
2184
2185    Ok((
2186        MergeSummary {
2187            kept_id: into_id,
2188            removed_id: from_id,
2189            edges_rewired,
2190            edges_contract_skipped,
2191            edge_conflict_preimages,
2192            properties_merged,
2193            tags_unioned,
2194            content_appended,
2195            dry_run,
2196            embedding_truncation: Default::default(),
2197        },
2198        updated_entity,
2199    ))
2200}
2201
2202// ---------------------------------------------------------------------------
2203// Note merge SQL helpers
2204// ---------------------------------------------------------------------------
2205
2206/// Read one note row by ID within a namespace, returning `SqliteError` on missing/wrong-ns.
2207fn read_merge_note(
2208    conn: &rusqlite::Connection,
2209    id: Uuid,
2210    namespace: &str,
2211) -> Result<khive_storage::note::Note, SqliteError> {
2212    use khive_storage::note::Note;
2213    let id_str = id.to_string();
2214    let mut stmt = conn.prepare(
2215        "SELECT id, namespace, kind, status, name, content, salience, decay_factor, \
2216         expires_at, properties, created_at, updated_at, deleted_at \
2217         FROM notes WHERE id = ?1 AND deleted_at IS NULL",
2218    )?;
2219    let mut rows = stmt.query(rusqlite::params![id_str])?;
2220    let row = rows
2221        .next()?
2222        .ok_or_else(|| SqliteError::InvalidData(format!("note {id} not found")))?;
2223
2224    let id_s: String = row.get(0)?;
2225    let ns: String = row.get(1)?;
2226    let kind: String = row.get(2)?;
2227    let status: String = row.get(3)?;
2228    let name: Option<String> = row.get(4)?;
2229    let content: String = row.get(5)?;
2230    let salience: Option<f64> = row.get(6)?;
2231    let decay_factor: Option<f64> = row.get(7)?;
2232    let expires_at: Option<i64> = row.get(8)?;
2233    let properties_str: Option<String> = row.get(9)?;
2234    let created_at: i64 = row.get(10)?;
2235    let updated_at: i64 = row.get(11)?;
2236    let deleted_at: Option<i64> = row.get(12)?;
2237
2238    if ns != namespace {
2239        return Err(SqliteError::InvalidData(format!(
2240            "note {id} belongs to namespace '{ns}', not '{namespace}'"
2241        )));
2242    }
2243
2244    let note_id = Uuid::parse_str(&id_s).map_err(|e| SqliteError::InvalidData(e.to_string()))?;
2245    let properties: Option<serde_json::Value> = properties_str
2246        .map(|s| serde_json::from_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string())))
2247        .transpose()?;
2248
2249    Ok(Note {
2250        id: note_id,
2251        namespace: ns,
2252        kind,
2253        status,
2254        name,
2255        content,
2256        salience,
2257        decay_factor,
2258        expires_at,
2259        properties,
2260        created_at,
2261        updated_at,
2262        deleted_at,
2263    })
2264}
2265
2266fn max_option_f64(a: Option<f64>, b: Option<f64>) -> Option<f64> {
2267    match (a, b) {
2268        (Some(x), Some(y)) => Some(x.max(y)),
2269        (Some(x), None) => Some(x),
2270        (None, Some(y)) => Some(y),
2271        (None, None) => None,
2272    }
2273}
2274
2275fn append_merge_history(props: Option<Value>, entry: Value) -> Result<Option<Value>, SqliteError> {
2276    use serde_json::{json, Map};
2277    let mut obj: Map<String, Value> = match props {
2278        Some(Value::Object(m)) => m,
2279        Some(other) => {
2280            let mut m = Map::new();
2281            m.insert("_value".into(), other);
2282            m
2283        }
2284        None => Map::new(),
2285    };
2286    let history = obj
2287        .entry("_merge_history".to_string())
2288        .or_insert_with(|| json!([]));
2289    if let Value::Array(arr) = history {
2290        arr.push(entry);
2291    }
2292    Ok(Some(Value::Object(obj)))
2293}
2294
2295/// All note merge SQL on one connection inside a `BEGIN IMMEDIATE` transaction.
2296///
2297/// Reads both notes (must have same `kind`), rewires/drops incident edges, merges content
2298/// per `content_strategy`, tombstones `from`. Returns the updated `into` note for async
2299/// re-embedding.
2300///
2301/// When `dry_run` is true, all reads and computations are performed but no writes are issued.
2302// REASON: note merge additionally requires a content_strategy parameter versus entity merge;
2303// same sync/async boundary rationale as merge_entity_sql applies here.
2304#[allow(clippy::too_many_arguments)]
2305fn merge_note_sql(
2306    conn: &rusqlite::Connection,
2307    namespace: String,
2308    fts_table: String,
2309    vec_tables: Vec<String>,
2310    into_id: Uuid,
2311    from_id: Uuid,
2312    strategy: EntityDedupMergePolicy,
2313    content_strategy: ContentMergeStrategy,
2314    dry_run: bool,
2315    pack_rules: Vec<EdgeEndpointRule>,
2316) -> Result<(MergeSummary, khive_storage::note::Note), SqliteError> {
2317    let into_note = read_merge_note(conn, into_id, &namespace)?;
2318    let from_note = read_merge_note(conn, from_id, &namespace)?;
2319
2320    if into_note.kind != from_note.kind {
2321        return Err(SqliteError::InvalidData(format!(
2322            "cannot merge notes of different kinds: {} vs {}",
2323            into_note.kind, from_note.kind
2324        )));
2325    }
2326
2327    let now = chrono::Utc::now().timestamp_micros();
2328    let into_str = into_id.to_string();
2329    let from_str = from_id.to_string();
2330
2331    // Collect edges incident to from_id.
2332    let parse_id =
2333        |s: String| Uuid::parse_str(&s).map_err(|e| SqliteError::InvalidData(e.to_string()));
2334
2335    // Namespace-agnostic (khive#1236): see the equivalent comment in
2336    // `merge_entity_sql` — edge endpoints resolve by-ID regardless of namespace.
2337    let mut outbound: Vec<EdgeRow> = Vec::new();
2338    {
2339        let mut stmt = conn.prepare(
2340            "SELECT id, namespace, source_id, target_id, relation, weight, created_at, updated_at, deleted_at, target_backend, metadata \
2341             FROM graph_edges WHERE source_id = ?1",
2342        )?;
2343        let mut rows = stmt.query(rusqlite::params![&from_str])?;
2344        while let Some(row) = rows.next()? {
2345            outbound.push(EdgeRow {
2346                id: parse_id(row.get(0)?)?,
2347                namespace: row.get(1)?,
2348                source_id: parse_id(row.get(2)?)?,
2349                target_id: parse_id(row.get(3)?)?,
2350                relation: row.get(4)?,
2351                weight: row.get(5)?,
2352                created_at: row.get(6)?,
2353                updated_at: row.get(7)?,
2354                deleted_at: row.get(8)?,
2355                target_backend: row.get(9)?,
2356                metadata: row.get(10)?,
2357            });
2358        }
2359    }
2360    let mut inbound: Vec<EdgeRow> = Vec::new();
2361    {
2362        let mut stmt = conn.prepare(
2363            "SELECT id, namespace, source_id, target_id, relation, weight, created_at, updated_at, deleted_at, target_backend, metadata \
2364             FROM graph_edges WHERE target_id = ?1",
2365        )?;
2366        let mut rows = stmt.query(rusqlite::params![&from_str])?;
2367        while let Some(row) = rows.next()? {
2368            inbound.push(EdgeRow {
2369                id: parse_id(row.get(0)?)?,
2370                namespace: row.get(1)?,
2371                source_id: parse_id(row.get(2)?)?,
2372                target_id: parse_id(row.get(3)?)?,
2373                relation: row.get(4)?,
2374                weight: row.get(5)?,
2375                created_at: row.get(6)?,
2376                updated_at: row.get(7)?,
2377                deleted_at: row.get(8)?,
2378                target_backend: row.get(9)?,
2379                metadata: row.get(10)?,
2380            });
2381        }
2382    }
2383    let mut seen: HashSet<Uuid> = HashSet::new();
2384    let mut all_edges: Vec<EdgeRow> = Vec::new();
2385    for edge in outbound.into_iter().chain(inbound) {
2386        if seen.insert(edge.id) {
2387            all_edges.push(edge);
2388        }
2389    }
2390    let original_edges: HashMap<Uuid, EdgeRow> = all_edges
2391        .iter()
2392        .map(|edge| (edge.id, edge.clone()))
2393        .collect();
2394
2395    // Merge note fields.
2396    let (merged_content, content_appended) = match content_strategy {
2397        ContentMergeStrategy::Append => {
2398            if from_note.content.is_empty() {
2399                (into_note.content.clone(), false)
2400            } else {
2401                (
2402                    format!("{}\n\n---\n\n{}", into_note.content, from_note.content),
2403                    true,
2404                )
2405            }
2406        }
2407        ContentMergeStrategy::PreferInto => (into_note.content.clone(), false),
2408        ContentMergeStrategy::PreferFrom => (from_note.content.clone(), false),
2409    };
2410
2411    let merged_name = match strategy {
2412        EntityDedupMergePolicy::PreferFrom => from_note.name.clone().or(into_note.name.clone()),
2413        _ => into_note.name.clone().or(from_note.name.clone()),
2414    };
2415
2416    let (merged_props, properties_merged) =
2417        merge_properties(&into_note.properties, &from_note.properties, strategy);
2418
2419    let merge_history_entry = serde_json::json!({
2420        "merged_from": from_id.to_string(),
2421        "merged_at": now,
2422        "strategy": format!("{:?}", strategy),
2423        "content_strategy": format!("{:?}", content_strategy),
2424    });
2425    let merged_props = append_merge_history(merged_props, merge_history_entry)?;
2426
2427    let merged_salience = max_option_f64(into_note.salience, from_note.salience);
2428    let merged_expires_at = match (into_note.expires_at, from_note.expires_at) {
2429        (Some(a), Some(b)) => Some(a.max(b)),
2430        (Some(a), None) => Some(a),
2431        (None, Some(b)) => Some(b),
2432        (None, None) => None,
2433    };
2434
2435    let props_str = merged_props
2436        .as_ref()
2437        .map(|v| serde_json::to_string(v).unwrap_or_default());
2438
2439    // The loop always runs so a dry-run reports a predictive `edges_rewired`
2440    // count instead of zero (mirrors the entity merge path).
2441    let mut rewired_edge_ids = HashSet::new();
2442    let mut edges_contract_skipped = 0usize;
2443    let mut edge_conflict_preimages = Vec::new();
2444    let mut conflict_deleted_edge_ids = HashSet::new();
2445    {
2446        for edge in all_edges {
2447            if conflict_deleted_edge_ids.contains(&edge.id) {
2448                continue;
2449            }
2450            let raw_src = if edge.source_id == from_id {
2451                into_id
2452            } else {
2453                edge.source_id
2454            };
2455            let raw_tgt = if edge.target_id == from_id {
2456                into_id
2457            } else {
2458                edge.target_id
2459            };
2460            let relation_typed = edge.relation.parse::<EdgeRelation>().ok();
2461            // Canonicalize symmetric relations before conflict check + UPDATE.
2462            let (new_src, new_tgt) = match relation_typed {
2463                Some(rel) => canonical_edge_endpoints(rel, raw_src, raw_tgt),
2464                None => (raw_src, raw_tgt),
2465            };
2466            if new_src == new_tgt {
2467                if !dry_run {
2468                    conn.execute(
2469                        "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
2470                        rusqlite::params![&edge.namespace, edge.id.to_string()],
2471                    )?;
2472                }
2473                continue;
2474            }
2475
2476            // Endpoint-contract check (khive#1216/#1236): see the equivalent
2477            // block in `merge_entity_sql` for the full rationale. Here the
2478            // rewiring endpoint is a note (`into_id`'s kind, substrate "note"),
2479            // not an entity.
2480            let contract_ok = match relation_typed {
2481                // Same rationale as the entity-merge path: annotates targets may
2482                // be events or edges, unresolvable by substrate lookup — the
2483                // exemption must precede endpoint resolution.
2484                Some(EdgeRelation::Annotates) => true,
2485                Some(rel) => {
2486                    let src_info = if new_src == into_id {
2487                        Some(("note", into_note.kind.clone(), None))
2488                    } else {
2489                        resolve_merge_edge_endpoint(conn, new_src)?
2490                    };
2491                    let tgt_info = if new_tgt == into_id {
2492                        Some(("note", into_note.kind.clone(), None))
2493                    } else {
2494                        resolve_merge_edge_endpoint(conn, new_tgt)?
2495                    };
2496                    match (src_info, tgt_info) {
2497                        (
2498                            Some((src_sub, src_kind, src_type)),
2499                            Some((tgt_sub, tgt_kind, tgt_type)),
2500                        ) => merge_rewire_endpoint_contract_allows(
2501                            &pack_rules,
2502                            rel,
2503                            src_sub,
2504                            &src_kind,
2505                            src_type.as_deref(),
2506                            tgt_sub,
2507                            &tgt_kind,
2508                            tgt_type.as_deref(),
2509                        ),
2510                        _ => false,
2511                    }
2512                }
2513                None => true,
2514            };
2515            if !contract_ok {
2516                if !dry_run {
2517                    conn.execute(
2518                        "DELETE FROM graph_edges WHERE namespace = ?1 AND id = ?2",
2519                        rusqlite::params![&edge.namespace, edge.id.to_string()],
2520                    )?;
2521                }
2522                tracing::warn!(
2523                    edge_id = %edge.id,
2524                    source = %new_src,
2525                    target = %new_tgt,
2526                    relation = %edge.relation,
2527                    "merge_note: dropping rewired edge — endpoint contract violation post-merge"
2528                );
2529                edges_contract_skipped += 1;
2530                continue;
2531            }
2532
2533            let now_ts = chrono::Utc::now().timestamp_micros();
2534            let conflict_id: Option<String> = {
2535                let conflict_src = new_src.to_string();
2536                let conflict_tgt = new_tgt.to_string();
2537                conn.query_row(
2538                    khive_db::stores::graph::EDGE_SYMMETRIC_CONFLICT_PROBE_SQL,
2539                    rusqlite::params![
2540                        &edge.namespace,
2541                        &conflict_src,
2542                        &conflict_tgt,
2543                        &edge.relation,
2544                        edge.id.to_string(),
2545                    ],
2546                    |row| row.get(0),
2547                )
2548                .optional()
2549                .map_err(SqliteError::Rusqlite)?
2550            };
2551
2552            if let Some(conflict_id) = conflict_id {
2553                // A live or soft-deleted row already owns this natural key: drop
2554                // the incoming duplicate (ADR-039 `ON CONFLICT ... DO NOTHING`).
2555                // The surviving row's weight/metadata/deleted_at are never
2556                // mutated or resurrected. Match hard `delete_edge`: cascade
2557                // incident annotations, and preserve every removed row first.
2558                let surviving_edge_id = Uuid::parse_str(&conflict_id)
2559                    .map_err(|error| SqliteError::InvalidData(error.to_string()))?;
2560                let incident_edge_preimages =
2561                    collect_conflict_incident_edge_preimages(conn, edge.id, &original_edges)?;
2562                for incident in &incident_edge_preimages {
2563                    conflict_deleted_edge_ids.insert(incident.id);
2564                    rewired_edge_ids.remove(&incident.id);
2565                }
2566                conflict_deleted_edge_ids.insert(edge.id);
2567                rewired_edge_ids.insert(edge.id);
2568
2569                if !dry_run {
2570                    delete_conflict_incident_edges(conn, &incident_edge_preimages)?;
2571                    conn.execute(
2572                        khive_db::stores::graph::EDGE_SYMMETRIC_DELETE_NONCANONICAL_SQL,
2573                        rusqlite::params![&edge.namespace, edge.id.to_string()],
2574                    )?;
2575                }
2576                edge_conflict_preimages.push(MergeEdgeConflictPreimage {
2577                    surviving_edge_id,
2578                    dropped_edge: edge_row_preimage(&edge)?,
2579                    incident_edge_preimages,
2580                });
2581            } else {
2582                if dry_run {
2583                    rewired_edge_ids.insert(edge.id);
2584                    continue;
2585                }
2586                let changed = conn.execute(
2587                    "UPDATE graph_edges SET \
2588                     source_id = ?1, target_id = ?2, updated_at = ?3 \
2589                     WHERE namespace = ?4 AND id = ?5",
2590                    rusqlite::params![
2591                        new_src.to_string(),
2592                        new_tgt.to_string(),
2593                        now_ts,
2594                        &edge.namespace,
2595                        edge.id.to_string(),
2596                    ],
2597                )?;
2598                if changed > 0 {
2599                    rewired_edge_ids.insert(edge.id);
2600                }
2601            }
2602        }
2603    }
2604    let edges_rewired = rewired_edge_ids.len();
2605
2606    if !dry_run {
2607        conn.prepare_cached(khive_db::stores::note::NOTE_UPSERT_SQL)?
2608            .execute(rusqlite::params![
2609                &into_str,
2610                &namespace,
2611                &into_note.kind,
2612                &into_note.status,
2613                &merged_name,
2614                &merged_content,
2615                merged_salience,
2616                into_note.decay_factor,
2617                merged_expires_at,
2618                &props_str,
2619                into_note.created_at,
2620                now,
2621                into_note.deleted_at,
2622            ])?;
2623
2624        conn.execute(
2625            &format!(
2626                "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2627                fts_table
2628            ),
2629            rusqlite::params![&namespace, &into_str],
2630        )?;
2631        // Derive FTS scalars through the shared constructor so this raw SQL path
2632        // is field-identical to TextSearch::upsert_document: critically, `title`
2633        // is an empty string (not SQL NULL) for nameless notes, so get_document
2634        // round-trips None <-> "" correctly.
2635        let fts_merged = {
2636            let mut merged_note = Note::new(&namespace, &*into_note.kind, &*merged_content);
2637            merged_note.id = into_id;
2638            merged_note.name = merged_name.clone();
2639            merged_note.properties = merged_props.clone();
2640            merged_note.updated_at = now;
2641            note_fts_scalars(&merged_note)
2642        };
2643        conn.execute(
2644            &format!(
2645                "INSERT INTO {} \
2646                 (subject_id, kind, title, body, tags, namespace, metadata, updated_at) \
2647                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
2648                fts_table
2649            ),
2650            rusqlite::params![
2651                &into_str,
2652                SubstrateKind::Note.to_string(),
2653                &fts_merged.title,
2654                &fts_merged.body,
2655                &fts_merged.tags,
2656                &namespace,
2657                &fts_merged.metadata,
2658                fts_merged.updated_at_micros,
2659            ],
2660        )?;
2661
2662        conn.execute(
2663            &format!(
2664                "DELETE FROM {} WHERE namespace = ?1 AND subject_id = ?2",
2665                fts_table
2666            ),
2667            rusqlite::params![&namespace, &from_str],
2668        )?;
2669
2670        khive_db::stores::vectors::delete_subject_from_vector_tables(
2671            conn,
2672            &vec_tables,
2673            from_id,
2674            &namespace,
2675        )?;
2676
2677        conn.execute(
2678            "UPDATE notes SET status = 'deleted', deleted_at = ?1, updated_at = ?1 \
2679             WHERE namespace = ?2 AND id = ?3 AND deleted_at IS NULL",
2680            rusqlite::params![now, &namespace, &from_str],
2681        )?;
2682    }
2683
2684    let updated_note = khive_storage::note::Note {
2685        id: into_id,
2686        namespace: namespace.clone(),
2687        kind: into_note.kind.clone(),
2688        status: into_note.status.clone(),
2689        name: merged_name,
2690        content: merged_content,
2691        salience: merged_salience,
2692        decay_factor: into_note.decay_factor,
2693        expires_at: merged_expires_at,
2694        properties: merged_props,
2695        created_at: into_note.created_at,
2696        updated_at: now,
2697        deleted_at: into_note.deleted_at,
2698    };
2699
2700    Ok((
2701        MergeSummary {
2702            kept_id: into_id,
2703            removed_id: from_id,
2704            edges_rewired,
2705            edges_contract_skipped,
2706            edge_conflict_preimages,
2707            properties_merged,
2708            tags_unioned: 0,
2709            content_appended,
2710            dry_run,
2711            embedding_truncation: Default::default(),
2712        },
2713        updated_note,
2714    ))
2715}
2716
2717// ---------------------------------------------------------------------------
2718// Merge helpers (pure functions — easier to unit test)
2719// ---------------------------------------------------------------------------
2720
2721/// `pub(crate)` so `crate::atomic_prepare::prepare_merge` can reuse this exact
2722/// field-fold semantics for atomic/non-atomic parity.
2723pub(crate) fn merge_string_field(
2724    into: &str,
2725    from: &str,
2726    strategy: EntityDedupMergePolicy,
2727) -> String {
2728    match strategy {
2729        EntityDedupMergePolicy::PreferInto | EntityDedupMergePolicy::Union => into.to_string(),
2730        EntityDedupMergePolicy::PreferFrom => from.to_string(),
2731    }
2732}
2733
2734/// Merge two property objects. Returns (merged, count_of_fields_from_from_that_were_added).
2735/// `pub(crate)` so `crate::atomic_prepare` can reuse this exact properties-merge
2736/// semantics when building an `update` write plan's row statement, matching
2737/// `update_entity`/`update_note`'s own patch behavior byte-for-byte.
2738pub(crate) fn merge_properties(
2739    into: &Option<Value>,
2740    from: &Option<Value>,
2741    strategy: EntityDedupMergePolicy,
2742) -> (Option<Value>, usize) {
2743    match (into, from) {
2744        (None, None) => (None, 0),
2745        (Some(a), None) => (Some(a.clone()), 0),
2746        (None, Some(b)) => {
2747            let count = if let Value::Object(m) = b { m.len() } else { 1 };
2748            (Some(b.clone()), count)
2749        }
2750        (Some(into_val), Some(from_val)) => {
2751            let (merged, added) = merge_json(into_val, from_val, strategy);
2752            (Some(merged), added)
2753        }
2754    }
2755}
2756
2757/// Deep-merge two JSON values per strategy. Returns (merged, keys_contributed_by_from).
2758fn merge_json(into: &Value, from: &Value, strategy: EntityDedupMergePolicy) -> (Value, usize) {
2759    match (into, from, strategy) {
2760        (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::Union) => {
2761            let mut result = a.clone();
2762            let mut added = 0usize;
2763            for (k, v_from) in b {
2764                if let Some(v_into) = a.get(k) {
2765                    let (merged, sub_added) =
2766                        merge_json(v_into, v_from, EntityDedupMergePolicy::Union);
2767                    result.insert(k.clone(), merged);
2768                    added += sub_added;
2769                } else {
2770                    result.insert(k.clone(), v_from.clone());
2771                    added += 1;
2772                }
2773            }
2774            (Value::Object(result), added)
2775        }
2776        (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::PreferInto) => {
2777            let mut result = a.clone();
2778            let mut added = 0usize;
2779            for (k, v) in b {
2780                if !a.contains_key(k) {
2781                    result.insert(k.clone(), v.clone());
2782                    added += 1;
2783                }
2784            }
2785            (Value::Object(result), added)
2786        }
2787        (Value::Object(a), Value::Object(b), EntityDedupMergePolicy::PreferFrom) => {
2788            let mut result = a.clone();
2789            let mut added = 0usize;
2790            for (k, v) in b {
2791                result.insert(k.clone(), v.clone());
2792                if !a.contains_key(k) {
2793                    added += 1;
2794                }
2795            }
2796            (Value::Object(result), added)
2797        }
2798        // Non-object scalars: apply strategy directly.
2799        (_into_val, from_val, EntityDedupMergePolicy::PreferFrom) => (from_val.clone(), 1),
2800        _ => (into.clone(), 0),
2801    }
2802}
2803
2804/// `pub(crate)` so `crate::atomic_prepare::prepare_merge` can reuse this for
2805/// atomic/non-atomic parity.
2806pub(crate) fn union_tags(into: &[String], from: &[String]) -> (Vec<String>, usize) {
2807    let mut seen: HashSet<&str> = into.iter().map(|s| s.as_str()).collect();
2808    let mut result: Vec<String> = into.to_vec();
2809    let mut added = 0usize;
2810    for tag in from {
2811        if seen.insert(tag.as_str()) {
2812            result.push(tag.clone());
2813            added += 1;
2814        }
2815    }
2816    (result, added)
2817}
2818
2819// ---------------------------------------------------------------------------
2820// INLINE TEST JUSTIFICATION: tests here exercise patch/merge helpers and the
2821// update_note/update_entity paths that share private merge_properties logic.
2822// Moving them to tests/ would require pub-exporting merge_properties, which is
2823// an internal invariant not suitable for the public API surface. Broad
2824// behavioral curation tests live in tests/integration.rs.
2825// ---------------------------------------------------------------------------
2826
2827#[cfg(test)]
2828mod tests {
2829    use super::*;
2830    use crate::runtime::{KhiveRuntime, NamespaceToken};
2831    use khive_storage::types::{Direction, TextFilter, TextQueryMode, TextSearchRequest};
2832    use khive_types::EndpointKind;
2833
2834    fn rt() -> KhiveRuntime {
2835        KhiveRuntime::memory().unwrap()
2836    }
2837
2838    fn secret_shaped_reason() -> String {
2839        const ALPHANUMERIC: &[u8] =
2840            b"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
2841        let candidate: String = (0..48)
2842            .map(|index| char::from(ALPHANUMERIC[(index * 17 + 11) % ALPHANUMERIC.len()]))
2843            .collect();
2844        format!("secret value: {candidate}")
2845    }
2846
2847    async fn restore_edge_preimage(
2848        rt: &KhiveRuntime,
2849        token: &NamespaceToken,
2850        preimage: &MergeEdgePreimage,
2851    ) {
2852        let edge = khive_storage::types::Edge {
2853            id: preimage.id.into(),
2854            namespace: preimage.namespace.clone(),
2855            source_id: preimage.source_id,
2856            target_id: preimage.target_id,
2857            relation: preimage.relation.parse().expect("stored relation"),
2858            weight: preimage.weight,
2859            created_at: chrono::DateTime::from_timestamp_micros(preimage.created_at)
2860                .expect("stored created_at"),
2861            updated_at: chrono::DateTime::from_timestamp_micros(preimage.updated_at)
2862                .expect("stored updated_at"),
2863            deleted_at: preimage.deleted_at.map(|value| {
2864                chrono::DateTime::from_timestamp_micros(value).expect("stored deleted_at")
2865            }),
2866            metadata: preimage.metadata.clone(),
2867            target_backend: preimage.target_backend.clone(),
2868        };
2869        rt.graph(token)
2870            .expect("graph store")
2871            .upsert_edge(edge)
2872            .await
2873            .expect("restore edge preimage");
2874    }
2875
2876    fn assert_edge_matches_preimage(
2877        edge: &khive_storage::types::Edge,
2878        preimage: &MergeEdgePreimage,
2879    ) {
2880        assert_eq!(Uuid::from(edge.id), preimage.id);
2881        assert_eq!(edge.namespace, preimage.namespace);
2882        assert_eq!(edge.source_id, preimage.source_id);
2883        assert_eq!(edge.target_id, preimage.target_id);
2884        assert_eq!(edge.relation.to_string(), preimage.relation);
2885        assert_eq!(edge.weight, preimage.weight);
2886        assert_eq!(edge.created_at.timestamp_micros(), preimage.created_at);
2887        assert_eq!(edge.updated_at.timestamp_micros(), preimage.updated_at);
2888        assert_eq!(
2889            edge.deleted_at.map(|value| value.timestamp_micros()),
2890            preimage.deleted_at
2891        );
2892        assert_eq!(edge.metadata, preimage.metadata);
2893        assert_eq!(edge.target_backend, preimage.target_backend);
2894    }
2895
2896    // Helper: search FTS5 for `query` in a runtime namespace.
2897    async fn fts_hit(rt: &KhiveRuntime, token: &NamespaceToken, query: &str) -> Vec<Uuid> {
2898        let ns = token.namespace().as_str().to_string();
2899        rt.text(token)
2900            .unwrap()
2901            .search(TextSearchRequest {
2902                query: query.to_string(),
2903                mode: TextQueryMode::Plain,
2904                filter: Some(TextFilter {
2905                    namespaces: vec![ns],
2906                    ..Default::default()
2907                }),
2908                top_k: 50,
2909                snippet_chars: 100,
2910            })
2911            .await
2912            .unwrap()
2913            .into_iter()
2914            .map(|h| h.subject_id)
2915            .collect()
2916    }
2917
2918    #[tokio::test]
2919    async fn update_entity_patch_changes_only_specified_fields() {
2920        let rt = rt();
2921        let tok = NamespaceToken::local();
2922        let entity = rt
2923            .create_entity(
2924                &tok,
2925                "concept",
2926                None,
2927                "OriginalName",
2928                Some("orig desc"),
2929                Some(serde_json::json!({"k":"v"})),
2930                vec![],
2931            )
2932            .await
2933            .unwrap();
2934
2935        let updated = rt
2936            .update_entity(
2937                &tok,
2938                entity.id,
2939                EntityPatch {
2940                    description: Some(Some("new desc".to_string())),
2941                    ..Default::default()
2942                },
2943            )
2944            .await
2945            .unwrap();
2946
2947        assert_eq!(updated.name, "OriginalName");
2948        assert_eq!(updated.description.as_deref(), Some("new desc"));
2949        assert_eq!(updated.properties, Some(serde_json::json!({"k":"v"})));
2950    }
2951
2952    #[tokio::test]
2953    async fn update_entity_clear_description_with_some_none() {
2954        let rt = rt();
2955        let tok = NamespaceToken::local();
2956        let entity = rt
2957            .create_entity(
2958                &tok,
2959                "concept",
2960                None,
2961                "ClearDesc",
2962                Some("has description"),
2963                None,
2964                vec![],
2965            )
2966            .await
2967            .unwrap();
2968
2969        let updated = rt
2970            .update_entity(
2971                &tok,
2972                entity.id,
2973                EntityPatch {
2974                    description: Some(None),
2975                    ..Default::default()
2976                },
2977            )
2978            .await
2979            .unwrap();
2980
2981        assert!(
2982            updated.description.is_none(),
2983            "description should be cleared"
2984        );
2985    }
2986
2987    #[tokio::test]
2988    async fn update_entity_reindexes_when_name_changes() {
2989        let rt = rt();
2990        let tok = NamespaceToken::local();
2991        let entity = rt
2992            .create_entity(&tok, "concept", None, "OldName", None, None, vec![])
2993            .await
2994            .unwrap();
2995
2996        let hits_before = fts_hit(&rt, &tok, "OldName").await;
2997        assert!(
2998            hits_before.contains(&entity.id),
2999            "entity should be findable by old name"
3000        );
3001
3002        rt.update_entity(
3003            &tok,
3004            entity.id,
3005            EntityPatch {
3006                name: Some("NewName".to_string()),
3007                ..Default::default()
3008            },
3009        )
3010        .await
3011        .unwrap();
3012
3013        let hits_old = fts_hit(&rt, &tok, "OldName").await;
3014        let hits_new = fts_hit(&rt, &tok, "NewName").await;
3015
3016        assert!(
3017            !hits_old.contains(&entity.id),
3018            "old name should no longer match after rename"
3019        );
3020        assert!(
3021            hits_new.contains(&entity.id),
3022            "new name should be findable after rename"
3023        );
3024    }
3025
3026    #[tokio::test]
3027    async fn update_entity_properties_merges_preserving_existing_keys() {
3028        let rt = rt();
3029        let tok = NamespaceToken::local();
3030        let entity = rt
3031            .create_entity(
3032                &tok,
3033                "concept",
3034                None,
3035                "MergeProps",
3036                None,
3037                Some(serde_json::json!({
3038                    "domain": "inference",
3039                    "repo": "lattice",
3040                    "status": "researched",
3041                })),
3042                vec![],
3043            )
3044            .await
3045            .unwrap();
3046
3047        let updated = rt
3048            .update_entity(
3049                &tok,
3050                entity.id,
3051                EntityPatch {
3052                    properties: Some(serde_json::json!({"status": "implemented"})),
3053                    ..Default::default()
3054                },
3055            )
3056            .await
3057            .unwrap();
3058
3059        let props = updated.properties.expect("properties should remain set");
3060        assert_eq!(props["domain"], "inference", "domain key must be preserved");
3061        assert_eq!(props["repo"], "lattice", "repo key must be preserved");
3062        assert_eq!(
3063            props["status"], "implemented",
3064            "status key must be updated by patch"
3065        );
3066    }
3067
3068    #[tokio::test]
3069    async fn update_entity_skips_reindex_when_only_properties_change() {
3070        let rt = rt();
3071        let tok = NamespaceToken::local();
3072        let entity = rt
3073            .create_entity(&tok, "concept", None, "StableIndexed", None, None, vec![])
3074            .await
3075            .unwrap();
3076
3077        let hits_before = fts_hit(&rt, &tok, "StableIndexed").await;
3078        assert!(hits_before.contains(&entity.id));
3079
3080        rt.update_entity(
3081            &tok,
3082            entity.id,
3083            EntityPatch {
3084                properties: Some(serde_json::json!({"new": "prop"})),
3085                ..Default::default()
3086            },
3087        )
3088        .await
3089        .unwrap();
3090
3091        let hits_after = fts_hit(&rt, &tok, "StableIndexed").await;
3092        assert!(
3093            hits_after.contains(&entity.id),
3094            "still findable after props-only patch"
3095        );
3096    }
3097
3098    #[tokio::test]
3099    async fn merge_entity_rewires_edges() {
3100        let rt = rt();
3101        let tok = NamespaceToken::local();
3102        let a = rt
3103            .create_entity(&tok, "concept", None, "A", None, None, vec![])
3104            .await
3105            .unwrap();
3106        let b = rt
3107            .create_entity(&tok, "concept", None, "B", None, None, vec![])
3108            .await
3109            .unwrap();
3110        let c = rt
3111            .create_entity(&tok, "concept", None, "C", None, None, vec![])
3112            .await
3113            .unwrap();
3114        let d = rt
3115            .create_entity(&tok, "concept", None, "D", None, None, vec![])
3116            .await
3117            .unwrap();
3118
3119        // A→B and C→B; merge B into D → should become A→D and C→D.
3120        rt.link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
3121            .await
3122            .unwrap();
3123        rt.link(&tok, c.id, b.id, EdgeRelation::Extends, 1.0, None)
3124            .await
3125            .unwrap();
3126
3127        let summary = rt
3128            .merge_entity_with_reason(
3129                &tok,
3130                d.id,
3131                b.id,
3132                EntityDedupMergePolicy::PreferInto,
3133                ContentMergeStrategy::Append,
3134                false,
3135                None,
3136            )
3137            .await
3138            .unwrap();
3139
3140        assert_eq!(summary.kept_id, d.id);
3141        assert_eq!(summary.removed_id, b.id);
3142        assert_eq!(summary.edges_rewired, 2);
3143
3144        let a_neighbors = rt
3145            .neighbors(&tok, a.id, Direction::Out, None, None)
3146            .await
3147            .unwrap();
3148        assert_eq!(a_neighbors.len(), 1);
3149        assert_eq!(a_neighbors[0].node_id, d.id);
3150
3151        let c_neighbors = rt
3152            .neighbors(&tok, c.id, Direction::Out, None, None)
3153            .await
3154            .unwrap();
3155        assert_eq!(c_neighbors.len(), 1);
3156        assert_eq!(c_neighbors[0].node_id, d.id);
3157    }
3158
3159    // khive#1236: edges incident to `from_id` but stamped with a namespace other
3160    // than the merge caller's must still be discovered and rewired — by-ID edge
3161    // endpoints are namespace-agnostic (ADR-007 Rev 6), and `link` stamps an edge
3162    // with its *creator's* namespace, not either endpoint's.
3163    #[tokio::test]
3164    async fn merge_entity_rewires_edges_from_other_namespaces() {
3165        use crate::Namespace;
3166
3167        let rt = rt();
3168        let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
3169        let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
3170
3171        let into_a = rt
3172            .create_entity(&ns_a, "concept", None, "Into A", None, None, vec![])
3173            .await
3174            .unwrap();
3175        let from_a = rt
3176            .create_entity(&ns_a, "concept", None, "From A", None, None, vec![])
3177            .await
3178            .unwrap();
3179        let foreign_b = rt
3180            .create_entity(&ns_b, "concept", None, "Foreign B", None, None, vec![])
3181            .await
3182            .unwrap();
3183
3184        // Edge created by an ns_b caller, stamped with ns_b, whose target lives in
3185        // ns_a — legal because by-ID link endpoints are namespace-agnostic.
3186        rt.link(
3187            &ns_b,
3188            foreign_b.id,
3189            from_a.id,
3190            EdgeRelation::Extends,
3191            1.0,
3192            None,
3193        )
3194        .await
3195        .unwrap();
3196
3197        let summary = rt
3198            .merge_entity_with_reason(
3199                &ns_a,
3200                into_a.id,
3201                from_a.id,
3202                EntityDedupMergePolicy::PreferInto,
3203                ContentMergeStrategy::Append,
3204                false,
3205                None,
3206            )
3207            .await
3208            .unwrap();
3209
3210        assert_eq!(
3211            summary.edges_rewired, 1,
3212            "the ns_b-stamped edge incident to from_id must be discovered and rewired, not missed"
3213        );
3214
3215        let foreign_neighbors = rt
3216            .neighbors(&ns_b, foreign_b.id, Direction::Out, None, None)
3217            .await
3218            .unwrap();
3219        assert_eq!(
3220            foreign_neighbors.len(),
3221            1,
3222            "cross-namespace edge must survive the merge, rewired to point at into_id"
3223        );
3224        assert_eq!(foreign_neighbors[0].node_id, into_a.id);
3225    }
3226
3227    // khive#1216: a merge rewire must re-check the pack endpoint contract for the
3228    // POST-rewrite pair, not just carry the pre-merge edge over. into_id and
3229    // from_id share `kind` (enforced by the caller) but may differ in
3230    // `entity_type`, so a pack rule scoped via `EntityOfType` can accept
3231    // `from_id`'s edge yet reject the identical relation once rewritten onto
3232    // `into_id`.
3233    #[tokio::test]
3234    async fn merge_entity_drops_edge_violating_endpoint_contract_after_rewire() {
3235        let rt = rt();
3236        let tok = NamespaceToken::local();
3237
3238        // depends_on is NOT in the base concept->concept allowlist; only this
3239        // pack rule (theorem -> definition) accepts it.
3240        rt.install_edge_rules(vec![EdgeEndpointRule {
3241            relation: EdgeRelation::DependsOn,
3242            source: EndpointKind::EntityOfType {
3243                kind: "concept",
3244                entity_type: "theorem",
3245            },
3246            target: EndpointKind::EntityOfType {
3247                kind: "concept",
3248                entity_type: "definition",
3249            },
3250        }]);
3251
3252        let def_entity = rt
3253            .create_entity(
3254                &tok,
3255                "concept",
3256                Some("definition"),
3257                "Def",
3258                None,
3259                None,
3260                vec![],
3261            )
3262            .await
3263            .unwrap();
3264        let from_theorem = rt
3265            .create_entity(
3266                &tok,
3267                "concept",
3268                Some("theorem"),
3269                "FromTheorem",
3270                None,
3271                None,
3272                vec![],
3273            )
3274            .await
3275            .unwrap();
3276        // Same base kind ("concept") as from_theorem, but a different entity_type
3277        // — the merge's same-kind constraint allows this, the endpoint contract
3278        // (entity_type-scoped) does not.
3279        let into_lemma = rt
3280            .create_entity(
3281                &tok,
3282                "concept",
3283                Some("lemma"),
3284                "IntoLemma",
3285                None,
3286                None,
3287                vec![],
3288            )
3289            .await
3290            .unwrap();
3291
3292        rt.link(
3293            &tok,
3294            from_theorem.id,
3295            def_entity.id,
3296            EdgeRelation::DependsOn,
3297            1.0,
3298            None,
3299        )
3300        .await
3301        .unwrap();
3302
3303        let summary = rt
3304            .merge_entity_with_reason(
3305                &tok,
3306                into_lemma.id,
3307                from_theorem.id,
3308                EntityDedupMergePolicy::PreferInto,
3309                ContentMergeStrategy::Append,
3310                false,
3311                None,
3312            )
3313            .await
3314            .unwrap();
3315
3316        assert_eq!(
3317            summary.edges_rewired, 0,
3318            "the contract-violating rewire must not be counted as rewired"
3319        );
3320        assert_eq!(
3321            summary.edges_contract_skipped, 1,
3322            "the depends_on edge must be dropped, not silently rewritten past the endpoint contract"
3323        );
3324
3325        let def_neighbors = rt
3326            .neighbors(&tok, def_entity.id, Direction::In, None, None)
3327            .await
3328            .unwrap();
3329        assert!(
3330            def_neighbors.is_empty(),
3331            "no contract-violating depends_on edge should survive onto into_lemma; got {def_neighbors:?}"
3332        );
3333    }
3334
3335    // Dry-run counterpart: a contract-violating rewire must be predicted as
3336    // skipped (not rewired), and no write occurs.
3337    #[tokio::test]
3338    async fn merge_entity_dry_run_predicts_contract_skip_without_writing() {
3339        let rt = rt();
3340        let tok = NamespaceToken::local();
3341
3342        rt.install_edge_rules(vec![EdgeEndpointRule {
3343            relation: EdgeRelation::DependsOn,
3344            source: EndpointKind::EntityOfType {
3345                kind: "concept",
3346                entity_type: "theorem",
3347            },
3348            target: EndpointKind::EntityOfType {
3349                kind: "concept",
3350                entity_type: "definition",
3351            },
3352        }]);
3353
3354        let def_entity = rt
3355            .create_entity(
3356                &tok,
3357                "concept",
3358                Some("definition"),
3359                "Def",
3360                None,
3361                None,
3362                vec![],
3363            )
3364            .await
3365            .unwrap();
3366        let from_theorem = rt
3367            .create_entity(
3368                &tok,
3369                "concept",
3370                Some("theorem"),
3371                "FromTheorem",
3372                None,
3373                None,
3374                vec![],
3375            )
3376            .await
3377            .unwrap();
3378        let into_lemma = rt
3379            .create_entity(
3380                &tok,
3381                "concept",
3382                Some("lemma"),
3383                "IntoLemma",
3384                None,
3385                None,
3386                vec![],
3387            )
3388            .await
3389            .unwrap();
3390
3391        rt.link(
3392            &tok,
3393            from_theorem.id,
3394            def_entity.id,
3395            EdgeRelation::DependsOn,
3396            1.0,
3397            None,
3398        )
3399        .await
3400        .unwrap();
3401
3402        let summary = rt
3403            .merge_entity_with_reason(
3404                &tok,
3405                into_lemma.id,
3406                from_theorem.id,
3407                EntityDedupMergePolicy::PreferInto,
3408                ContentMergeStrategy::Append,
3409                true, // dry_run
3410                None,
3411            )
3412            .await
3413            .unwrap();
3414
3415        assert_eq!(summary.edges_rewired, 0);
3416        assert_eq!(summary.edges_contract_skipped, 1);
3417
3418        // Nothing written: the original edge is untouched.
3419        let def_neighbors = rt
3420            .neighbors(&tok, def_entity.id, Direction::In, None, None)
3421            .await
3422            .unwrap();
3423        assert_eq!(def_neighbors.len(), 1);
3424        assert_eq!(def_neighbors[0].node_id, from_theorem.id);
3425    }
3426
3427    // A conflicting rewire must leave the surviving edge untouched (ADR-039
3428    // DO NOTHING) — the merged-from edge's attributes never overwrite it.
3429    #[tokio::test]
3430    async fn merge_entity_conflict_keeps_survivor_edge_attributes() {
3431        let rt = rt();
3432        let tok = NamespaceToken::local();
3433        let into = rt
3434            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3435            .await
3436            .unwrap();
3437        let from = rt
3438            .create_entity(&tok, "concept", None, "From", None, None, vec![])
3439            .await
3440            .unwrap();
3441        let shared = rt
3442            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3443            .await
3444            .unwrap();
3445
3446        let survivor = rt
3447            .link(&tok, into.id, shared.id, EdgeRelation::Extends, 0.9, None)
3448            .await
3449            .unwrap();
3450        rt.link(&tok, from.id, shared.id, EdgeRelation::Extends, 0.2, None)
3451            .await
3452            .unwrap();
3453
3454        rt.merge_entity(
3455            &tok,
3456            into.id,
3457            from.id,
3458            EntityDedupMergePolicy::PreferInto,
3459            ContentMergeStrategy::Append,
3460            false,
3461        )
3462        .await
3463        .unwrap();
3464
3465        let edges = rt
3466            .list_edges(
3467                &tok,
3468                crate::EdgeListFilter {
3469                    source_id: Some(into.id),
3470                    target_id: Some(shared.id),
3471                    relations: vec![EdgeRelation::Extends],
3472                    ..Default::default()
3473                },
3474                10,
3475                0,
3476            )
3477            .await
3478            .unwrap();
3479        assert_eq!(edges.len(), 1);
3480        assert_eq!(edges[0].id, survivor.id);
3481        assert!(
3482            (edges[0].weight - 0.9).abs() < f64::EPSILON,
3483            "survivor weight must not be overwritten by the merged-from edge; got {}",
3484            edges[0].weight
3485        );
3486    }
3487
3488    #[tokio::test]
3489    async fn merge_entity_conflict_records_restorable_edge_and_annotation_preimages() {
3490        let rt = rt();
3491        let tok = NamespaceToken::local();
3492        let into = rt
3493            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3494            .await
3495            .unwrap();
3496        let from = rt
3497            .create_entity(&tok, "concept", None, "From", None, None, vec![])
3498            .await
3499            .unwrap();
3500        let shared = rt
3501            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3502            .await
3503            .unwrap();
3504        let annotator = rt
3505            .create_note(
3506                &tok,
3507                "observation",
3508                None,
3509                "edge judgment",
3510                None,
3511                None,
3512                vec![],
3513            )
3514            .await
3515            .unwrap();
3516        let nested_annotator = rt
3517            .create_note(
3518                &tok,
3519                "observation",
3520                None,
3521                "judgment review",
3522                None,
3523                None,
3524                vec![],
3525            )
3526            .await
3527            .unwrap();
3528
3529        let survivor = rt
3530            .link(
3531                &tok,
3532                into.id,
3533                shared.id,
3534                EdgeRelation::Extends,
3535                0.9,
3536                Some(serde_json::json!({"source": "survivor"})),
3537            )
3538            .await
3539            .unwrap();
3540        let dropped = rt
3541            .link(
3542                &tok,
3543                from.id,
3544                shared.id,
3545                EdgeRelation::Extends,
3546                0.2,
3547                Some(serde_json::json!({"source": "dropped"})),
3548            )
3549            .await
3550            .unwrap();
3551        let annotation = rt
3552            .link(
3553                &tok,
3554                annotator.id,
3555                dropped.id.into(),
3556                EdgeRelation::Annotates,
3557                0.7,
3558                Some(serde_json::json!({"basis": "manual"})),
3559            )
3560            .await
3561            .unwrap();
3562        let nested_annotation = rt
3563            .link(
3564                &tok,
3565                nested_annotator.id,
3566                annotation.id.into(),
3567                EdgeRelation::Annotates,
3568                0.6,
3569                Some(serde_json::json!({"review": "confirmed"})),
3570            )
3571            .await
3572            .unwrap();
3573        rt.delete_edge(&tok, annotation.id.into(), false)
3574            .await
3575            .unwrap();
3576
3577        let summary = rt
3578            .merge_entity(
3579                &tok,
3580                into.id,
3581                from.id,
3582                EntityDedupMergePolicy::PreferInto,
3583                ContentMergeStrategy::Append,
3584                false,
3585            )
3586            .await
3587            .unwrap();
3588
3589        let [conflict] = summary.edge_conflict_preimages.as_slice() else {
3590            panic!(
3591                "expected one edge-conflict preimage, got {:?}",
3592                summary.edge_conflict_preimages
3593            );
3594        };
3595        assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
3596        assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
3597        assert_eq!(conflict.dropped_edge.source_id, from.id);
3598        assert_eq!(conflict.dropped_edge.target_id, shared.id);
3599        assert_eq!(conflict.dropped_edge.relation, "extends");
3600        assert_eq!(conflict.dropped_edge.weight, 0.2);
3601        assert_eq!(
3602            conflict.dropped_edge.metadata,
3603            Some(serde_json::json!({"source": "dropped"}))
3604        );
3605        assert_eq!(conflict.incident_edge_preimages.len(), 2);
3606        assert_eq!(
3607            conflict.incident_edge_preimages[0].id,
3608            Uuid::from(annotation.id)
3609        );
3610        assert_eq!(
3611            conflict.incident_edge_preimages[1].id,
3612            Uuid::from(nested_annotation.id)
3613        );
3614
3615        for id in [dropped.id, annotation.id, nested_annotation.id] {
3616            assert!(
3617                rt.get_edge_including_deleted(&tok, id.into())
3618                    .await
3619                    .unwrap()
3620                    .is_none(),
3621                "merge conflict cascade must leave no dangling edge row for {id}"
3622            );
3623        }
3624
3625        let events = rt
3626            .events(&tok)
3627            .unwrap()
3628            .query_events(
3629                khive_storage::EventFilter {
3630                    kinds: vec![EventKind::EntityMerged],
3631                    ..Default::default()
3632                },
3633                khive_storage::types::PageRequest {
3634                    offset: 0,
3635                    limit: 10,
3636                },
3637            )
3638            .await
3639            .unwrap();
3640        assert_eq!(events.items.len(), 1);
3641        assert_eq!(
3642            events.items[0].payload["edge_conflict_preimages"],
3643            serde_json::to_value(&summary.edge_conflict_preimages).unwrap()
3644        );
3645
3646        restore_edge_preimage(&rt, &tok, &conflict.dropped_edge).await;
3647        for preimage in &conflict.incident_edge_preimages {
3648            restore_edge_preimage(&rt, &tok, preimage).await;
3649        }
3650        for preimage in
3651            std::iter::once(&conflict.dropped_edge).chain(conflict.incident_edge_preimages.iter())
3652        {
3653            let restored = rt
3654                .get_edge_including_deleted(&tok, preimage.id)
3655                .await
3656                .unwrap()
3657                .expect("restored edge");
3658            assert_edge_matches_preimage(&restored, preimage);
3659        }
3660    }
3661
3662    // A dry run must predict the same conflict preimages a committing merge
3663    // would produce, without deleting or mutating a single row. The incident
3664    // cascade is two levels deep (an annotation on the dropped edge, and a
3665    // nested annotation on that annotation) so the root-to-leaf ordering
3666    // ADR-014 promises is actually exercised, not just a one-element vec that
3667    // trivially satisfies any order. Every row touched by the merge — both
3668    // entities and every edge — is snapshotted before the dry run and
3669    // compared field-for-field against its post-run state.
3670    #[tokio::test]
3671    async fn merge_entity_dry_run_conflict_returns_preimages_without_mutating() {
3672        let rt = rt();
3673        let tok = NamespaceToken::local();
3674        let into = rt
3675            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3676            .await
3677            .unwrap();
3678        let from = rt
3679            .create_entity(&tok, "concept", None, "From", None, None, vec![])
3680            .await
3681            .unwrap();
3682        let shared = rt
3683            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3684            .await
3685            .unwrap();
3686        let annotator = rt
3687            .create_note(
3688                &tok,
3689                "observation",
3690                None,
3691                "edge judgment",
3692                None,
3693                None,
3694                vec![],
3695            )
3696            .await
3697            .unwrap();
3698        let nested_annotator = rt
3699            .create_note(
3700                &tok,
3701                "observation",
3702                None,
3703                "judgment review",
3704                None,
3705                None,
3706                vec![],
3707            )
3708            .await
3709            .unwrap();
3710
3711        let survivor = rt
3712            .link(
3713                &tok,
3714                into.id,
3715                shared.id,
3716                EdgeRelation::Extends,
3717                0.9,
3718                Some(serde_json::json!({"source": "survivor"})),
3719            )
3720            .await
3721            .unwrap();
3722        let dropped = rt
3723            .link(
3724                &tok,
3725                from.id,
3726                shared.id,
3727                EdgeRelation::Extends,
3728                0.2,
3729                Some(serde_json::json!({"source": "dropped"})),
3730            )
3731            .await
3732            .unwrap();
3733        let annotation = rt
3734            .link(
3735                &tok,
3736                annotator.id,
3737                dropped.id.into(),
3738                EdgeRelation::Annotates,
3739                0.7,
3740                Some(serde_json::json!({"basis": "manual"})),
3741            )
3742            .await
3743            .unwrap();
3744        let nested_annotation = rt
3745            .link(
3746                &tok,
3747                nested_annotator.id,
3748                annotation.id.into(),
3749                EdgeRelation::Annotates,
3750                0.6,
3751                Some(serde_json::json!({"basis": "nested"})),
3752            )
3753            .await
3754            .unwrap();
3755        rt.delete_edge(&tok, nested_annotation.id.into(), false)
3756            .await
3757            .unwrap();
3758
3759        let survivor_before = rt
3760            .get_edge_including_deleted(&tok, survivor.id.into())
3761            .await
3762            .unwrap()
3763            .expect("survivor edge exists");
3764        let dropped_before = rt
3765            .get_edge_including_deleted(&tok, dropped.id.into())
3766            .await
3767            .unwrap()
3768            .expect("dropped edge exists");
3769        let annotation_before = rt
3770            .get_edge_including_deleted(&tok, annotation.id.into())
3771            .await
3772            .unwrap()
3773            .expect("annotation edge exists");
3774        let nested_annotation_before = rt
3775            .get_edge_including_deleted(&tok, nested_annotation.id.into())
3776            .await
3777            .unwrap()
3778            .expect("nested annotation edge exists");
3779        let into_before = rt
3780            .get_entity(&tok, into.id)
3781            .await
3782            .expect("into entity exists");
3783        let from_before = rt
3784            .get_entity(&tok, from.id)
3785            .await
3786            .expect("from entity exists");
3787
3788        let summary = rt
3789            .merge_entity(
3790                &tok,
3791                into.id,
3792                from.id,
3793                EntityDedupMergePolicy::PreferInto,
3794                ContentMergeStrategy::Append,
3795                true,
3796            )
3797            .await
3798            .unwrap();
3799
3800        let [conflict] = summary.edge_conflict_preimages.as_slice() else {
3801            panic!(
3802                "expected one edge-conflict preimage from the dry run, got {:?}",
3803                summary.edge_conflict_preimages
3804            );
3805        };
3806        assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
3807        assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
3808        assert_eq!(conflict.dropped_edge.source_id, from.id);
3809        assert_eq!(conflict.dropped_edge.target_id, shared.id);
3810        assert_eq!(conflict.dropped_edge.weight, 0.2);
3811        // Root-to-leaf order (ADR-014): the direct annotation on the dropped
3812        // edge must precede the annotation nested on top of it.
3813        assert_eq!(conflict.incident_edge_preimages.len(), 2);
3814        assert_eq!(
3815            conflict.incident_edge_preimages[0].id,
3816            Uuid::from(annotation.id)
3817        );
3818        assert!(
3819            conflict.incident_edge_preimages[0].deleted_at.is_none(),
3820            "the direct annotation was never soft-deleted"
3821        );
3822        assert_eq!(
3823            conflict.incident_edge_preimages[1].id,
3824            Uuid::from(nested_annotation.id)
3825        );
3826        assert!(
3827            conflict.incident_edge_preimages[1].deleted_at.is_some(),
3828            "dry-run preimage must retain the nested annotation's tombstone state"
3829        );
3830
3831        let survivor_after = rt
3832            .get_edge_including_deleted(&tok, survivor.id.into())
3833            .await
3834            .unwrap()
3835            .expect("dry run must not delete the survivor edge");
3836        let dropped_after = rt
3837            .get_edge_including_deleted(&tok, dropped.id.into())
3838            .await
3839            .unwrap()
3840            .expect("dry run must not delete the dropped edge");
3841        let annotation_after = rt
3842            .get_edge_including_deleted(&tok, annotation.id.into())
3843            .await
3844            .unwrap()
3845            .expect("dry run must not delete the cascaded annotation");
3846        let nested_annotation_after = rt
3847            .get_edge_including_deleted(&tok, nested_annotation.id.into())
3848            .await
3849            .unwrap()
3850            .expect("dry run must not delete the nested cascaded annotation");
3851        assert_eq!(
3852            serde_json::to_value(&survivor_before).unwrap(),
3853            serde_json::to_value(&survivor_after).unwrap(),
3854            "dry run must not mutate the surviving edge's row at all"
3855        );
3856        assert_eq!(
3857            serde_json::to_value(&dropped_before).unwrap(),
3858            serde_json::to_value(&dropped_after).unwrap(),
3859            "dry run must not mutate the would-be-dropped edge's row at all"
3860        );
3861        assert_eq!(
3862            serde_json::to_value(&annotation_before).unwrap(),
3863            serde_json::to_value(&annotation_after).unwrap(),
3864            "dry run must not mutate the incident annotation's row at all"
3865        );
3866        assert_eq!(
3867            serde_json::to_value(&nested_annotation_before).unwrap(),
3868            serde_json::to_value(&nested_annotation_after).unwrap(),
3869            "dry run must not mutate the nested incident annotation's row at all"
3870        );
3871
3872        let into_after = rt
3873            .get_entity(&tok, into.id)
3874            .await
3875            .expect("into entity must remain unmerged after a dry run");
3876        let from_after = rt
3877            .get_entity(&tok, from.id)
3878            .await
3879            .expect("from entity must not be merged away by a dry run");
3880        assert_eq!(
3881            serde_json::to_value(&into_before).unwrap(),
3882            serde_json::to_value(&into_after).unwrap(),
3883            "dry run must not mutate the into entity's row at all"
3884        );
3885        assert_eq!(
3886            serde_json::to_value(&from_before).unwrap(),
3887            serde_json::to_value(&from_after).unwrap(),
3888            "dry run must not mutate the from entity's row at all"
3889        );
3890        assert_eq!(from_after.deleted_at, None);
3891        assert_eq!(from_after.merged_into, None);
3892        assert_eq!(from_after.merge_event_id, None);
3893
3894        let events = rt
3895            .events(&tok)
3896            .unwrap()
3897            .query_events(
3898                khive_storage::EventFilter {
3899                    kinds: vec![EventKind::EntityMerged],
3900                    ..Default::default()
3901                },
3902                khive_storage::types::PageRequest {
3903                    offset: 0,
3904                    limit: 10,
3905                },
3906            )
3907            .await
3908            .unwrap();
3909        assert!(
3910            events.items.is_empty(),
3911            "a dry run must not record a merge audit event"
3912        );
3913    }
3914
3915    // A soft-deleted surviving edge must not be resurrected by a conflicting
3916    // rewire — the from-edge is dropped and the tombstone stays.
3917    #[tokio::test]
3918    async fn merge_entity_conflict_does_not_resurrect_tombstoned_edge() {
3919        let rt = rt();
3920        let tok = NamespaceToken::local();
3921        let into = rt
3922            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
3923            .await
3924            .unwrap();
3925        let from = rt
3926            .create_entity(&tok, "concept", None, "From", None, None, vec![])
3927            .await
3928            .unwrap();
3929        let shared = rt
3930            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
3931            .await
3932            .unwrap();
3933
3934        let survivor = rt
3935            .link(&tok, into.id, shared.id, EdgeRelation::Extends, 0.9, None)
3936            .await
3937            .unwrap();
3938        rt.delete_edge(&tok, survivor.id.into(), false)
3939            .await
3940            .unwrap();
3941        rt.link(&tok, from.id, shared.id, EdgeRelation::Extends, 0.2, None)
3942            .await
3943            .unwrap();
3944
3945        rt.merge_entity(
3946            &tok,
3947            into.id,
3948            from.id,
3949            EntityDedupMergePolicy::PreferInto,
3950            ContentMergeStrategy::Append,
3951            false,
3952        )
3953        .await
3954        .unwrap();
3955
3956        for (src, label) in [(into.id, "into"), (from.id, "from")] {
3957            let edges = rt
3958                .list_edges(
3959                    &tok,
3960                    crate::EdgeListFilter {
3961                        source_id: Some(src),
3962                        target_id: Some(shared.id),
3963                        relations: vec![EdgeRelation::Extends],
3964                        ..Default::default()
3965                    },
3966                    10,
3967                    0,
3968                )
3969                .await
3970                .unwrap();
3971            assert!(
3972                edges.is_empty(),
3973                "no live {label}→shared edge may exist after merging over a tombstone; got: {edges:?}"
3974            );
3975        }
3976    }
3977
3978    // The survivor row write must not null columns it doesn't merge —
3979    // entity_type (and content_ref) were lost by the old full-row
3980    // INSERT OR REPLACE.
3981    #[tokio::test]
3982    async fn merge_entity_preserves_survivor_entity_type() {
3983        let rt = rt();
3984        let tok = NamespaceToken::local();
3985        let into = rt
3986            .create_entity(&tok, "resource", Some("skill"), "Into", None, None, vec![])
3987            .await
3988            .unwrap();
3989        assert_eq!(into.entity_type.as_deref(), Some("skill"));
3990        let from = rt
3991            .create_entity(&tok, "resource", None, "From", None, None, vec![])
3992            .await
3993            .unwrap();
3994
3995        rt.merge_entity(
3996            &tok,
3997            into.id,
3998            from.id,
3999            EntityDedupMergePolicy::PreferInto,
4000            ContentMergeStrategy::Append,
4001            false,
4002        )
4003        .await
4004        .unwrap();
4005
4006        let got = rt.get_entity(&tok, into.id).await.unwrap();
4007        assert_eq!(
4008            got.entity_type.as_deref(),
4009            Some("skill"),
4010            "merge must not null the survivor's entity_type"
4011        );
4012    }
4013
4014    #[tokio::test]
4015    async fn merge_entity_preserves_survivor_content_ref() {
4016        let rt = rt();
4017        let tok = NamespaceToken::local();
4018        let into = rt
4019            .create_entity(&tok, "document", None, "Into", None, None, vec![])
4020            .await
4021            .unwrap();
4022        let from = rt
4023            .create_entity(&tok, "document", None, "From", None, None, vec![])
4024            .await
4025            .unwrap();
4026
4027        let content_ref = "blake3:0000000000000000000000000000000000000000000000000000000000000000";
4028        let store = rt.entities(&tok).unwrap();
4029        let stored = store.get_entity(into.id).await.unwrap().unwrap();
4030        store
4031            .upsert_entity(stored.with_content_ref(content_ref))
4032            .await
4033            .unwrap();
4034
4035        rt.merge_entity(
4036            &tok,
4037            into.id,
4038            from.id,
4039            EntityDedupMergePolicy::PreferInto,
4040            ContentMergeStrategy::Append,
4041            false,
4042        )
4043        .await
4044        .unwrap();
4045
4046        let got = store.get_entity(into.id).await.unwrap().unwrap();
4047        assert_eq!(
4048            got.content_ref.as_deref(),
4049            Some(content_ref),
4050            "merge must not null the survivor's content_ref"
4051        );
4052    }
4053
4054    #[tokio::test]
4055    async fn merge_entity_self_merge_rejected() {
4056        let rt = rt();
4057        let tok = NamespaceToken::local();
4058        let a = rt
4059            .create_entity(&tok, "concept", None, "A", None, None, vec![])
4060            .await
4061            .unwrap();
4062        let err = rt
4063            .merge_entity_with_reason(
4064                &tok,
4065                a.id,
4066                a.id,
4067                EntityDedupMergePolicy::PreferInto,
4068                ContentMergeStrategy::Append,
4069                false,
4070                None,
4071            )
4072            .await
4073            .unwrap_err();
4074        assert!(
4075            format!("{err:?}").contains("cannot merge an entity into itself"),
4076            "expected self-merge rejection, got: {err:?}"
4077        );
4078    }
4079
4080    #[tokio::test]
4081    async fn merge_entity_prefer_into_strategy() {
4082        let rt = rt();
4083        let tok = NamespaceToken::local();
4084        let into = rt
4085            .create_entity(
4086                &tok,
4087                "concept",
4088                None,
4089                "Into",
4090                None,
4091                Some(serde_json::json!({"a": 1})),
4092                vec![],
4093            )
4094            .await
4095            .unwrap();
4096        let from = rt
4097            .create_entity(
4098                &tok,
4099                "concept",
4100                None,
4101                "From",
4102                None,
4103                Some(serde_json::json!({"a": 2, "b": 3})),
4104                vec![],
4105            )
4106            .await
4107            .unwrap();
4108
4109        rt.merge_entity_with_reason(
4110            &tok,
4111            into.id,
4112            from.id,
4113            EntityDedupMergePolicy::PreferInto,
4114            ContentMergeStrategy::Append,
4115            false,
4116            None,
4117        )
4118        .await
4119        .unwrap();
4120
4121        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4122        let props = kept.properties.unwrap();
4123        // a stays as 1 (into wins), b is added from from.
4124        assert_eq!(props["a"], 1);
4125        assert_eq!(props["b"], 3);
4126    }
4127
4128    #[tokio::test]
4129    async fn merge_entity_prefer_from_strategy() {
4130        let rt = rt();
4131        let tok = NamespaceToken::local();
4132        let into = rt
4133            .create_entity(
4134                &tok,
4135                "concept",
4136                None,
4137                "Into",
4138                None,
4139                Some(serde_json::json!({"a": 1})),
4140                vec![],
4141            )
4142            .await
4143            .unwrap();
4144        let from = rt
4145            .create_entity(
4146                &tok,
4147                "concept",
4148                None,
4149                "From",
4150                None,
4151                Some(serde_json::json!({"a": 2, "b": 3})),
4152                vec![],
4153            )
4154            .await
4155            .unwrap();
4156
4157        rt.merge_entity_with_reason(
4158            &tok,
4159            into.id,
4160            from.id,
4161            EntityDedupMergePolicy::PreferFrom,
4162            ContentMergeStrategy::Append,
4163            false,
4164            None,
4165        )
4166        .await
4167        .unwrap();
4168
4169        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4170        let props = kept.properties.unwrap();
4171        // from wins on a, b also from from.
4172        assert_eq!(props["a"], 2);
4173        assert_eq!(props["b"], 3);
4174    }
4175
4176    #[tokio::test]
4177    async fn merge_entity_union_strategy() {
4178        let rt = rt();
4179        let tok = NamespaceToken::local();
4180        let into = rt
4181            .create_entity(
4182                &tok,
4183                "concept",
4184                None,
4185                "Into",
4186                None,
4187                Some(serde_json::json!({"a": 1})),
4188                vec![],
4189            )
4190            .await
4191            .unwrap();
4192        let from = rt
4193            .create_entity(
4194                &tok,
4195                "concept",
4196                None,
4197                "From",
4198                None,
4199                Some(serde_json::json!({"a": 2, "b": 3})),
4200                vec![],
4201            )
4202            .await
4203            .unwrap();
4204
4205        rt.merge_entity_with_reason(
4206            &tok,
4207            into.id,
4208            from.id,
4209            EntityDedupMergePolicy::Union,
4210            ContentMergeStrategy::Append,
4211            false,
4212            None,
4213        )
4214        .await
4215        .unwrap();
4216
4217        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4218        let props = kept.properties.unwrap();
4219        // Scalar conflict: into wins → a=1. b added from from.
4220        assert_eq!(props["a"], 1);
4221        assert_eq!(props["b"], 3);
4222    }
4223
4224    #[tokio::test]
4225    async fn merge_entity_unions_tags() {
4226        let rt = rt();
4227        let tok = NamespaceToken::local();
4228        let into = rt
4229            .create_entity(
4230                &tok,
4231                "concept",
4232                None,
4233                "Into",
4234                None,
4235                None,
4236                vec!["x".to_string(), "y".to_string()],
4237            )
4238            .await
4239            .unwrap();
4240        let from = rt
4241            .create_entity(
4242                &tok,
4243                "concept",
4244                None,
4245                "From",
4246                None,
4247                None,
4248                vec!["y".to_string(), "z".to_string()],
4249            )
4250            .await
4251            .unwrap();
4252
4253        rt.merge_entity_with_reason(
4254            &tok,
4255            into.id,
4256            from.id,
4257            EntityDedupMergePolicy::PreferInto,
4258            ContentMergeStrategy::Append,
4259            false,
4260            None,
4261        )
4262        .await
4263        .unwrap();
4264
4265        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4266        let mut tags = kept.tags.clone();
4267        tags.sort();
4268        assert_eq!(tags, vec!["x", "y", "z"]);
4269    }
4270
4271    #[tokio::test]
4272    async fn merge_entity_drops_self_loops() {
4273        let rt = rt();
4274        let tok = NamespaceToken::local();
4275        let a = rt
4276            .create_entity(&tok, "concept", None, "A", None, None, vec![])
4277            .await
4278            .unwrap();
4279        let b = rt
4280            .create_entity(&tok, "concept", None, "B", None, None, vec![])
4281            .await
4282            .unwrap();
4283
4284        // A `extends` B — merging B into A would produce A `extends` A → drop it.
4285        rt.link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
4286            .await
4287            .unwrap();
4288
4289        let summary = rt
4290            .merge_entity_with_reason(
4291                &tok,
4292                a.id,
4293                b.id,
4294                EntityDedupMergePolicy::PreferInto,
4295                ContentMergeStrategy::Append,
4296                false,
4297                None,
4298            )
4299            .await
4300            .unwrap();
4301
4302        assert_eq!(
4303            summary.edges_rewired, 0,
4304            "self-loop should be dropped, not rewired"
4305        );
4306
4307        let a_out = rt
4308            .neighbors(&tok, a.id, Direction::Out, None, None)
4309            .await
4310            .unwrap();
4311        assert!(a_out.is_empty(), "no self-loop should remain");
4312    }
4313
4314    // ---- content_strategy for entity merge ----
4315
4316    #[tokio::test]
4317    async fn merge_entity_append_strategy_concatenates_descriptions() {
4318        let rt = rt();
4319        let tok = NamespaceToken::local();
4320        let into = rt
4321            .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4322            .await
4323            .unwrap();
4324        let from = rt
4325            .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4326            .await
4327            .unwrap();
4328
4329        let summary = rt
4330            .merge_entity_with_reason(
4331                &tok,
4332                into.id,
4333                from.id,
4334                EntityDedupMergePolicy::PreferInto,
4335                ContentMergeStrategy::Append,
4336                false,
4337                None,
4338            )
4339            .await
4340            .unwrap();
4341
4342        assert!(
4343            summary.content_appended,
4344            "append strategy with two non-empty descriptions must report content_appended=true"
4345        );
4346        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4347        assert_eq!(kept.description.as_deref(), Some("desc A\n\n---\n\ndesc B"));
4348    }
4349
4350    #[tokio::test]
4351    async fn merge_entity_append_strategy_from_empty_is_noop() {
4352        let rt = rt();
4353        let tok = NamespaceToken::local();
4354        let into = rt
4355            .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4356            .await
4357            .unwrap();
4358        let from = rt
4359            .create_entity(&tok, "concept", None, "From", None, None, vec![])
4360            .await
4361            .unwrap();
4362
4363        let summary = rt
4364            .merge_entity_with_reason(
4365                &tok,
4366                into.id,
4367                from.id,
4368                EntityDedupMergePolicy::PreferInto,
4369                ContentMergeStrategy::Append,
4370                false,
4371                None,
4372            )
4373            .await
4374            .unwrap();
4375
4376        assert!(
4377            !summary.content_appended,
4378            "from's empty description means nothing was appended"
4379        );
4380        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4381        assert_eq!(kept.description.as_deref(), Some("desc A"));
4382    }
4383
4384    #[tokio::test]
4385    async fn merge_entity_append_strategy_into_empty_takes_from() {
4386        let rt = rt();
4387        let tok = NamespaceToken::local();
4388        let into = rt
4389            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4390            .await
4391            .unwrap();
4392        let from = rt
4393            .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4394            .await
4395            .unwrap();
4396
4397        let summary = rt
4398            .merge_entity_with_reason(
4399                &tok,
4400                into.id,
4401                from.id,
4402                EntityDedupMergePolicy::PreferInto,
4403                ContentMergeStrategy::Append,
4404                false,
4405                None,
4406            )
4407            .await
4408            .unwrap();
4409
4410        assert!(
4411            summary.content_appended,
4412            "taking from's description into an empty into is real content preservation"
4413        );
4414        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4415        assert_eq!(kept.description.as_deref(), Some("desc B"));
4416    }
4417
4418    #[tokio::test]
4419    async fn merge_entity_prefer_into_strategy_still_discards_explicitly() {
4420        let rt = rt();
4421        let tok = NamespaceToken::local();
4422        let into = rt
4423            .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4424            .await
4425            .unwrap();
4426        let from = rt
4427            .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4428            .await
4429            .unwrap();
4430
4431        let summary = rt
4432            .merge_entity_with_reason(
4433                &tok,
4434                into.id,
4435                from.id,
4436                EntityDedupMergePolicy::PreferInto,
4437                ContentMergeStrategy::PreferInto,
4438                false,
4439                None,
4440            )
4441            .await
4442            .unwrap();
4443
4444        assert!(
4445            !summary.content_appended,
4446            "explicit PreferInto opt-out must not report an append"
4447        );
4448        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4449        assert_eq!(
4450            kept.description.as_deref(),
4451            Some("desc A"),
4452            "explicit PreferInto opt-out keeps the old discard behavior"
4453        );
4454    }
4455
4456    /// `content_strategy` must be followed directly, independent of the
4457    /// entity-field `strategy`: with the default entity policy `prefer_into`,
4458    /// an explicit `content_strategy=prefer_from` must still keep the
4459    /// from-description.
4460    #[tokio::test]
4461    async fn merge_entity_prefer_from_content_strategy_wins_over_default_entity_policy() {
4462        let rt = rt();
4463        let tok = NamespaceToken::local();
4464        let into = rt
4465            .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4466            .await
4467            .unwrap();
4468        let from = rt
4469            .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4470            .await
4471            .unwrap();
4472
4473        let summary = rt
4474            .merge_entity_with_reason(
4475                &tok,
4476                into.id,
4477                from.id,
4478                EntityDedupMergePolicy::PreferInto,
4479                ContentMergeStrategy::PreferFrom,
4480                false,
4481                None,
4482            )
4483            .await
4484            .unwrap();
4485
4486        assert!(
4487            !summary.content_appended,
4488            "explicit PreferFrom is not an append"
4489        );
4490        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4491        assert_eq!(
4492            kept.description.as_deref(),
4493            Some("desc B"),
4494            "content_strategy=prefer_from must win over the default prefer_into entity policy"
4495        );
4496    }
4497
4498    #[tokio::test]
4499    async fn merge_entity_dry_run_previews_append() {
4500        let rt = rt();
4501        let tok = NamespaceToken::local();
4502        let into = rt
4503            .create_entity(&tok, "concept", None, "Into", Some("desc A"), None, vec![])
4504            .await
4505            .unwrap();
4506        let from = rt
4507            .create_entity(&tok, "concept", None, "From", Some("desc B"), None, vec![])
4508            .await
4509            .unwrap();
4510
4511        let summary = rt
4512            .merge_entity_with_reason(
4513                &tok,
4514                into.id,
4515                from.id,
4516                EntityDedupMergePolicy::PreferInto,
4517                ContentMergeStrategy::Append,
4518                true,
4519                None,
4520            )
4521            .await
4522            .unwrap();
4523
4524        assert!(summary.dry_run);
4525        assert!(
4526            summary.content_appended,
4527            "dry-run must preview the append outcome without writing"
4528        );
4529        let kept = rt.get_entity(&tok, into.id).await.unwrap();
4530        assert_eq!(
4531            kept.description.as_deref(),
4532            Some("desc A"),
4533            "dry_run=true must not mutate the into entity's description"
4534        );
4535    }
4536
4537    /// Dry-run must be a read-only, accurate preview: it must predict
4538    /// `edges_rewired` without writing, and must not append an `EntityMerged` event.
4539    #[tokio::test]
4540    async fn merge_entity_dry_run_predicts_edges_rewired_without_writing() {
4541        use khive_storage::EdgeRelation;
4542
4543        let rt = rt();
4544        let tok = NamespaceToken::local();
4545        let a = rt
4546            .create_entity(&tok, "concept", None, "A", None, None, vec![])
4547            .await
4548            .unwrap();
4549        let into = rt
4550            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4551            .await
4552            .unwrap();
4553        let from = rt
4554            .create_entity(&tok, "concept", None, "From", None, None, vec![])
4555            .await
4556            .unwrap();
4557
4558        rt.link(&tok, a.id, from.id, EdgeRelation::Extends, 1.0, None)
4559            .await
4560            .unwrap();
4561
4562        let summary = rt
4563            .merge_entity_with_reason(
4564                &tok,
4565                into.id,
4566                from.id,
4567                EntityDedupMergePolicy::PreferInto,
4568                ContentMergeStrategy::Append,
4569                true,
4570                None,
4571            )
4572            .await
4573            .unwrap();
4574
4575        assert!(summary.dry_run);
4576        assert_eq!(
4577            summary.edges_rewired, 1,
4578            "dry-run must predict the edge that would be rewired, not report zero"
4579        );
4580
4581        let a_neighbors = rt
4582            .neighbors(&tok, a.id, Direction::Out, None, None)
4583            .await
4584            .unwrap();
4585        assert_eq!(a_neighbors.len(), 1);
4586        assert_eq!(
4587            a_neighbors[0].node_id, from.id,
4588            "dry_run=true must not rewire any edges"
4589        );
4590
4591        let events = rt
4592            .events(&tok)
4593            .unwrap()
4594            .query_events(
4595                khive_storage::EventFilter {
4596                    kinds: vec![EventKind::EntityMerged],
4597                    ..Default::default()
4598                },
4599                khive_storage::types::PageRequest {
4600                    offset: 0,
4601                    limit: 10,
4602                },
4603            )
4604            .await
4605            .unwrap();
4606        assert!(
4607            events.items.is_empty(),
4608            "dry_run=true must not append an EntityMerged event"
4609        );
4610    }
4611
4612    /// ADR-014: `reason` is additive — when supplied it must land in the
4613    /// `EntityMerged` payload verbatim; the key must be entirely absent (not
4614    /// `null`) when the caller omits it.
4615    #[tokio::test]
4616    async fn merge_entity_event_reason_present_when_supplied_absent_when_not() {
4617        let rt = rt();
4618        let tok = NamespaceToken::local();
4619
4620        let into_a = rt
4621            .create_entity(&tok, "concept", None, "IntoA", None, None, vec![])
4622            .await
4623            .unwrap();
4624        let from_a = rt
4625            .create_entity(&tok, "concept", None, "FromA", None, None, vec![])
4626            .await
4627            .unwrap();
4628        rt.merge_entity_with_reason(
4629            &tok,
4630            into_a.id,
4631            from_a.id,
4632            EntityDedupMergePolicy::PreferInto,
4633            ContentMergeStrategy::Append,
4634            false,
4635            Some("duplicate".to_string()),
4636        )
4637        .await
4638        .unwrap();
4639
4640        let into_b = rt
4641            .create_entity(&tok, "concept", None, "IntoB", None, None, vec![])
4642            .await
4643            .unwrap();
4644        let from_b = rt
4645            .create_entity(&tok, "concept", None, "FromB", None, None, vec![])
4646            .await
4647            .unwrap();
4648        rt.merge_entity_with_reason(
4649            &tok,
4650            into_b.id,
4651            from_b.id,
4652            EntityDedupMergePolicy::PreferInto,
4653            ContentMergeStrategy::Append,
4654            false,
4655            None,
4656        )
4657        .await
4658        .unwrap();
4659
4660        let events = rt
4661            .events(&tok)
4662            .unwrap()
4663            .query_events(
4664                khive_storage::EventFilter {
4665                    kinds: vec![EventKind::EntityMerged],
4666                    ..Default::default()
4667                },
4668                khive_storage::types::PageRequest {
4669                    offset: 0,
4670                    limit: 10,
4671                },
4672            )
4673            .await
4674            .unwrap();
4675        assert_eq!(events.items.len(), 2);
4676
4677        let with_reason = events
4678            .items
4679            .iter()
4680            .find(|e| {
4681                e.payload.get("from_id").and_then(|v| v.as_str())
4682                    == Some(from_a.id.to_string()).as_deref()
4683            })
4684            .expect("event for the reasoned merge must exist");
4685        assert_eq!(
4686            with_reason.payload.get("reason").and_then(|v| v.as_str()),
4687            Some("duplicate"),
4688            "reason must be threaded verbatim into the payload when supplied"
4689        );
4690
4691        let without_reason = events
4692            .items
4693            .iter()
4694            .find(|e| {
4695                e.payload.get("from_id").and_then(|v| v.as_str())
4696                    == Some(from_b.id.to_string()).as_deref()
4697            })
4698            .expect("event for the reasonless merge must exist");
4699        assert!(
4700            without_reason.payload.get("reason").is_none(),
4701            "reason key must be absent (never null) when the caller omits it, got: {:?}",
4702            without_reason.payload
4703        );
4704    }
4705
4706    #[tokio::test]
4707    async fn merge_entity_with_reason_preserves_an_explicit_empty_reason() {
4708        let rt = rt();
4709        let tok = NamespaceToken::local();
4710        let into = rt
4711            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4712            .await
4713            .unwrap();
4714        let from = rt
4715            .create_entity(&tok, "concept", None, "From", None, None, vec![])
4716            .await
4717            .unwrap();
4718
4719        rt.merge_entity_with_reason(
4720            &tok,
4721            into.id,
4722            from.id,
4723            EntityDedupMergePolicy::PreferInto,
4724            ContentMergeStrategy::Append,
4725            false,
4726            Some(String::new()),
4727        )
4728        .await
4729        .unwrap();
4730
4731        let events = rt
4732            .events(&tok)
4733            .unwrap()
4734            .query_events(
4735                khive_storage::EventFilter {
4736                    kinds: vec![EventKind::EntityMerged],
4737                    ..Default::default()
4738                },
4739                khive_storage::types::PageRequest {
4740                    offset: 0,
4741                    limit: 10,
4742                },
4743            )
4744            .await
4745            .unwrap();
4746        assert_eq!(events.items.len(), 1);
4747        assert_eq!(
4748            events.items[0].payload.get("reason"),
4749            Some(&Value::String(String::new()))
4750        );
4751    }
4752
4753    #[tokio::test]
4754    async fn merge_entity_with_reason_rejects_secrets_before_reads_or_writes() {
4755        let rt = rt();
4756        let tok = NamespaceToken::local();
4757        let into = rt
4758            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
4759            .await
4760            .unwrap();
4761        let from = rt
4762            .create_entity(&tok, "concept", None, "From", None, None, vec![])
4763            .await
4764            .unwrap();
4765        let secret = secret_shaped_reason();
4766
4767        let error = rt
4768            .merge_entity_with_reason(
4769                &tok,
4770                into.id,
4771                from.id,
4772                EntityDedupMergePolicy::PreferInto,
4773                ContentMergeStrategy::Append,
4774                false,
4775                Some(secret),
4776            )
4777            .await
4778            .unwrap_err();
4779
4780        assert!(matches!(error, RuntimeError::SecretDetected(_)));
4781        assert_eq!(rt.get_entity(&tok, into.id).await.unwrap().id, into.id);
4782        assert_eq!(rt.get_entity(&tok, from.id).await.unwrap().id, from.id);
4783        let event_count = rt
4784            .events(&tok)
4785            .unwrap()
4786            .count_events(khive_storage::EventFilter {
4787                kinds: vec![EventKind::EntityMerged],
4788                ..Default::default()
4789            })
4790            .await
4791            .unwrap();
4792        assert_eq!(event_count, 0);
4793    }
4794
4795    /// ADR-014: `merge_note` must be as auditable as `merge_entity` — exactly one
4796    /// `NoteMerged` event, carrying kept/absorbed ids, per note merge.
4797    #[tokio::test]
4798    async fn merge_note_emits_exactly_one_note_merged_event_with_kept_and_absorbed_ids() {
4799        let rt = rt();
4800        let tok = NamespaceToken::local();
4801        let into = rt
4802            .create_note(&tok, "observation", None, "into note", None, None, vec![])
4803            .await
4804            .unwrap();
4805        let from = rt
4806            .create_note(&tok, "observation", None, "from note", None, None, vec![])
4807            .await
4808            .unwrap();
4809
4810        let summary = rt
4811            .merge_note_with_reason(
4812                &tok,
4813                into.id,
4814                from.id,
4815                EntityDedupMergePolicy::PreferInto,
4816                ContentMergeStrategy::Append,
4817                false,
4818                Some("duplicate".to_string()),
4819            )
4820            .await
4821            .unwrap();
4822
4823        let events = rt
4824            .events(&tok)
4825            .unwrap()
4826            .query_events(
4827                khive_storage::EventFilter {
4828                    kinds: vec![EventKind::NoteMerged],
4829                    ..Default::default()
4830                },
4831                khive_storage::types::PageRequest {
4832                    offset: 0,
4833                    limit: 10,
4834                },
4835            )
4836            .await
4837            .unwrap();
4838        assert_eq!(
4839            events.items.len(),
4840            1,
4841            "merge_note must emit exactly one NoteMerged event"
4842        );
4843
4844        let payload = &events.items[0].payload;
4845        assert_eq!(
4846            payload.get("into_id").and_then(|v| v.as_str()),
4847            Some(summary.kept_id.to_string()).as_deref()
4848        );
4849        assert_eq!(
4850            payload.get("from_id").and_then(|v| v.as_str()),
4851            Some(summary.removed_id.to_string()).as_deref()
4852        );
4853        assert_eq!(
4854            payload.get("reason").and_then(|v| v.as_str()),
4855            Some("duplicate")
4856        );
4857    }
4858
4859    #[tokio::test]
4860    async fn merge_note_with_reason_preserves_an_explicit_empty_reason() {
4861        let rt = rt();
4862        let tok = NamespaceToken::local();
4863        let into = rt
4864            .create_note(&tok, "observation", None, "into note", None, None, vec![])
4865            .await
4866            .unwrap();
4867        let from = rt
4868            .create_note(&tok, "observation", None, "from note", None, None, vec![])
4869            .await
4870            .unwrap();
4871
4872        rt.merge_note_with_reason(
4873            &tok,
4874            into.id,
4875            from.id,
4876            EntityDedupMergePolicy::PreferInto,
4877            ContentMergeStrategy::Append,
4878            false,
4879            Some(String::new()),
4880        )
4881        .await
4882        .unwrap();
4883
4884        let events = rt
4885            .events(&tok)
4886            .unwrap()
4887            .query_events(
4888                khive_storage::EventFilter {
4889                    kinds: vec![EventKind::NoteMerged],
4890                    ..Default::default()
4891                },
4892                khive_storage::types::PageRequest {
4893                    offset: 0,
4894                    limit: 10,
4895                },
4896            )
4897            .await
4898            .unwrap();
4899        assert_eq!(events.items.len(), 1);
4900        assert_eq!(
4901            events.items[0].payload.get("reason"),
4902            Some(&Value::String(String::new()))
4903        );
4904    }
4905
4906    #[tokio::test]
4907    async fn merge_note_with_reason_rejects_secrets_before_reads_or_writes() {
4908        let rt = rt();
4909        let tok = NamespaceToken::local();
4910        let into = rt
4911            .create_note(&tok, "observation", None, "into note", None, None, vec![])
4912            .await
4913            .unwrap();
4914        let from = rt
4915            .create_note(&tok, "observation", None, "from note", None, None, vec![])
4916            .await
4917            .unwrap();
4918        let secret = secret_shaped_reason();
4919
4920        let error = rt
4921            .merge_note_with_reason(
4922                &tok,
4923                into.id,
4924                from.id,
4925                EntityDedupMergePolicy::PreferInto,
4926                ContentMergeStrategy::Append,
4927                false,
4928                Some(secret),
4929            )
4930            .await
4931            .unwrap_err();
4932
4933        assert!(matches!(error, RuntimeError::SecretDetected(_)));
4934        let note_store = rt.notes(&tok).unwrap();
4935        assert_eq!(
4936            note_store.get_note(into.id).await.unwrap().unwrap().id,
4937            into.id
4938        );
4939        assert_eq!(
4940            note_store.get_note(from.id).await.unwrap().unwrap().id,
4941            from.id
4942        );
4943        let event_count = rt
4944            .events(&tok)
4945            .unwrap()
4946            .count_events(khive_storage::EventFilter {
4947                kinds: vec![EventKind::NoteMerged],
4948                ..Default::default()
4949            })
4950            .await
4951            .unwrap();
4952        assert_eq!(event_count, 0);
4953    }
4954
4955    #[tokio::test]
4956    async fn legacy_merge_methods_remain_source_compatible() {
4957        let rt = rt();
4958        let tok = NamespaceToken::local();
4959        let into_entity = rt
4960            .create_entity(&tok, "concept", None, "Entity A", None, None, vec![])
4961            .await
4962            .unwrap();
4963        let from_entity = rt
4964            .create_entity(&tok, "concept", None, "Entity B", None, None, vec![])
4965            .await
4966            .unwrap();
4967        let into_note = rt
4968            .create_note(&tok, "observation", None, "note A", None, None, vec![])
4969            .await
4970            .unwrap();
4971        let from_note = rt
4972            .create_note(&tok, "observation", None, "note B", None, None, vec![])
4973            .await
4974            .unwrap();
4975
4976        rt.merge_entity(
4977            &tok,
4978            into_entity.id,
4979            from_entity.id,
4980            EntityDedupMergePolicy::PreferInto,
4981            ContentMergeStrategy::Append,
4982            false,
4983        )
4984        .await
4985        .unwrap();
4986        rt.merge_note(
4987            &tok,
4988            into_note.id,
4989            from_note.id,
4990            EntityDedupMergePolicy::PreferInto,
4991            ContentMergeStrategy::Append,
4992            false,
4993        )
4994        .await
4995        .unwrap();
4996    }
4997
4998    // ---- interim merged_into miss-hint (data-integrity, precedes ADR-113 chase) ----
4999
5000    #[tokio::test]
5001    async fn get_entity_after_merge_discloses_kept_id() {
5002        let rt = rt();
5003        let tok = NamespaceToken::local();
5004        let into = rt
5005            .create_entity(&tok, "concept", None, "Kept", None, None, vec![])
5006            .await
5007            .unwrap();
5008        let from = rt
5009            .create_entity(&tok, "concept", None, "Absorbed", None, None, vec![])
5010            .await
5011            .unwrap();
5012
5013        rt.merge_entity(
5014            &tok,
5015            into.id,
5016            from.id,
5017            EntityDedupMergePolicy::PreferInto,
5018            ContentMergeStrategy::Append,
5019            false,
5020        )
5021        .await
5022        .unwrap();
5023
5024        let err = rt.get_entity(&tok, from.id).await.unwrap_err();
5025        let msg = err.to_string();
5026        assert!(
5027            msg.contains("was merged into") && msg.contains(&into.id.to_string()),
5028            "expected a merged_into disclosure naming {}, got {msg:?}",
5029            into.id
5030        );
5031    }
5032
5033    #[tokio::test]
5034    async fn get_entity_on_plain_soft_delete_stays_bare_not_found() {
5035        let rt = rt();
5036        let tok = NamespaceToken::local();
5037        let entity = rt
5038            .create_entity(&tok, "concept", None, "Deleted", None, None, vec![])
5039            .await
5040            .unwrap();
5041        assert!(rt.delete_entity(&tok, entity.id, false).await.unwrap());
5042
5043        let err = rt.get_entity(&tok, entity.id).await.unwrap_err();
5044        let msg = err.to_string();
5045        assert!(
5046            !msg.contains("merged into"),
5047            "plain soft-delete must not gain a merge hint, got {msg:?}"
5048        );
5049        assert_eq!(msg, format!("not found: entity {}", entity.id));
5050    }
5051
5052    #[tokio::test]
5053    async fn get_entity_on_absent_id_stays_bare_not_found() {
5054        let rt = rt();
5055        let tok = NamespaceToken::local();
5056        let absent = Uuid::new_v4();
5057
5058        let err = rt.get_entity(&tok, absent).await.unwrap_err();
5059        let msg = err.to_string();
5060        assert!(
5061            !msg.contains("merged into"),
5062            "a never-existed id must not gain a merge hint, got {msg:?}"
5063        );
5064        assert_eq!(msg, format!("not found: entity {absent}"));
5065    }
5066
5067    // ---- merge helper unit tests ----
5068
5069    #[test]
5070    fn union_tags_deduplicates() {
5071        let (tags, added) = union_tags(
5072            &["x".to_string(), "y".to_string()],
5073            &["y".to_string(), "z".to_string()],
5074        );
5075        let mut sorted = tags.clone();
5076        sorted.sort();
5077        assert_eq!(sorted, vec!["x", "y", "z"]);
5078        assert_eq!(added, 1);
5079    }
5080
5081    #[test]
5082    fn merge_properties_prefer_into_fills_missing_keys() {
5083        let a = serde_json::json!({"a": 1});
5084        let b = serde_json::json!({"a": 99, "b": 2});
5085        let (merged, added) =
5086            merge_properties(&Some(a), &Some(b), EntityDedupMergePolicy::PreferInto);
5087        let m = merged.unwrap();
5088        assert_eq!(m["a"], 1);
5089        assert_eq!(m["b"], 2);
5090        assert_eq!(added, 1);
5091    }
5092
5093    // ---- tombstone and note merge tests ----
5094
5095    #[tokio::test]
5096    async fn merge_entity_tombstones_source_with_provenance() {
5097        let rt = rt();
5098        let tok = NamespaceToken::local();
5099        let into = rt
5100            .create_entity(&tok, "concept", None, "Into", None, None, vec![])
5101            .await
5102            .unwrap();
5103        let from = rt
5104            .create_entity(&tok, "concept", None, "From", None, None, vec![])
5105            .await
5106            .unwrap();
5107        let from_id = from.id;
5108
5109        rt.merge_entity_with_reason(
5110            &tok,
5111            into.id,
5112            from_id,
5113            EntityDedupMergePolicy::PreferInto,
5114            ContentMergeStrategy::Append,
5115            false,
5116            None,
5117        )
5118        .await
5119        .unwrap();
5120
5121        assert!(
5122            rt.get_entity(&tok, from_id).await.is_err(),
5123            "tombstoned source should not be returned by get_entity"
5124        );
5125
5126        let pool = rt.backend().pool_arc();
5127        let (deleted_at, merged_into): (Option<i64>, Option<String>) =
5128            tokio::task::spawn_blocking(move || {
5129                let guard = pool.writer().unwrap();
5130                guard
5131                    .conn()
5132                    .query_row(
5133                        "SELECT deleted_at, merged_into FROM entities WHERE id = ?1",
5134                        [from_id.to_string()],
5135                        |row| Ok((row.get(0)?, row.get(1)?)),
5136                    )
5137                    .unwrap()
5138            })
5139            .await
5140            .unwrap();
5141        assert!(
5142            deleted_at.is_some(),
5143            "tombstoned entity must have deleted_at set"
5144        );
5145        assert_eq!(
5146            merged_into.as_deref(),
5147            Some(into.id.to_string().as_str()),
5148            "merged_into must point to into_id"
5149        );
5150    }
5151
5152    #[tokio::test]
5153    async fn generic_update_and_merge_reject_schedule_managed_notes() {
5154        let rt = rt();
5155        let tok = NamespaceToken::local();
5156        let schedule_a = rt
5157            .create_note(
5158                &tok,
5159                "scheduled_event",
5160                None,
5161                "stats()",
5162                None,
5163                Some(serde_json::json!({
5164                    "event_type": "schedule",
5165                    "payload": "stats()",
5166                    "status": "pending",
5167                    "trigger_at": "2099-01-01T00:00:00Z"
5168                })),
5169                vec![],
5170            )
5171            .await
5172            .unwrap();
5173        let schedule_b = rt
5174            .create_note(
5175                &tok,
5176                "scheduled_event",
5177                None,
5178                "stats()",
5179                None,
5180                Some(serde_json::json!({
5181                    "event_type": "schedule",
5182                    "payload": "stats()",
5183                    "status": "pending",
5184                    "trigger_at": "2099-01-02T00:00:00Z"
5185                })),
5186                vec![],
5187            )
5188            .await
5189            .unwrap();
5190
5191        let update_error = rt
5192            .update_note(
5193                &tok,
5194                schedule_a.id,
5195                NotePatch::new(
5196                    None,
5197                    None,
5198                    None,
5199                    None,
5200                    Some(serde_json::json!({ "payload": "delete(id=\"victim\")" })),
5201                ),
5202            )
5203            .await
5204            .expect_err("schedule-managed note update must fail");
5205        assert!(
5206            update_error.to_string().contains("schedule-managed"),
5207            "{update_error}"
5208        );
5209
5210        for (into_id, from_id) in [
5211            (schedule_a.id, schedule_b.id),
5212            (schedule_b.id, schedule_a.id),
5213        ] {
5214            let merge_error = rt
5215                .merge_note(
5216                    &tok,
5217                    into_id,
5218                    from_id,
5219                    EntityDedupMergePolicy::PreferFrom,
5220                    ContentMergeStrategy::PreferFrom,
5221                    false,
5222                )
5223                .await
5224                .expect_err("either schedule-managed merge operand must fail");
5225            assert!(
5226                merge_error.to_string().contains("schedule-managed"),
5227                "{merge_error}"
5228            );
5229        }
5230
5231        let store = rt.notes(&tok).unwrap();
5232        for (id, trigger_at) in [
5233            (schedule_a.id, "2099-01-01T00:00:00Z"),
5234            (schedule_b.id, "2099-01-02T00:00:00Z"),
5235        ] {
5236            let note = store
5237                .get_note(id)
5238                .await
5239                .unwrap()
5240                .expect("rejected generic mutation leaves the schedule intact");
5241            assert_eq!(note.properties.as_ref().unwrap()["trigger_at"], trigger_at);
5242        }
5243    }
5244
5245    #[tokio::test]
5246    async fn merge_note_same_kind_appends_content() {
5247        let rt = rt();
5248        let tok = NamespaceToken::local();
5249        let into = rt
5250            .create_note(
5251                &tok,
5252                "observation",
5253                None,
5254                "Into content",
5255                None,
5256                None,
5257                vec![],
5258            )
5259            .await
5260            .unwrap();
5261        let from = rt
5262            .create_note(
5263                &tok,
5264                "observation",
5265                None,
5266                "From content",
5267                None,
5268                None,
5269                vec![],
5270            )
5271            .await
5272            .unwrap();
5273        let from_id = from.id;
5274
5275        let summary = rt
5276            .merge_note_with_reason(
5277                &tok,
5278                into.id,
5279                from_id,
5280                EntityDedupMergePolicy::PreferInto,
5281                ContentMergeStrategy::Append,
5282                false,
5283                None,
5284            )
5285            .await
5286            .unwrap();
5287
5288        assert_eq!(summary.kept_id, into.id);
5289        assert_eq!(summary.removed_id, from_id);
5290        assert!(summary.content_appended);
5291        assert!(!summary.dry_run);
5292
5293        let from_store = rt.notes(&tok).unwrap();
5294        assert!(
5295            from_store.get_note(from_id).await.unwrap().is_none(),
5296            "merged-from note should be soft-deleted"
5297        );
5298    }
5299
5300    // Note merge must absorb a conflicting edge natural key exactly like entity
5301    // merge does, since both route through the shared EDGE_SYMMETRIC_*_SQL arms.
5302    #[tokio::test]
5303    async fn merge_note_survives_shared_edge_to_third_party() {
5304        use khive_storage::EdgeRelation;
5305        let rt = rt();
5306        let tok = NamespaceToken::local();
5307
5308        let into = rt
5309            .create_note(&tok, "observation", None, "Into", None, None, vec![])
5310            .await
5311            .unwrap();
5312        let from = rt
5313            .create_note(&tok, "observation", None, "From", None, None, vec![])
5314            .await
5315            .unwrap();
5316        let shared = rt
5317            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5318            .await
5319            .unwrap();
5320
5321        // Both into and from annotate the same shared entity — rewiring from's
5322        // edge onto into during merge produces a duplicate (into, shared,
5323        // annotates) triple, exercising the conflict-probe/delete arms.
5324        rt.link(&tok, into.id, shared.id, EdgeRelation::Annotates, 1.0, None)
5325            .await
5326            .unwrap();
5327        rt.link(&tok, from.id, shared.id, EdgeRelation::Annotates, 1.0, None)
5328            .await
5329            .unwrap();
5330
5331        let summary = rt
5332            .merge_note_with_reason(
5333                &tok,
5334                into.id,
5335                from.id,
5336                EntityDedupMergePolicy::PreferInto,
5337                ContentMergeStrategy::Append,
5338                false,
5339                None,
5340            )
5341            .await
5342            .expect("merge must succeed even when both notes annotate the same entity");
5343
5344        assert_eq!(summary.kept_id, into.id);
5345        assert_eq!(summary.removed_id, from.id);
5346
5347        let into_edges = rt
5348            .list_edges(
5349                &tok,
5350                crate::EdgeListFilter {
5351                    source_id: Some(into.id),
5352                    target_id: Some(shared.id),
5353                    relations: vec![EdgeRelation::Annotates],
5354                    ..Default::default()
5355                },
5356                10,
5357                0,
5358            )
5359            .await
5360            .unwrap();
5361        assert_eq!(
5362            into_edges.len(),
5363            1,
5364            "exactly one live into→shared annotates edge must exist after merge; got: {into_edges:?}"
5365        );
5366    }
5367
5368    #[tokio::test]
5369    async fn merge_note_conflict_records_dropped_edge_and_cascades_annotation() {
5370        let rt = rt();
5371        let tok = NamespaceToken::local();
5372        let into = rt
5373            .create_note(&tok, "observation", None, "Into", None, None, vec![])
5374            .await
5375            .unwrap();
5376        let from = rt
5377            .create_note(&tok, "observation", None, "From", None, None, vec![])
5378            .await
5379            .unwrap();
5380        let annotator = rt
5381            .create_note(
5382                &tok,
5383                "observation",
5384                None,
5385                "edge annotation",
5386                None,
5387                None,
5388                vec![],
5389            )
5390            .await
5391            .unwrap();
5392        let shared = rt
5393            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5394            .await
5395            .unwrap();
5396
5397        let survivor = rt
5398            .link(
5399                &tok,
5400                into.id,
5401                shared.id,
5402                EdgeRelation::Annotates,
5403                1.0,
5404                Some(serde_json::json!({"source": "survivor"})),
5405            )
5406            .await
5407            .unwrap();
5408        let dropped = rt
5409            .link(
5410                &tok,
5411                from.id,
5412                shared.id,
5413                EdgeRelation::Annotates,
5414                0.4,
5415                Some(serde_json::json!({"source": "dropped"})),
5416            )
5417            .await
5418            .unwrap();
5419        let annotation = rt
5420            .link(
5421                &tok,
5422                annotator.id,
5423                dropped.id.into(),
5424                EdgeRelation::Annotates,
5425                0.8,
5426                Some(serde_json::json!({"why": "duplicate claim"})),
5427            )
5428            .await
5429            .unwrap();
5430        rt.delete_edge(&tok, annotation.id.into(), false)
5431            .await
5432            .unwrap();
5433
5434        let summary = rt
5435            .merge_note(
5436                &tok,
5437                into.id,
5438                from.id,
5439                EntityDedupMergePolicy::PreferInto,
5440                ContentMergeStrategy::Append,
5441                false,
5442            )
5443            .await
5444            .unwrap();
5445
5446        let [conflict] = summary.edge_conflict_preimages.as_slice() else {
5447            panic!(
5448                "expected one note-merge edge conflict, got {:?}",
5449                summary.edge_conflict_preimages
5450            );
5451        };
5452        assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
5453        assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
5454        assert_eq!(conflict.dropped_edge.source_id, from.id);
5455        assert_eq!(conflict.dropped_edge.weight, 0.4);
5456        assert_eq!(
5457            conflict.dropped_edge.metadata,
5458            Some(serde_json::json!({"source": "dropped"}))
5459        );
5460        assert_eq!(conflict.incident_edge_preimages.len(), 1);
5461        assert_eq!(
5462            conflict.incident_edge_preimages[0].id,
5463            Uuid::from(annotation.id)
5464        );
5465        assert_eq!(
5466            conflict.incident_edge_preimages[0].metadata,
5467            Some(serde_json::json!({"why": "duplicate claim"}))
5468        );
5469        assert!(
5470            conflict.incident_edge_preimages[0].deleted_at.is_some(),
5471            "the cascade preimage must retain an annotation's tombstone state"
5472        );
5473        assert!(rt
5474            .get_edge_including_deleted(&tok, dropped.id.into())
5475            .await
5476            .unwrap()
5477            .is_none());
5478        assert!(
5479            rt.get_edge_including_deleted(&tok, annotation.id.into())
5480                .await
5481                .unwrap()
5482                .is_none(),
5483            "annotation targeting the dropped edge must be cascaded, not left dangling"
5484        );
5485
5486        let events = rt
5487            .events(&tok)
5488            .unwrap()
5489            .query_events(
5490                khive_storage::EventFilter {
5491                    kinds: vec![EventKind::NoteMerged],
5492                    ..Default::default()
5493                },
5494                khive_storage::types::PageRequest {
5495                    offset: 0,
5496                    limit: 10,
5497                },
5498            )
5499            .await
5500            .unwrap();
5501        assert_eq!(events.items.len(), 1);
5502        assert_eq!(
5503            events.items[0].payload["edge_conflict_preimages"],
5504            serde_json::to_value(&summary.edge_conflict_preimages).unwrap()
5505        );
5506    }
5507
5508    // A dry run must predict the same conflict preimages a committing note
5509    // merge would produce, without deleting or mutating a single row. The
5510    // incident cascade is two levels deep (an annotation on the dropped
5511    // edge, and a nested annotation on that annotation) so the root-to-leaf
5512    // ordering ADR-014 promises is actually exercised, not just a
5513    // one-element vec that trivially satisfies any order. Every row touched
5514    // by the merge — both notes and every edge — is snapshotted before the
5515    // dry run and compared field-for-field against its post-run state.
5516    #[tokio::test]
5517    async fn merge_note_dry_run_conflict_returns_preimages_without_mutating() {
5518        let rt = rt();
5519        let tok = NamespaceToken::local();
5520        let into = rt
5521            .create_note(&tok, "observation", None, "Into", None, None, vec![])
5522            .await
5523            .unwrap();
5524        let from = rt
5525            .create_note(&tok, "observation", None, "From", None, None, vec![])
5526            .await
5527            .unwrap();
5528        let annotator = rt
5529            .create_note(
5530                &tok,
5531                "observation",
5532                None,
5533                "edge annotation",
5534                None,
5535                None,
5536                vec![],
5537            )
5538            .await
5539            .unwrap();
5540        let nested_annotator = rt
5541            .create_note(
5542                &tok,
5543                "observation",
5544                None,
5545                "nested edge annotation",
5546                None,
5547                None,
5548                vec![],
5549            )
5550            .await
5551            .unwrap();
5552        let shared = rt
5553            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
5554            .await
5555            .unwrap();
5556
5557        let survivor = rt
5558            .link(
5559                &tok,
5560                into.id,
5561                shared.id,
5562                EdgeRelation::Annotates,
5563                1.0,
5564                Some(serde_json::json!({"source": "survivor"})),
5565            )
5566            .await
5567            .unwrap();
5568        let dropped = rt
5569            .link(
5570                &tok,
5571                from.id,
5572                shared.id,
5573                EdgeRelation::Annotates,
5574                0.4,
5575                Some(serde_json::json!({"source": "dropped"})),
5576            )
5577            .await
5578            .unwrap();
5579        let annotation = rt
5580            .link(
5581                &tok,
5582                annotator.id,
5583                dropped.id.into(),
5584                EdgeRelation::Annotates,
5585                0.8,
5586                Some(serde_json::json!({"why": "duplicate claim"})),
5587            )
5588            .await
5589            .unwrap();
5590        let nested_annotation = rt
5591            .link(
5592                &tok,
5593                nested_annotator.id,
5594                annotation.id.into(),
5595                EdgeRelation::Annotates,
5596                0.6,
5597                Some(serde_json::json!({"why": "nested duplicate claim"})),
5598            )
5599            .await
5600            .unwrap();
5601        rt.delete_edge(&tok, nested_annotation.id.into(), false)
5602            .await
5603            .unwrap();
5604
5605        let survivor_before = rt
5606            .get_edge_including_deleted(&tok, survivor.id.into())
5607            .await
5608            .unwrap()
5609            .expect("survivor edge exists");
5610        let dropped_before = rt
5611            .get_edge_including_deleted(&tok, dropped.id.into())
5612            .await
5613            .unwrap()
5614            .expect("dropped edge exists");
5615        let annotation_before = rt
5616            .get_edge_including_deleted(&tok, annotation.id.into())
5617            .await
5618            .unwrap()
5619            .expect("annotation edge exists");
5620        let nested_annotation_before = rt
5621            .get_edge_including_deleted(&tok, nested_annotation.id.into())
5622            .await
5623            .unwrap()
5624            .expect("nested annotation edge exists");
5625        let into_before = rt
5626            .get_note_including_deleted(&tok, into.id)
5627            .await
5628            .unwrap()
5629            .expect("into note exists");
5630        let from_before = rt
5631            .get_note_including_deleted(&tok, from.id)
5632            .await
5633            .unwrap()
5634            .expect("from note exists");
5635
5636        let summary = rt
5637            .merge_note(
5638                &tok,
5639                into.id,
5640                from.id,
5641                EntityDedupMergePolicy::PreferInto,
5642                ContentMergeStrategy::Append,
5643                true,
5644            )
5645            .await
5646            .unwrap();
5647
5648        let [conflict] = summary.edge_conflict_preimages.as_slice() else {
5649            panic!(
5650                "expected one note-merge edge conflict from the dry run, got {:?}",
5651                summary.edge_conflict_preimages
5652            );
5653        };
5654        assert_eq!(conflict.surviving_edge_id, Uuid::from(survivor.id));
5655        assert_eq!(conflict.dropped_edge.id, Uuid::from(dropped.id));
5656        assert_eq!(conflict.dropped_edge.source_id, from.id);
5657        assert_eq!(conflict.dropped_edge.weight, 0.4);
5658        // Root-to-leaf order (ADR-014): the direct annotation on the dropped
5659        // edge must precede the annotation nested on top of it.
5660        assert_eq!(conflict.incident_edge_preimages.len(), 2);
5661        assert_eq!(
5662            conflict.incident_edge_preimages[0].id,
5663            Uuid::from(annotation.id)
5664        );
5665        assert!(
5666            conflict.incident_edge_preimages[0].deleted_at.is_none(),
5667            "the direct annotation was never soft-deleted"
5668        );
5669        assert_eq!(
5670            conflict.incident_edge_preimages[1].id,
5671            Uuid::from(nested_annotation.id)
5672        );
5673        assert!(
5674            conflict.incident_edge_preimages[1].deleted_at.is_some(),
5675            "dry-run preimage must retain the nested annotation's tombstone state"
5676        );
5677
5678        let survivor_after = rt
5679            .get_edge_including_deleted(&tok, survivor.id.into())
5680            .await
5681            .unwrap()
5682            .expect("dry run must not delete the survivor edge");
5683        let dropped_after = rt
5684            .get_edge_including_deleted(&tok, dropped.id.into())
5685            .await
5686            .unwrap()
5687            .expect("dry run must not delete the dropped edge");
5688        let annotation_after = rt
5689            .get_edge_including_deleted(&tok, annotation.id.into())
5690            .await
5691            .unwrap()
5692            .expect("dry run must not delete the cascaded annotation");
5693        let nested_annotation_after = rt
5694            .get_edge_including_deleted(&tok, nested_annotation.id.into())
5695            .await
5696            .unwrap()
5697            .expect("dry run must not delete the nested cascaded annotation");
5698        assert_eq!(
5699            serde_json::to_value(&survivor_before).unwrap(),
5700            serde_json::to_value(&survivor_after).unwrap(),
5701            "dry run must not mutate the surviving edge's row at all"
5702        );
5703        assert_eq!(
5704            serde_json::to_value(&dropped_before).unwrap(),
5705            serde_json::to_value(&dropped_after).unwrap(),
5706            "dry run must not mutate the would-be-dropped edge's row at all"
5707        );
5708        assert_eq!(
5709            serde_json::to_value(&annotation_before).unwrap(),
5710            serde_json::to_value(&annotation_after).unwrap(),
5711            "dry run must not mutate the incident annotation's row at all"
5712        );
5713        assert_eq!(
5714            serde_json::to_value(&nested_annotation_before).unwrap(),
5715            serde_json::to_value(&nested_annotation_after).unwrap(),
5716            "dry run must not mutate the nested incident annotation's row at all"
5717        );
5718
5719        let into_after = rt
5720            .get_note_including_deleted(&tok, into.id)
5721            .await
5722            .unwrap()
5723            .expect("into note must remain unmerged after a dry run");
5724        let from_after = rt
5725            .get_note_including_deleted(&tok, from.id)
5726            .await
5727            .unwrap()
5728            .expect("from note must not be deleted by a dry run");
5729        assert_eq!(
5730            serde_json::to_value(&into_before).unwrap(),
5731            serde_json::to_value(&into_after).unwrap(),
5732            "dry run must not mutate the into note's row at all"
5733        );
5734        assert_eq!(
5735            serde_json::to_value(&from_before).unwrap(),
5736            serde_json::to_value(&from_after).unwrap(),
5737            "dry run must not mutate the from note's row at all"
5738        );
5739        assert_eq!(from_after.status, from_before.status);
5740        assert_eq!(from_after.deleted_at, None);
5741
5742        let events = rt
5743            .events(&tok)
5744            .unwrap()
5745            .query_events(
5746                khive_storage::EventFilter {
5747                    kinds: vec![EventKind::NoteMerged],
5748                    ..Default::default()
5749                },
5750                khive_storage::types::PageRequest {
5751                    offset: 0,
5752                    limit: 10,
5753                },
5754            )
5755            .await
5756            .unwrap();
5757        assert!(
5758            events.items.is_empty(),
5759            "a dry run must not record a merge audit event"
5760        );
5761    }
5762
5763    // The rewire contract check must preserve note→note supersedes, supports,
5764    // and refutes — `validate_edge_relation_endpoints` permits any note→note
5765    // pair for these relations, so the merge matcher must too, or a note merge
5766    // deletes valid epistemic/supersession edges.
5767    #[tokio::test]
5768    async fn merge_note_preserves_note_to_note_epistemic_and_supersession_edges() {
5769        use khive_storage::EdgeRelation;
5770        let rt = rt();
5771        let tok = NamespaceToken::local();
5772
5773        let into = rt
5774            .create_note(&tok, "observation", None, "Into", None, None, vec![])
5775            .await
5776            .unwrap();
5777        let from = rt
5778            .create_note(&tok, "observation", None, "From", None, None, vec![])
5779            .await
5780            .unwrap();
5781        let superseded = rt
5782            .create_note(&tok, "observation", None, "Old", None, None, vec![])
5783            .await
5784            .unwrap();
5785        let claim = rt
5786            .create_note(&tok, "insight", None, "Claim", None, None, vec![])
5787            .await
5788            .unwrap();
5789        let counter = rt
5790            .create_note(&tok, "observation", None, "Counter", None, None, vec![])
5791            .await
5792            .unwrap();
5793
5794        // Outgoing from `from` (source rewires) and incoming onto `from`
5795        // (target rewires) — both directions must survive.
5796        rt.link(
5797            &tok,
5798            from.id,
5799            superseded.id,
5800            EdgeRelation::Supersedes,
5801            1.0,
5802            None,
5803        )
5804        .await
5805        .unwrap();
5806        rt.link(&tok, from.id, claim.id, EdgeRelation::Supports, 1.0, None)
5807            .await
5808            .unwrap();
5809        rt.link(&tok, counter.id, from.id, EdgeRelation::Refutes, 1.0, None)
5810            .await
5811            .unwrap();
5812
5813        let summary = rt
5814            .merge_note_with_reason(
5815                &tok,
5816                into.id,
5817                from.id,
5818                EntityDedupMergePolicy::PreferInto,
5819                ContentMergeStrategy::Append,
5820                false,
5821                None,
5822            )
5823            .await
5824            .unwrap();
5825
5826        assert_eq!(
5827            summary.edges_rewired, 3,
5828            "all three note→note edges must be rewired, not contract-dropped"
5829        );
5830        assert_eq!(
5831            summary.edges_contract_skipped, 0,
5832            "no valid note→note supersedes/supports/refutes edge may be dropped"
5833        );
5834
5835        for (src, tgt, rel) in [
5836            (into.id, superseded.id, EdgeRelation::Supersedes),
5837            (into.id, claim.id, EdgeRelation::Supports),
5838            (counter.id, into.id, EdgeRelation::Refutes),
5839        ] {
5840            let edges = rt
5841                .list_edges(
5842                    &tok,
5843                    crate::EdgeListFilter {
5844                        source_id: Some(src),
5845                        target_id: Some(tgt),
5846                        relations: vec![rel],
5847                        ..Default::default()
5848                    },
5849                    10,
5850                    0,
5851                )
5852                .await
5853                .unwrap();
5854            assert_eq!(
5855                edges.len(),
5856                1,
5857                "rewired {rel:?} edge {src}→{tgt} must survive the merge; got {edges:?}"
5858            );
5859        }
5860    }
5861
5862    // Annotates targets may be edges or events — substrates
5863    // `resolve_merge_edge_endpoint` cannot resolve. The contract check must
5864    // exempt annotates BEFORE endpoint resolution, or a note merge deletes
5865    // valid annotates edges pointing at them.
5866    #[tokio::test]
5867    async fn merge_note_preserves_annotates_edges_targeting_edges_and_events() {
5868        use khive_storage::EdgeRelation;
5869        let rt = rt();
5870        let tok = NamespaceToken::local();
5871
5872        // An edge to annotate.
5873        let a = rt
5874            .create_entity(&tok, "concept", None, "A", None, None, vec![])
5875            .await
5876            .unwrap();
5877        let b = rt
5878            .create_entity(&tok, "concept", None, "B", None, None, vec![])
5879            .await
5880            .unwrap();
5881        let annotated_edge = rt
5882            .link(&tok, a.id, b.id, EdgeRelation::Extends, 1.0, None)
5883            .await
5884            .unwrap();
5885
5886        // An event to annotate: a throwaway note merge emits a NoteMerged
5887        // event (creation ops don't emit in this harness).
5888        let scrap_into = rt
5889            .create_note(&tok, "observation", None, "ScrapInto", None, None, vec![])
5890            .await
5891            .unwrap();
5892        let scrap_from = rt
5893            .create_note(&tok, "observation", None, "ScrapFrom", None, None, vec![])
5894            .await
5895            .unwrap();
5896        rt.merge_note_with_reason(
5897            &tok,
5898            scrap_into.id,
5899            scrap_from.id,
5900            EntityDedupMergePolicy::PreferInto,
5901            ContentMergeStrategy::Append,
5902            false,
5903            None,
5904        )
5905        .await
5906        .unwrap();
5907        let events = rt
5908            .events(&tok)
5909            .unwrap()
5910            .query_events(
5911                khive_storage::EventFilter {
5912                    kinds: vec![EventKind::NoteMerged],
5913                    ..Default::default()
5914                },
5915                khive_storage::types::PageRequest {
5916                    offset: 0,
5917                    limit: 1,
5918                },
5919            )
5920            .await
5921            .unwrap();
5922        let annotated_event_id = events.items[0].id;
5923
5924        let into = rt
5925            .create_note(&tok, "observation", None, "Into", None, None, vec![])
5926            .await
5927            .unwrap();
5928        let from = rt
5929            .create_note(&tok, "observation", None, "From", None, None, vec![])
5930            .await
5931            .unwrap();
5932
5933        rt.link(
5934            &tok,
5935            from.id,
5936            annotated_edge.id.0,
5937            EdgeRelation::Annotates,
5938            1.0,
5939            None,
5940        )
5941        .await
5942        .unwrap();
5943        rt.link(
5944            &tok,
5945            from.id,
5946            annotated_event_id,
5947            EdgeRelation::Annotates,
5948            1.0,
5949            None,
5950        )
5951        .await
5952        .unwrap();
5953
5954        let summary = rt
5955            .merge_note_with_reason(
5956                &tok,
5957                into.id,
5958                from.id,
5959                EntityDedupMergePolicy::PreferInto,
5960                ContentMergeStrategy::Append,
5961                false,
5962                None,
5963            )
5964            .await
5965            .unwrap();
5966
5967        assert_eq!(
5968            summary.edges_rewired, 2,
5969            "annotates edges targeting an edge and an event must be rewired"
5970        );
5971        assert_eq!(
5972            summary.edges_contract_skipped, 0,
5973            "no valid annotates edge may be dropped as contract-violating"
5974        );
5975
5976        for tgt in [annotated_edge.id.0, annotated_event_id] {
5977            let edges = rt
5978                .list_edges(
5979                    &tok,
5980                    crate::EdgeListFilter {
5981                        source_id: Some(into.id),
5982                        target_id: Some(tgt),
5983                        relations: vec![EdgeRelation::Annotates],
5984                        ..Default::default()
5985                    },
5986                    10,
5987                    0,
5988                )
5989                .await
5990                .unwrap();
5991            assert_eq!(
5992                edges.len(),
5993                1,
5994                "rewired annotates edge onto target {tgt} must survive the merge; got {edges:?}"
5995            );
5996        }
5997    }
5998
5999    // A note dry-run must predict edges_rewired like the entity path does,
6000    // and must not touch topology.
6001    #[tokio::test]
6002    async fn merge_note_dry_run_predicts_edges_rewired() {
6003        use khive_storage::EdgeRelation;
6004        let rt = rt();
6005        let tok = NamespaceToken::local();
6006        let into = rt
6007            .create_note(&tok, "observation", None, "Into", None, None, vec![])
6008            .await
6009            .unwrap();
6010        let from = rt
6011            .create_note(&tok, "observation", None, "From", None, None, vec![])
6012            .await
6013            .unwrap();
6014        let shared = rt
6015            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6016            .await
6017            .unwrap();
6018        rt.link(&tok, from.id, shared.id, EdgeRelation::Annotates, 1.0, None)
6019            .await
6020            .unwrap();
6021
6022        let summary = rt
6023            .merge_note_with_reason(
6024                &tok,
6025                into.id,
6026                from.id,
6027                EntityDedupMergePolicy::PreferInto,
6028                ContentMergeStrategy::Append,
6029                true,
6030                None,
6031            )
6032            .await
6033            .unwrap();
6034        assert!(summary.dry_run);
6035        assert_eq!(
6036            summary.edges_rewired, 1,
6037            "note dry-run must predict the rewire count"
6038        );
6039
6040        let from_edges = rt
6041            .list_edges(
6042                &tok,
6043                crate::EdgeListFilter {
6044                    source_id: Some(from.id),
6045                    target_id: Some(shared.id),
6046                    relations: vec![EdgeRelation::Annotates],
6047                    ..Default::default()
6048                },
6049                10,
6050                0,
6051            )
6052            .await
6053            .unwrap();
6054        assert_eq!(from_edges.len(), 1, "dry-run must leave topology untouched");
6055    }
6056
6057    #[tokio::test]
6058    async fn merge_note_different_kinds_rejected() {
6059        let rt = rt();
6060        let tok = NamespaceToken::local();
6061        let into = rt
6062            .create_note(&tok, "observation", None, "Into", None, None, vec![])
6063            .await
6064            .unwrap();
6065        let from = rt
6066            .create_note(&tok, "decision", None, "From", None, None, vec![])
6067            .await
6068            .unwrap();
6069
6070        let result = rt
6071            .merge_note_with_reason(
6072                &tok,
6073                into.id,
6074                from.id,
6075                EntityDedupMergePolicy::PreferInto,
6076                ContentMergeStrategy::Append,
6077                false,
6078                None,
6079            )
6080            .await;
6081        assert!(result.is_err(), "merging different note kinds must fail");
6082    }
6083
6084    #[tokio::test]
6085    async fn merge_note_dry_run_leaves_notes_unchanged() {
6086        let rt = rt();
6087        let tok = NamespaceToken::local();
6088        let into = rt
6089            .create_note(
6090                &tok,
6091                "observation",
6092                None,
6093                "Into content",
6094                None,
6095                None,
6096                vec![],
6097            )
6098            .await
6099            .unwrap();
6100        let from = rt
6101            .create_note(
6102                &tok,
6103                "observation",
6104                None,
6105                "From content",
6106                None,
6107                None,
6108                vec![],
6109            )
6110            .await
6111            .unwrap();
6112        let into_id = into.id;
6113        let from_id = from.id;
6114
6115        let summary = rt
6116            .merge_note_with_reason(
6117                &tok,
6118                into_id,
6119                from_id,
6120                EntityDedupMergePolicy::PreferInto,
6121                ContentMergeStrategy::Append,
6122                true,
6123                None,
6124            )
6125            .await
6126            .unwrap();
6127
6128        assert!(summary.dry_run);
6129
6130        let store = rt.notes(&tok).unwrap();
6131        let into_after = store.get_note(into_id).await.unwrap().unwrap();
6132        let from_after = store.get_note(from_id).await.unwrap().unwrap();
6133        assert_eq!(
6134            into_after.content, "Into content",
6135            "dry_run must not mutate into-note"
6136        );
6137        assert_eq!(
6138            from_after.content, "From content",
6139            "dry_run must not mutate from-note"
6140        );
6141
6142        let events = rt
6143            .events(&tok)
6144            .unwrap()
6145            .query_events(
6146                khive_storage::EventFilter {
6147                    kinds: vec![EventKind::NoteMerged],
6148                    ..Default::default()
6149                },
6150                khive_storage::types::PageRequest {
6151                    offset: 0,
6152                    limit: 10,
6153                },
6154            )
6155            .await
6156            .unwrap();
6157        assert!(
6158            events.items.is_empty(),
6159            "dry_run=true must not append a NoteMerged event"
6160        );
6161    }
6162
6163    // Merging two nameless notes with no embedding model configured: a raw SQL FTS
6164    // INSERT binding &merged_name directly would store SQL NULL for a nameless
6165    // note, while Fts5TextSearch::upsert_document stores an empty string:
6166    // note_fts_scalars must keep the round-trip field-identical.
6167    #[tokio::test]
6168    async fn merge_nameless_notes_fts_document_is_parity_correct() {
6169        use khive_storage::types::TextSearchRequest;
6170
6171        let rt = rt(); // in-memory runtime — no embedding model configured
6172        let tok = NamespaceToken::local();
6173
6174        let into = rt
6175            .create_note(
6176                &tok,
6177                "observation",
6178                None,
6179                "intosentinelzxq body",
6180                None,
6181                Some(serde_json::json!({"src": "into"})),
6182                vec![],
6183            )
6184            .await
6185            .expect("create into-note");
6186        let from = rt
6187            .create_note(
6188                &tok,
6189                "observation",
6190                None,
6191                "fromsentinelzxq body",
6192                None,
6193                None,
6194                vec![],
6195            )
6196            .await
6197            .expect("create from-note");
6198
6199        let into_id = into.id;
6200        let from_id = from.id;
6201
6202        rt.merge_note_with_reason(
6203            &tok,
6204            into_id,
6205            from_id,
6206            EntityDedupMergePolicy::PreferInto,
6207            ContentMergeStrategy::Append,
6208            false,
6209            None,
6210        )
6211        .await
6212        .expect("merge_note must succeed");
6213
6214        let note_store = rt.notes(&tok).expect("note store");
6215        let merged_note = note_store
6216            .get_note(into_id)
6217            .await
6218            .expect("get_note")
6219            .expect("merged note must exist");
6220
6221        let expected = note_fts_document(&merged_note);
6222
6223        let fts = rt.text_for_notes(&tok).expect("FTS store");
6224        let stored = fts
6225            .get_document("local", into_id)
6226            .await
6227            .expect("get_document must not error")
6228            .expect("FTS document must exist after merge");
6229
6230        assert_eq!(stored.subject_id, expected.subject_id, "subject_id");
6231        assert_eq!(
6232            stored.title, expected.title,
6233            "title (None for nameless note)"
6234        );
6235        assert_eq!(stored.body, expected.body, "body");
6236        assert_eq!(stored.namespace, expected.namespace, "namespace");
6237        assert_eq!(stored.kind, expected.kind, "kind");
6238
6239        assert!(
6240            stored.title.is_none(),
6241            "nameless merged note must have title=None in FTS (was NULL before fix)"
6242        );
6243
6244        // The merged note must be searchable by a unique token from the into-note body.
6245        let hits = fts
6246            .search(TextSearchRequest {
6247                query: "intosentinelzxq".to_string(),
6248                mode: khive_storage::types::TextQueryMode::Plain,
6249                filter: None,
6250                top_k: 10,
6251                snippet_chars: 0,
6252            })
6253            .await
6254            .expect("search");
6255        assert!(
6256            hits.iter().any(|h| h.subject_id == into_id),
6257            "merged note must be searchable by into-note content"
6258        );
6259    }
6260
6261    #[tokio::test]
6262    async fn update_edge_updates_properties() {
6263        use khive_storage::EdgeRelation;
6264        let rt = rt();
6265        let tok = NamespaceToken::local();
6266        let a = rt
6267            .create_entity(&tok, "concept", None, "A", None, None, vec![])
6268            .await
6269            .unwrap();
6270        let b = rt
6271            .create_entity(&tok, "concept", None, "B", None, None, vec![])
6272            .await
6273            .unwrap();
6274        let edge = rt
6275            .link(&tok, a.id, b.id, EdgeRelation::Extends, 0.5, None)
6276            .await
6277            .unwrap();
6278        let edge_id: Uuid = edge.id.into();
6279
6280        let updated = rt
6281            .update_edge(
6282                &tok,
6283                edge_id,
6284                EdgePatch {
6285                    properties: Some(serde_json::json!({"source": "manual"})),
6286                    ..Default::default()
6287                },
6288            )
6289            .await
6290            .unwrap();
6291
6292        assert_eq!(updated.metadata.as_ref().unwrap()["source"], "manual");
6293        assert!((updated.weight - 0.5).abs() < 0.001, "weight unchanged");
6294    }
6295
6296    // Merge must not crash when both entities share a common third-party edge
6297    // (duplicate triple after rewire): a double-ON-CONFLICT INSERT would
6298    // otherwise raise a UNIQUE constraint error and abort mid-transaction.
6299    #[tokio::test]
6300    async fn merge_entity_survives_shared_edge_to_third_party() {
6301        use khive_storage::EdgeRelation;
6302        let rt = rt();
6303        let tok = NamespaceToken::local();
6304
6305        // A and B will be merged; shared is the common target. `extends` is used
6306        // since concept→concept is a valid endpoint combination.
6307        let a = rt
6308            .create_entity(&tok, "concept", None, "A", None, None, vec![])
6309            .await
6310            .unwrap();
6311        let b = rt
6312            .create_entity(&tok, "concept", None, "B", None, None, vec![])
6313            .await
6314            .unwrap();
6315        let shared = rt
6316            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6317            .await
6318            .unwrap();
6319
6320        // Both A and B extend the same shared concept — this creates a duplicate
6321        // triple (A/B → shared, extends) that triggers the crash on rewire.
6322        rt.link(&tok, a.id, shared.id, EdgeRelation::Extends, 1.0, None)
6323            .await
6324            .unwrap();
6325        rt.link(&tok, b.id, shared.id, EdgeRelation::Extends, 1.0, None)
6326            .await
6327            .unwrap();
6328
6329        let summary = rt
6330            .merge_entity_with_reason(
6331                &tok,
6332                a.id,
6333                b.id,
6334                crate::EntityDedupMergePolicy::PreferInto,
6335                ContentMergeStrategy::Append,
6336                false,
6337                None,
6338            )
6339            .await
6340            .expect(
6341                "C1: merge must succeed even when both entities share an edge to a third party",
6342            );
6343
6344        assert_eq!(summary.kept_id, a.id);
6345        assert_eq!(summary.removed_id, b.id);
6346        // A already had the Extends edge to shared; rewiring B->shared onto it
6347        // hits the natural-key conflict arm, which drops the incoming (B-side)
6348        // duplicate rather than erroring or touching A's surviving row (ADR-039
6349        // `ON CONFLICT ... DO NOTHING`). The invariant checked below is that
6350        // exactly one live edge A->shared remains.
6351        let a_edges = rt
6352            .list_edges(
6353                &tok,
6354                crate::EdgeListFilter {
6355                    source_id: Some(a.id),
6356                    target_id: Some(shared.id),
6357                    relations: vec![EdgeRelation::Extends],
6358                    ..Default::default()
6359                },
6360                10,
6361                0,
6362            )
6363            .await
6364            .unwrap();
6365        assert_eq!(
6366            a_edges.len(),
6367            1,
6368            "C1: exactly one live A→shared Extends edge must exist after merge; got: {a_edges:?}"
6369        );
6370
6371        // get_entity filters deleted_at IS NULL, so a tombstoned entity returns None.
6372        let b_after = rt.entities(&tok).unwrap().get_entity(b.id).await.unwrap();
6373        assert!(
6374            b_after.is_none(),
6375            "C3: from_entity must be tombstoned (get_entity returns None for deleted) after merge; got: {b_after:?}"
6376        );
6377    }
6378
6379    // ADR-039 conflict-arm regression (#1191): on a symmetric-edge merge collision,
6380    // the surviving row's own weight/metadata must never be overwritten with the
6381    // incoming (dropped) duplicate's values.
6382    #[tokio::test]
6383    async fn merge_entity_symmetric_conflict_preserves_survivor_fields() {
6384        use khive_storage::EdgeRelation;
6385        let rt = rt();
6386        let tok = NamespaceToken::local();
6387
6388        let a = rt
6389            .create_entity(&tok, "concept", None, "A", None, None, vec![])
6390            .await
6391            .unwrap();
6392        let b = rt
6393            .create_entity(&tok, "concept", None, "B", None, None, vec![])
6394            .await
6395            .unwrap();
6396        let shared = rt
6397            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6398            .await
6399            .unwrap();
6400
6401        let survivor_edge = rt
6402            .link(
6403                &tok,
6404                a.id,
6405                shared.id,
6406                EdgeRelation::Extends,
6407                1.0,
6408                Some(serde_json::json!({"source": "survivor"})),
6409            )
6410            .await
6411            .unwrap();
6412        rt.link(
6413            &tok,
6414            b.id,
6415            shared.id,
6416            EdgeRelation::Extends,
6417            0.3,
6418            Some(serde_json::json!({"source": "loser"})),
6419        )
6420        .await
6421        .unwrap();
6422
6423        rt.merge_entity_with_reason(
6424            &tok,
6425            a.id,
6426            b.id,
6427            crate::EntityDedupMergePolicy::PreferInto,
6428            ContentMergeStrategy::Append,
6429            false,
6430            None,
6431        )
6432        .await
6433        .expect("merge must succeed across the symmetric-edge collision");
6434
6435        let after = rt
6436            .get_edge(&tok, survivor_edge.id.into())
6437            .await
6438            .unwrap()
6439            .expect("survivor edge must still exist after merge");
6440        assert!(
6441            (after.weight - 1.0).abs() < 0.001,
6442            "survivor weight must be untouched by the dropped duplicate; got {}",
6443            after.weight
6444        );
6445        assert_eq!(
6446            after.metadata.as_ref().unwrap()["source"],
6447            "survivor",
6448            "survivor metadata must be untouched by the dropped duplicate; got {:?}",
6449            after.metadata
6450        );
6451    }
6452
6453    // ADR-039 conflict-arm regression (#1191): a soft-deleted survivor row must
6454    // stay soft-deleted after a merge collision, never resurrected.
6455    #[tokio::test]
6456    async fn merge_entity_symmetric_conflict_does_not_resurrect_soft_deleted_survivor() {
6457        use khive_storage::EdgeRelation;
6458        let rt = rt();
6459        let tok = NamespaceToken::local();
6460
6461        let a = rt
6462            .create_entity(&tok, "concept", None, "A", None, None, vec![])
6463            .await
6464            .unwrap();
6465        let b = rt
6466            .create_entity(&tok, "concept", None, "B", None, None, vec![])
6467            .await
6468            .unwrap();
6469        let shared = rt
6470            .create_entity(&tok, "concept", None, "Shared", None, None, vec![])
6471            .await
6472            .unwrap();
6473
6474        let survivor_edge = rt
6475            .link(&tok, a.id, shared.id, EdgeRelation::Extends, 1.0, None)
6476            .await
6477            .unwrap();
6478        rt.delete_edge(&tok, survivor_edge.id.into(), false)
6479            .await
6480            .unwrap();
6481        rt.link(&tok, b.id, shared.id, EdgeRelation::Extends, 0.5, None)
6482            .await
6483            .unwrap();
6484
6485        rt.merge_entity_with_reason(
6486            &tok,
6487            a.id,
6488            b.id,
6489            crate::EntityDedupMergePolicy::PreferInto,
6490            ContentMergeStrategy::Append,
6491            false,
6492            None,
6493        )
6494        .await
6495        .expect("merge must succeed even when the surviving edge is soft-deleted");
6496
6497        let after = rt
6498            .get_edge_including_deleted(&tok, survivor_edge.id.into())
6499            .await
6500            .unwrap()
6501            .expect("survivor edge row must still exist after merge");
6502        assert!(
6503            after.deleted_at.is_some(),
6504            "soft-deleted survivor must stay soft-deleted after merge collision; got: {after:?}"
6505        );
6506    }
6507
6508    // merge_entity at the runtime level must reject cross-kind merges: without this
6509    // guard, a direct runtime caller could merge concept+project, silently
6510    // tombstoning the source entity, even though the pack handler also checks it.
6511    #[tokio::test]
6512    async fn merge_entity_cross_kind_rejected_at_runtime() {
6513        let rt = rt();
6514        let tok = NamespaceToken::local();
6515
6516        let concept = rt
6517            .create_entity(&tok, "concept", None, "H2Concept", None, None, vec![])
6518            .await
6519            .unwrap();
6520        let project = rt
6521            .create_entity(&tok, "project", None, "H2Project", None, None, vec![])
6522            .await
6523            .unwrap();
6524
6525        let err = rt
6526            .merge_entity_with_reason(
6527                &tok,
6528                concept.id,
6529                project.id,
6530                crate::EntityDedupMergePolicy::PreferInto,
6531                ContentMergeStrategy::Append,
6532                false,
6533                None,
6534            )
6535            .await
6536            .expect_err("H2: cross-kind merge must be rejected by runtime");
6537        assert!(
6538            matches!(err, crate::RuntimeError::InvalidInput(_)),
6539            "H2: expected InvalidInput, got: {err:?}"
6540        );
6541
6542        let concept_after = rt.get_entity(&tok, concept.id).await;
6543        let project_after = rt.get_entity(&tok, project.id).await;
6544        assert!(
6545            concept_after.is_ok(),
6546            "H2: concept must remain live after rejected merge; got: {concept_after:?}"
6547        );
6548        assert!(
6549            project_after.is_ok(),
6550            "H2: project must remain live after rejected merge; got: {project_after:?}"
6551        );
6552    }
6553
6554    // Same-kind merge must succeed.
6555    #[tokio::test]
6556    async fn merge_entity_same_kind_succeeds() {
6557        let rt = rt();
6558        let tok = NamespaceToken::local();
6559
6560        let c1 = rt
6561            .create_entity(&tok, "concept", None, "Concept1", None, None, vec![])
6562            .await
6563            .unwrap();
6564        let c2 = rt
6565            .create_entity(&tok, "concept", None, "Concept2", None, None, vec![])
6566            .await
6567            .unwrap();
6568
6569        let summary = rt
6570            .merge_entity_with_reason(
6571                &tok,
6572                c1.id,
6573                c2.id,
6574                crate::EntityDedupMergePolicy::PreferInto,
6575                ContentMergeStrategy::Append,
6576                false,
6577                None,
6578            )
6579            .await
6580            .expect("same-kind merge must succeed");
6581        assert_eq!(summary.kept_id, c1.id);
6582        assert_eq!(summary.removed_id, c2.id);
6583
6584        let c2_after = rt.entities(&tok).unwrap().get_entity(c2.id).await.unwrap();
6585        assert!(c2_after.is_none(), "from_entity must be tombstoned");
6586    }
6587
6588    #[tokio::test]
6589    async fn merge_entity_explicit_policy_rereads_names_before_commit() {
6590        let rt = rt();
6591        let tok = NamespaceToken::local();
6592
6593        let into = rt
6594            .create_entity(
6595                &tok,
6596                "concept",
6597                None,
6598                "Transactional Guard",
6599                None,
6600                None,
6601                vec![],
6602            )
6603            .await
6604            .unwrap();
6605        let from = rt
6606            .create_entity(
6607                &tok,
6608                "concept",
6609                None,
6610                "Transactional Guard",
6611                None,
6612                None,
6613                vec![],
6614            )
6615            .await
6616            .unwrap();
6617
6618        validate_entity_merge_floor(&into, &from)
6619            .expect("the handler's fast-path validation would initially pass");
6620        let renamed_into = rt
6621            .update_entity(
6622                &tok,
6623                into.id,
6624                EntityPatch {
6625                    name: Some("Unrelated Renamed Target".to_string()),
6626                    ..Default::default()
6627                },
6628            )
6629            .await
6630            .unwrap();
6631        let expected = validate_entity_merge_floor(&renamed_into, &from)
6632            .expect_err("the renamed transactional state must violate the name guard");
6633        let RuntimeError::Khive(expected) = entity_merge_guard_error(expected) else {
6634            unreachable!("merge guard errors are structured Khive errors")
6635        };
6636
6637        let err = rt
6638            .merge_entity_with_reason_and_force(
6639                &tok,
6640                into.id,
6641                from.id,
6642                EntityDedupMergePolicy::PreferInto,
6643                ContentMergeStrategy::Append,
6644                false,
6645                None,
6646                false,
6647            )
6648            .await
6649            .expect_err("the explicit non-forced path must validate its transactional reread");
6650        let RuntimeError::Khive(err) = err else {
6651            panic!("expected a structured merge-guard conflict, got {err:?}");
6652        };
6653        assert_eq!(err.kind(), expected.kind());
6654        assert_eq!(err.message(), expected.message());
6655        assert_eq!(err.code(), expected.code());
6656        assert_eq!(err.details(), expected.details());
6657        assert!(
6658            rt.get_entity(&tok, from.id).await.is_ok(),
6659            "a refused merge must leave the source entity live"
6660        );
6661    }
6662
6663    // Cross-namespace merge_note must be denied on either ID.
6664
6665    #[tokio::test]
6666    async fn merge_note_cross_namespace_either_id_returns_not_found() {
6667        use crate::error::RuntimeError;
6668        use crate::Namespace;
6669
6670        let rt = rt();
6671        let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6672        let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6673
6674        let into_a = rt
6675            .create_note(&ns_a, "observation", None, "Into A", None, None, vec![])
6676            .await
6677            .unwrap();
6678        let from_a = rt
6679            .create_note(&ns_a, "observation", None, "From A", None, None, vec![])
6680            .await
6681            .unwrap();
6682        let note_b = rt
6683            .create_note(&ns_b, "observation", None, "Note B", None, None, vec![])
6684            .await
6685            .unwrap();
6686
6687        // foreign into_id: note_b belongs to ns_b, caller token is ns_a
6688        let foreign_into = rt
6689            .merge_note_with_reason(
6690                &ns_a,
6691                note_b.id,
6692                from_a.id,
6693                EntityDedupMergePolicy::PreferInto,
6694                ContentMergeStrategy::Append,
6695                false,
6696                None,
6697            )
6698            .await;
6699        assert!(
6700            matches!(foreign_into, Err(RuntimeError::NotFound(_))),
6701            "foreign into_id must be denied before merge, got {foreign_into:?}"
6702        );
6703
6704        // foreign from_id: note_b belongs to ns_b, caller token is ns_a
6705        let foreign_from = rt
6706            .merge_note_with_reason(
6707                &ns_a,
6708                into_a.id,
6709                note_b.id,
6710                EntityDedupMergePolicy::PreferInto,
6711                ContentMergeStrategy::Append,
6712                false,
6713                None,
6714            )
6715            .await;
6716        assert!(
6717            matches!(foreign_from, Err(RuntimeError::NotFound(_))),
6718            "foreign from_id must be denied before merge, got {foreign_from:?}"
6719        );
6720    }
6721
6722    // Cross-namespace update now succeeds (shared-brain model).
6723
6724    #[tokio::test]
6725    async fn update_entity_cross_namespace_succeeds() {
6726        use crate::Namespace;
6727
6728        let rt = rt();
6729        let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6730        let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6731
6732        let entity = rt
6733            .create_entity(
6734                &ns_a,
6735                "concept",
6736                None,
6737                "Alpha",
6738                Some("original"),
6739                None,
6740                vec![],
6741            )
6742            .await
6743            .unwrap();
6744
6745        let result = rt
6746            .update_entity(
6747                &ns_b,
6748                entity.id,
6749                EntityPatch {
6750                    name: Some("Updated".into()),
6751                    ..Default::default()
6752                },
6753            )
6754            .await;
6755
6756        assert!(
6757            result.is_ok(),
6758            "cross-namespace update must succeed in shared-brain OSS; got {result:?}"
6759        );
6760        assert_eq!(result.unwrap().name, "Updated");
6761    }
6762
6763    // merge_entity still requires both entities to be in the same namespace as
6764    // the token's write namespace (enforced at the SQL transaction layer, not the
6765    // runtime layer).  This is a merge-semantic constraint, not tenant isolation.
6766    #[tokio::test]
6767    async fn merge_entity_cross_namespace_ids_fail_at_sql_layer() {
6768        use crate::Namespace;
6769
6770        let rt = rt();
6771        let ns_a = NamespaceToken::for_namespace(Namespace::parse("ns-a").unwrap());
6772        let ns_b = NamespaceToken::for_namespace(Namespace::parse("ns-b").unwrap());
6773
6774        let into_a = rt
6775            .create_entity(&ns_a, "concept", None, "Into A", None, None, vec![])
6776            .await
6777            .unwrap();
6778        let from_a = rt
6779            .create_entity(&ns_a, "concept", None, "From A", None, None, vec![])
6780            .await
6781            .unwrap();
6782        let foreign_b = rt
6783            .create_entity(&ns_b, "concept", None, "Foreign B", None, None, vec![])
6784            .await
6785            .unwrap();
6786
6787        // foreign into_id: SQL read_merge_entity checks ns matches token namespace.
6788        let foreign_into = rt
6789            .merge_entity_with_reason(
6790                &ns_a,
6791                foreign_b.id,
6792                from_a.id,
6793                EntityDedupMergePolicy::PreferInto,
6794                ContentMergeStrategy::Append,
6795                false,
6796                None,
6797            )
6798            .await;
6799        assert!(
6800            foreign_into.is_err(),
6801            "cross-namespace into_id must still fail at SQL layer; got {foreign_into:?}"
6802        );
6803
6804        // foreign from_id: same SQL constraint.
6805        let foreign_from = rt
6806            .merge_entity_with_reason(
6807                &ns_a,
6808                into_a.id,
6809                foreign_b.id,
6810                EntityDedupMergePolicy::PreferInto,
6811                ContentMergeStrategy::Append,
6812                false,
6813                None,
6814            )
6815            .await;
6816        assert!(
6817            foreign_from.is_err(),
6818            "cross-namespace from_id must still fail at SQL layer; got {foreign_from:?}"
6819        );
6820
6821        // All three entities survive the failed merges.
6822        assert!(rt.get_entity(&ns_a, into_a.id).await.is_ok());
6823        assert!(rt.get_entity(&ns_a, from_a.id).await.is_ok());
6824        assert!(rt.get_entity(&ns_b, foreign_b.id).await.is_ok());
6825    }
6826
6827    // Parity: entity_fts_document must produce the same body/title as the
6828    // create_entity and update_entity FTS write paths.
6829    #[test]
6830    fn entity_fts_document_with_description() {
6831        let mut entity = Entity::new("local", "concept", "MyEntity");
6832        entity = entity.with_description("some description text");
6833        let doc = entity_fts_document(&entity);
6834        assert_eq!(doc.subject_id, entity.id);
6835        assert_eq!(doc.namespace, "local");
6836        assert_eq!(doc.title.as_deref(), Some("MyEntity"));
6837        assert_eq!(doc.body, "MyEntity some description text");
6838        assert_eq!(doc.kind, khive_types::SubstrateKind::Entity);
6839    }
6840
6841    #[test]
6842    fn entity_fts_document_without_description() {
6843        let entity = Entity::new("local", "concept", "NameOnly");
6844        let doc = entity_fts_document(&entity);
6845        assert_eq!(doc.title.as_deref(), Some("NameOnly"));
6846        assert_eq!(doc.body, "NameOnly");
6847    }
6848
6849    #[test]
6850    fn entity_fts_document_empty_description_uses_name_only() {
6851        let mut entity = Entity::new("local", "concept", "TitleOnly");
6852        entity = entity.with_description("");
6853        let doc = entity_fts_document(&entity);
6854        assert_eq!(
6855            doc.body, "TitleOnly",
6856            "empty description must not be appended"
6857        );
6858    }
6859
6860    // Cross-path equality: an entity created through the runtime (operations.rs
6861    // create_entity path) must produce a stored FTS document field-identical to
6862    // entity_fts_document() called on the same Entity.
6863    #[tokio::test]
6864    async fn entity_fts_document_matches_runtime_create_path() {
6865        let rt = rt();
6866        let tok = NamespaceToken::local();
6867
6868        let entity = rt
6869            .create_entity(
6870                &tok,
6871                "concept",
6872                None,
6873                "CrossPathTitle",
6874                Some("cross path description body"),
6875                Some(serde_json::json!({"key": "val"})),
6876                vec!["tag1".to_string()],
6877            )
6878            .await
6879            .expect("create_entity");
6880
6881        let fts = rt.text(&tok).expect("FTS store");
6882        let stored = fts
6883            .get_document("local", entity.id)
6884            .await
6885            .expect("get_document")
6886            .expect("document must exist after create_entity");
6887
6888        let expected = entity_fts_document(&entity);
6889
6890        assert_eq!(stored.subject_id, expected.subject_id, "subject_id");
6891        assert_eq!(stored.kind, expected.kind, "kind");
6892        assert_eq!(stored.title, expected.title, "title");
6893        assert_eq!(stored.body, expected.body, "body");
6894        assert_eq!(stored.namespace, expected.namespace, "namespace");
6895    }
6896
6897    // Cross-path equality: update_entity must produce a stored FTS document
6898    // field-identical to entity_fts_document() on the updated Entity.
6899    #[tokio::test]
6900    async fn entity_fts_document_matches_runtime_update_path() {
6901        let rt = rt();
6902        let tok = NamespaceToken::local();
6903
6904        let entity = rt
6905            .create_entity(
6906                &tok,
6907                "concept",
6908                None,
6909                "OldName",
6910                Some("old desc"),
6911                None,
6912                vec![],
6913            )
6914            .await
6915            .expect("create_entity");
6916
6917        let updated = rt
6918            .update_entity(
6919                &tok,
6920                entity.id,
6921                EntityPatch {
6922                    name: Some("NewName".to_string()),
6923                    description: Some(Some("new desc".to_string())),
6924                    ..Default::default()
6925                },
6926            )
6927            .await
6928            .expect("update_entity");
6929
6930        let fts = rt.text(&tok).expect("FTS store");
6931        let stored = fts
6932            .get_document("local", updated.id)
6933            .await
6934            .expect("get_document")
6935            .expect("document must exist after update_entity");
6936
6937        let expected = entity_fts_document(&updated);
6938
6939        assert_eq!(stored.title, expected.title, "title after update");
6940        assert_eq!(stored.body, expected.body, "body after update");
6941    }
6942
6943    // Verify that merge_entity / merge_note delete from_id vectors from ALL
6944    // registered model vec tables, not just the default-model table. Uses the
6945    // same ConstVecProvider/ConstVecService pattern as operations.rs so no
6946    // real model files are required.
6947
6948    struct MergeTestVecService {
6949        dims: usize,
6950    }
6951
6952    #[async_trait::async_trait]
6953    impl lattice_embed::EmbeddingService for MergeTestVecService {
6954        async fn embed(
6955            &self,
6956            texts: &[String],
6957            _model: lattice_embed::EmbeddingModel,
6958        ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
6959            Ok(texts.iter().map(|_| vec![1.0_f32; self.dims]).collect())
6960        }
6961
6962        fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
6963            true
6964        }
6965
6966        fn name(&self) -> &'static str {
6967            "merge-test-const-vec"
6968        }
6969    }
6970
6971    struct MergeTestVecProvider {
6972        provider_name: String,
6973        dims: usize,
6974    }
6975
6976    impl MergeTestVecProvider {
6977        fn new(name: &str, dims: usize) -> Self {
6978            Self {
6979                provider_name: name.to_owned(),
6980                dims,
6981            }
6982        }
6983    }
6984
6985    #[async_trait::async_trait]
6986    impl crate::embedder_registry::EmbedderProvider for MergeTestVecProvider {
6987        fn name(&self) -> &str {
6988            &self.provider_name
6989        }
6990
6991        fn dimensions(&self) -> usize {
6992            self.dims
6993        }
6994
6995        async fn build(
6996            &self,
6997        ) -> crate::error::RuntimeResult<std::sync::Arc<dyn lattice_embed::EmbeddingService>>
6998        {
6999            Ok(std::sync::Arc::new(MergeTestVecService { dims: self.dims }))
7000        }
7001    }
7002
7003    #[tokio::test]
7004    async fn entity_reindex_with_captured_merge_plan_excludes_late_model() {
7005        const DIMS: usize = 4;
7006        const PLANNED: &str = "merge-entity-plan-existing";
7007        const LATE: &str = "merge-entity-plan-late";
7008        let rt = KhiveRuntime::memory().unwrap();
7009        let ns = crate::Namespace::parse("merge-entity-plan-snapshot").unwrap();
7010        let tok = NamespaceToken::for_namespace(ns);
7011        let entity = rt
7012            .create_entity(
7013                &tok,
7014                "concept",
7015                None,
7016                "CapturedEntityPlan",
7017                Some("full source remains indexed"),
7018                None,
7019                vec![],
7020            )
7021            .await
7022            .expect("create entity before registering embedders");
7023
7024        rt.register_embedder(MergeTestVecProvider::new(PLANNED, DIMS));
7025        let embedding_plan = EmbeddingModelPlan::capture(&rt);
7026        rt.register_embedder(MergeTestVecProvider::new(LATE, DIMS));
7027
7028        rt.reindex_entity_with_plan(&tok, &entity, &embedding_plan)
7029            .await
7030            .expect("reindex entity with captured merge plan");
7031
7032        assert_eq!(embedding_plan.model_names().len(), 1);
7033        assert_eq!(embedding_plan.model_names()[0].as_str(), PLANNED);
7034        assert_eq!(
7035            rt.vectors_for_model(&tok, PLANNED)
7036                .unwrap()
7037                .count()
7038                .await
7039                .unwrap(),
7040            1
7041        );
7042        assert_eq!(
7043            rt.vectors_for_model(&tok, LATE)
7044                .unwrap()
7045                .count()
7046                .await
7047                .unwrap(),
7048            0,
7049            "a provider registered after plan capture must not join survivor reindex"
7050        );
7051    }
7052
7053    #[tokio::test]
7054    async fn note_reindex_with_captured_merge_plan_excludes_late_model() {
7055        const DIMS: usize = 4;
7056        const PLANNED: &str = "merge-note-plan-existing";
7057        const LATE: &str = "merge-note-plan-late";
7058        let rt = KhiveRuntime::memory().unwrap();
7059        let ns = crate::Namespace::parse("merge-note-plan-snapshot").unwrap();
7060        let tok = NamespaceToken::for_namespace(ns);
7061        let note = rt
7062            .create_note(
7063                &tok,
7064                "observation",
7065                None,
7066                "full note source remains indexed",
7067                None,
7068                None,
7069                vec![],
7070            )
7071            .await
7072            .expect("create note before registering embedders");
7073
7074        rt.register_embedder(MergeTestVecProvider::new(PLANNED, DIMS));
7075        let embedding_plan = EmbeddingModelPlan::capture(&rt);
7076        rt.register_embedder(MergeTestVecProvider::new(LATE, DIMS));
7077
7078        rt.reindex_note_with_plan(&tok, &note, &embedding_plan)
7079            .await
7080            .expect("reindex note with captured merge plan");
7081
7082        assert_eq!(embedding_plan.model_names().len(), 1);
7083        assert_eq!(embedding_plan.model_names()[0].as_str(), PLANNED);
7084        assert_eq!(
7085            rt.vectors_for_model(&tok, PLANNED)
7086                .unwrap()
7087                .count()
7088                .await
7089                .unwrap(),
7090            1
7091        );
7092        assert_eq!(
7093            rt.vectors_for_model(&tok, LATE)
7094                .unwrap()
7095                .count()
7096                .await
7097                .unwrap(),
7098            0,
7099            "a provider registered after plan capture must not join survivor reindex"
7100        );
7101    }
7102
7103    /// merge_entity must delete from_id vectors from ALL registered model tables.
7104    ///
7105    /// Two custom embedders ("merge-vec-a", "merge-vec-b") are registered.  Both
7106    /// entities are embedded so each has a row in both model tables.  After merge,
7107    /// from_id must have zero surviving rows in either table.
7108    #[tokio::test]
7109    async fn merge_entity_clears_vectors_from_all_registered_models() {
7110        const DIMS: usize = 4;
7111        let rt = KhiveRuntime::memory().unwrap();
7112        rt.register_embedder(MergeTestVecProvider::new("merge-vec-a", DIMS));
7113        rt.register_embedder(MergeTestVecProvider::new("merge-vec-b", DIMS));
7114
7115        let ns_str = "merge-entity-vec-cleanup";
7116        let ns = crate::Namespace::parse(ns_str).unwrap();
7117        let tok = NamespaceToken::for_namespace(ns);
7118
7119        let into_e = rt
7120            .create_entity(
7121                &tok,
7122                "concept",
7123                None,
7124                "IntoVecEntity",
7125                Some("desc a"),
7126                None,
7127                vec![],
7128            )
7129            .await
7130            .expect("create into");
7131        let from_e = rt
7132            .create_entity(
7133                &tok,
7134                "concept",
7135                None,
7136                "FromVecEntity",
7137                Some("desc b"),
7138                None,
7139                vec![],
7140            )
7141            .await
7142            .expect("create from");
7143
7144        // Confirm both entities have vectors in both model tables before merge.
7145        let vs_a = rt.vectors_for_model(&tok, "merge-vec-a").unwrap();
7146        let vs_b = rt.vectors_for_model(&tok, "merge-vec-b").unwrap();
7147        use khive_storage::types::VectorSearchRequest;
7148        let query = vec![1.0_f32; DIMS];
7149        let pre_a = vs_a
7150            .search(VectorSearchRequest {
7151                query_vectors: vec![query.clone()],
7152                top_k: 100,
7153                namespace: Some(ns_str.to_string()),
7154                kind: Some(khive_types::SubstrateKind::Entity),
7155                embedding_model: Some("merge-vec-a".to_string()),
7156                filter: None,
7157                backend_hints: None,
7158            })
7159            .await
7160            .unwrap();
7161        assert!(
7162            pre_a.iter().any(|h| h.subject_id == into_e.id)
7163                && pre_a.iter().any(|h| h.subject_id == from_e.id),
7164            "both entities must be in model-a before merge; got {pre_a:?}"
7165        );
7166
7167        // model-b must ALSO hold both entities pre-merge, else the post-merge
7168        // model-b emptiness check below is vacuous (nothing to delete).
7169        let pre_b = vs_b
7170            .search(VectorSearchRequest {
7171                query_vectors: vec![query.clone()],
7172                top_k: 100,
7173                namespace: Some(ns_str.to_string()),
7174                kind: Some(khive_types::SubstrateKind::Entity),
7175                embedding_model: Some("merge-vec-b".to_string()),
7176                filter: None,
7177                backend_hints: None,
7178            })
7179            .await
7180            .unwrap();
7181        assert!(
7182            pre_b.iter().any(|h| h.subject_id == into_e.id)
7183                && pre_b.iter().any(|h| h.subject_id == from_e.id),
7184            "both entities must be in model-b before merge; got {pre_b:?}"
7185        );
7186
7187        rt.merge_entity_with_reason(
7188            &tok,
7189            into_e.id,
7190            from_e.id,
7191            EntityDedupMergePolicy::PreferInto,
7192            ContentMergeStrategy::Append,
7193            false,
7194            None,
7195        )
7196        .await
7197        .expect("merge_entity");
7198
7199        let post_a = vs_a
7200            .search(VectorSearchRequest {
7201                query_vectors: vec![query.clone()],
7202                top_k: 100,
7203                namespace: Some(ns_str.to_string()),
7204                kind: Some(khive_types::SubstrateKind::Entity),
7205                embedding_model: Some("merge-vec-a".to_string()),
7206                filter: None,
7207                backend_hints: None,
7208            })
7209            .await
7210            .unwrap();
7211        let from_ids_a: Vec<_> = post_a
7212            .iter()
7213            .filter(|h| h.subject_id == from_e.id)
7214            .collect();
7215        assert!(
7216            from_ids_a.is_empty(),
7217            "from_id must have no vectors in model-a after merge; got {from_ids_a:?}"
7218        );
7219
7220        let post_b = vs_b
7221            .search(VectorSearchRequest {
7222                query_vectors: vec![query],
7223                top_k: 100,
7224                namespace: Some(ns_str.to_string()),
7225                kind: Some(khive_types::SubstrateKind::Entity),
7226                embedding_model: Some("merge-vec-b".to_string()),
7227                filter: None,
7228                backend_hints: None,
7229            })
7230            .await
7231            .unwrap();
7232        let from_ids_b: Vec<_> = post_b
7233            .iter()
7234            .filter(|h| h.subject_id == from_e.id)
7235            .collect();
7236        assert!(
7237            from_ids_b.is_empty(),
7238            "from_id must have no vectors in model-b after merge; got {from_ids_b:?}"
7239        );
7240    }
7241
7242    /// merge_note must delete from_id vectors from ALL registered model tables.
7243    ///
7244    /// Two custom embedders ("merge-note-vec-a", "merge-note-vec-b") are registered.
7245    /// Both notes are embedded so each has a row in both model tables.  After merge,
7246    /// from_id must have zero surviving rows in either table.
7247    #[tokio::test]
7248    async fn merge_note_clears_vectors_from_all_registered_models() {
7249        const DIMS: usize = 4;
7250        let rt = KhiveRuntime::memory().unwrap();
7251        rt.register_embedder(MergeTestVecProvider::new("merge-note-vec-a", DIMS));
7252        rt.register_embedder(MergeTestVecProvider::new("merge-note-vec-b", DIMS));
7253
7254        let ns_str = "merge-note-vec-cleanup";
7255        let ns = crate::Namespace::parse(ns_str).unwrap();
7256        let tok = NamespaceToken::for_namespace(ns);
7257
7258        let into_n = rt
7259            .create_note(
7260                &tok,
7261                "observation",
7262                None,
7263                "IntoVecNote content",
7264                None,
7265                None,
7266                vec![],
7267            )
7268            .await
7269            .expect("create into note");
7270        let from_n = rt
7271            .create_note(
7272                &tok,
7273                "observation",
7274                None,
7275                "FromVecNote content",
7276                None,
7277                None,
7278                vec![],
7279            )
7280            .await
7281            .expect("create from note");
7282
7283        let vs_a = rt.vectors_for_model(&tok, "merge-note-vec-a").unwrap();
7284        let vs_b = rt.vectors_for_model(&tok, "merge-note-vec-b").unwrap();
7285        use khive_storage::types::VectorSearchRequest;
7286        let query = vec![1.0_f32; DIMS];
7287
7288        let pre_a = vs_a
7289            .search(VectorSearchRequest {
7290                query_vectors: vec![query.clone()],
7291                top_k: 100,
7292                namespace: Some(ns_str.to_string()),
7293                kind: Some(khive_types::SubstrateKind::Note),
7294                embedding_model: Some("merge-note-vec-a".to_string()),
7295                filter: None,
7296                backend_hints: None,
7297            })
7298            .await
7299            .unwrap();
7300        assert!(
7301            pre_a.iter().any(|h| h.subject_id == into_n.id)
7302                && pre_a.iter().any(|h| h.subject_id == from_n.id),
7303            "both notes must be in model-a before merge; got {pre_a:?}"
7304        );
7305
7306        // model-b must ALSO hold both notes pre-merge, else the post-merge
7307        // model-b emptiness check below is vacuous (nothing to delete).
7308        let pre_b = vs_b
7309            .search(VectorSearchRequest {
7310                query_vectors: vec![query.clone()],
7311                top_k: 100,
7312                namespace: Some(ns_str.to_string()),
7313                kind: Some(khive_types::SubstrateKind::Note),
7314                embedding_model: Some("merge-note-vec-b".to_string()),
7315                filter: None,
7316                backend_hints: None,
7317            })
7318            .await
7319            .unwrap();
7320        assert!(
7321            pre_b.iter().any(|h| h.subject_id == into_n.id)
7322                && pre_b.iter().any(|h| h.subject_id == from_n.id),
7323            "both notes must be in model-b before merge; got {pre_b:?}"
7324        );
7325
7326        rt.merge_note_with_reason(
7327            &tok,
7328            into_n.id,
7329            from_n.id,
7330            EntityDedupMergePolicy::PreferInto,
7331            ContentMergeStrategy::PreferInto,
7332            false,
7333            None,
7334        )
7335        .await
7336        .expect("merge_note");
7337
7338        let post_a = vs_a
7339            .search(VectorSearchRequest {
7340                query_vectors: vec![query.clone()],
7341                top_k: 100,
7342                namespace: Some(ns_str.to_string()),
7343                kind: Some(khive_types::SubstrateKind::Note),
7344                embedding_model: Some("merge-note-vec-a".to_string()),
7345                filter: None,
7346                backend_hints: None,
7347            })
7348            .await
7349            .unwrap();
7350        let from_ids_a: Vec<_> = post_a
7351            .iter()
7352            .filter(|h| h.subject_id == from_n.id)
7353            .collect();
7354        assert!(
7355            from_ids_a.is_empty(),
7356            "from_id must have no vectors in model-a after merge; got {from_ids_a:?}"
7357        );
7358
7359        let post_b = vs_b
7360            .search(VectorSearchRequest {
7361                query_vectors: vec![query],
7362                top_k: 100,
7363                namespace: Some(ns_str.to_string()),
7364                kind: Some(khive_types::SubstrateKind::Note),
7365                embedding_model: Some("merge-note-vec-b".to_string()),
7366                filter: None,
7367                backend_hints: None,
7368            })
7369            .await
7370            .unwrap();
7371        let from_ids_b: Vec<_> = post_b
7372            .iter()
7373            .filter(|h| h.subject_id == from_n.id)
7374            .collect();
7375        assert!(
7376            from_ids_b.is_empty(),
7377            "from_id must have no vectors in model-b after merge; got {from_ids_b:?}"
7378        );
7379    }
7380
7381    // Cross-path equality: merge_entity must produce a stored FTS document for
7382    // the kept entity that is field-identical to entity_fts_document().
7383    #[tokio::test]
7384    async fn entity_fts_document_matches_runtime_merge_path() {
7385        let rt = rt();
7386        let tok = NamespaceToken::local();
7387
7388        let into_e = rt
7389            .create_entity(
7390                &tok,
7391                "concept",
7392                None,
7393                "IntoEntity",
7394                Some("into desc"),
7395                None,
7396                vec![],
7397            )
7398            .await
7399            .expect("create into");
7400        let from_e = rt
7401            .create_entity(
7402                &tok,
7403                "concept",
7404                None,
7405                "FromEntity",
7406                Some("from desc"),
7407                None,
7408                vec![],
7409            )
7410            .await
7411            .expect("create from");
7412
7413        let summary = rt
7414            .merge_entity_with_reason(
7415                &tok,
7416                into_e.id,
7417                from_e.id,
7418                EntityDedupMergePolicy::PreferInto,
7419                ContentMergeStrategy::Append,
7420                false,
7421                None,
7422            )
7423            .await
7424            .expect("merge_entity");
7425
7426        let kept = rt
7427            .get_entity(&tok, summary.kept_id)
7428            .await
7429            .expect("get kept");
7430
7431        let fts = rt.text(&tok).expect("FTS store");
7432        let stored = fts
7433            .get_document("local", kept.id)
7434            .await
7435            .expect("get_document")
7436            .expect("FTS document must exist for kept entity after merge");
7437
7438        let expected = entity_fts_document(&kept);
7439
7440        assert_eq!(stored.title, expected.title, "title after merge");
7441        assert_eq!(stored.body, expected.body, "body after merge");
7442    }
7443}