kglite 0.17.2

Pure-Rust embedded Cypher knowledge graph engine with in-memory, mmap, and disk storage, and agent-facing schema introspection
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302

//! Freshness of the persistent disk index bundles.
//!
//! A `property_index_*` / `global_index_*` bundle is an mmap snapshot: nothing
//! maintains it after the build, so the only sound thing it can say about a
//! graph that has moved is *nothing*. These cases pin `None` ("unknown, go
//! scan") rather than `Some(vec![])` ("proven empty") for every way a disk
//! graph can move under a bundle, and pin the query answer that a scan then
//! produces.
//!
//! Deep-scan 2026-09-07 items 2+3 (lane report F2/F3): before this, a
//! save+load armed the auto-built `title`/`nid` globals and every later
//! `name`/`title` lookup missed the rows added since, and a user
//! `create_index` was trusted as authoritative forever.

use crate::datatypes::{DataFrame, Value};
use crate::graph::session::execute::{execute_mut, execute_read, ExecuteOptions};
use crate::graph::DirGraph;
use std::collections::HashMap;
use tempfile::TempDir;

/// `Doc` rows as `(id, name, tag)`; `name` is the title column, so `n.name`
/// and `n.title` both resolve through the auto-built global `title` bundle.
fn add_docs(graph: &mut DirGraph, rows: &[(i64, &str, &str)]) {
    let frame = DataFrame::from_cypher_rows(
        vec!["id".to_string(), "name".to_string(), "tag".to_string()],
        rows.iter()
            .map(|(id, name, tag)| {
                vec![
                    Value::Int64(*id),
                    Value::String((*name).to_string()),
                    Value::String((*tag).to_string()),
                ]
            })
            .collect(),
    )
    .unwrap();
    crate::graph::mutation::maintain::add_nodes(
        graph,
        frame,
        "Doc".to_string(),
        "id".to_string(),
        Some("name".to_string()),
        None,
    )
    .unwrap();
}

fn run(graph: &mut DirGraph, query: &str) {
    let params = HashMap::new();
    let opts = ExecuteOptions::eager(&params);
    execute_mut(graph, query, &opts).unwrap_or_else(|e| panic!("{query}: {e}"));
}

fn rows(graph: &DirGraph, query: &str) -> usize {
    let params = HashMap::new();
    let opts = ExecuteOptions::eager(&params);
    execute_read(graph, query, &opts)
        .unwrap_or_else(|e| panic!("{query}: {e}"))
        .result
        .rows
        .len()
}

/// A published disk graph at `path` holding `rows`, live on the mapped
/// generation — the state `kglite.open(path)` reaches.
fn published_disk_graph(path: &std::path::Path, docs: &[(i64, &str, &str)]) -> DirGraph {
    let mut graph = DirGraph::new();
    if !docs.is_empty() {
        add_docs(&mut graph, docs);
    }
    graph.enable_disk_mode().unwrap();
    graph.save_disk(path.to_str().unwrap()).unwrap();
    graph
}

fn typed_lookup(graph: &DirGraph, property: &str, value: &str) -> Option<Vec<usize>> {
    graph
        .graph
        .as_disk()
        .expect("disk backend")
        .lookup_property_eq("Doc", property, value)
        .map(|hits| hits.into_iter().map(|idx| idx.index()).collect())
}

fn global_lookup(graph: &DirGraph, property: &str, value: &str) -> Option<Vec<usize>> {
    graph
        .graph
        .as_disk()
        .expect("disk backend")
        .lookup_global_eq(property, value)
        .map(|hits| hits.into_iter().map(|idx| idx.index()).collect())
}

/// F3, index level: a row created after the build is not in the bundle, so the
/// bundle cannot answer "no such row".
#[test]
fn a_creation_after_the_build_makes_the_typed_bundle_decline() {
    let dir = TempDir::new().unwrap();
    let mut graph = published_disk_graph(dir.path(), &[(1, "a", "c0"), (2, "b", "c1")]);
    let (_count, persistent) = graph.create_property_index_routed("Doc", "tag").unwrap();
    assert!(persistent, "a disk create_index builds the mmap bundle");
    assert_eq!(
        typed_lookup(&graph, "tag", "c1"),
        Some(vec![1]),
        "a bundle built over the current graph answers"
    );

    add_docs(&mut graph, &[(3, "c", "c1")]);

    assert_eq!(
        typed_lookup(&graph, "tag", "c1"),
        None,
        "the bundle no longer covers every row, so it must decline to the scan"
    );
    assert_eq!(
        rows(&graph, "MATCH (n:Doc) WHERE n.tag = 'c1' RETURN n.id"),
        2,
        "the scan finds both c1 rows"
    );
}

/// F3, via the matcher: a `SET` moves a row between buckets the bundle still
/// records under the old value.
#[test]
fn a_set_on_the_indexed_property_makes_the_typed_bundle_decline() {
    let dir = TempDir::new().unwrap();
    let mut graph = published_disk_graph(dir.path(), &[(1, "a", "c0"), (2, "b", "c1")]);
    graph.create_property_index_routed("Doc", "tag").unwrap();

    run(&mut graph, "MATCH (n:Doc) WHERE n.id = 1 SET n.tag = 'c1'");

    assert_eq!(
        typed_lookup(&graph, "tag", "c1"),
        None,
        "the row moved into 'c1' after the build"
    );
    assert_eq!(
        rows(&graph, "MATCH (n:Doc) WHERE n.tag = 'c1' RETURN n.id"),
        2
    );
    assert_eq!(
        rows(&graph, "MATCH (n:Doc) WHERE n.tag = 'c0' RETURN n.id"),
        0,
        "and the row it left is no longer under the old value"
    );
}

/// F2: every disk `save()` auto-builds the global `title` bundle, so a
/// save+load arms this on a graph whose owner never asked for an index.
#[test]
fn a_creation_after_a_load_makes_the_global_title_bundle_decline() {
    let dir = TempDir::new().unwrap();
    drop(published_disk_graph(dir.path(), &[]));
    let mut handle = crate::graph::io::file::load_file(dir.path().to_str().unwrap()).unwrap();
    let graph = crate::graph::handle::make_dir_graph_mut(&mut handle);

    add_docs(graph, &[(6, "nm_6", "c0"), (19, "nm_7", "c1")]);

    assert_eq!(
        global_lookup(graph, "title", "nm_7"),
        None,
        "the bundle was built over an empty graph"
    );
    assert_eq!(
        rows(graph, "MATCH (n:Doc) WHERE n.name = 'nm_7' RETURN n.id"),
        1
    );
    assert_eq!(
        rows(graph, "MATCH (n:Doc {name: 'nm_7'}) RETURN n.id"),
        1,
        "the map form routes through the same global bundle"
    );
    assert_eq!(
        rows(graph, "MATCH (n:Doc) WHERE n.title = 'nm_7' RETURN n.id"),
        1
    );
}

/// A `SET` of the title column after a load is the same defect through the
/// global bundle's other arm.
#[test]
fn a_title_set_after_a_load_makes_the_global_bundle_decline() {
    let dir = TempDir::new().unwrap();
    drop(published_disk_graph(
        dir.path(),
        &[(6, "nm_6", "c0"), (19, "nm_6", "c1")],
    ));
    let mut handle = crate::graph::io::file::load_file(dir.path().to_str().unwrap()).unwrap();
    let graph = crate::graph::handle::make_dir_graph_mut(&mut handle);

    run(graph, "MATCH (n:Doc) WHERE n.id = 19 SET n.name = 'nm_7'");

    assert_eq!(global_lookup(graph, "title", "nm_7"), None);
    assert_eq!(
        rows(graph, "MATCH (n:Doc) WHERE n.name = 'nm_7' RETURN n.id"),
        1
    );
}

/// Deletion must mark the bundle stale on its own. Relying on the tombstone
/// filter downstream would leave the *value* half of a delete+re-add — a slot
/// recycled under a different value — answered from the stale bundle.
#[test]
fn a_delete_and_re_add_under_a_new_value_makes_the_typed_bundle_decline() {
    let dir = TempDir::new().unwrap();
    let mut graph = published_disk_graph(dir.path(), &[(1, "a", "c0"), (2, "b", "c1")]);
    graph.create_property_index_routed("Doc", "tag").unwrap();

    run(&mut graph, "MATCH (n:Doc) WHERE n.id = 2 DETACH DELETE n");
    assert_eq!(
        typed_lookup(&graph, "tag", "c1"),
        None,
        "a deletion is a change the bundle does not carry"
    );

    add_docs(&mut graph, &[(4, "d", "c0")]);
    assert_eq!(
        rows(&graph, "MATCH (n:Doc) WHERE n.tag = 'c0' RETURN n.id"),
        2
    );
    assert_eq!(
        rows(&graph, "MATCH (n:Doc) WHERE n.tag = 'c1' RETURN n.id"),
        0
    );
}

/// `reindex()` is the documented repair verb, and on a disk graph it rebuilt
/// only the empty heap maps — a measured no-op (F2).
#[test]
fn reindex_rebuilds_the_disk_bundles() {
    let dir = TempDir::new().unwrap();
    let mut graph = published_disk_graph(dir.path(), &[(1, "a", "c0"), (2, "b", "c1")]);
    graph.create_property_index_routed("Doc", "tag").unwrap();
    add_docs(&mut graph, &[(3, "c", "c1")]);
    assert_eq!(typed_lookup(&graph, "tag", "c1"), None);

    graph.reindex();

    let hits = typed_lookup(&graph, "tag", "c1").expect("the rebuilt bundle answers again");
    assert_eq!(hits.len(), 2, "and it covers the row added since the build");
    assert_eq!(
        global_lookup(&graph, "title", "c").map(|hits| hits.len()),
        Some(1),
        "the global bundles are rebuilt too"
    );
}

/// A stale bundle must not cross a generation: the next process would open it
/// with no memory that it was stale.
#[test]
fn a_save_never_carries_a_stale_bundle_into_the_new_generation() {
    let source = TempDir::new().unwrap();
    let destination = TempDir::new().unwrap();
    let mut graph = published_disk_graph(source.path(), &[(1, "a", "c0"), (2, "b", "c1")]);
    graph.create_property_index_routed("Doc", "tag").unwrap();
    add_docs(&mut graph, &[(3, "c", "c1")]);

    let mut handle = std::sync::Arc::new(graph);
    crate::graph::io::file::save_graph(&mut handle, destination.path().to_str().unwrap()).unwrap();
    drop(handle);
    let reloaded = crate::graph::io::file::load_file(destination.path().to_str().unwrap()).unwrap();

    if let Some(hits) = typed_lookup(&reloaded, "tag", "c1") {
        assert_eq!(hits.len(), 2, "a carried bundle must be complete");
    }
    assert_eq!(
        rows(&reloaded, "MATCH (n:Doc) WHERE n.tag = 'c1' RETURN n.id"),
        2
    );
}

/// save → load → mutate → save → load: the generation carry seen twice, which
/// is what a long-running ingest server does.
#[test]
fn generation_carry_survives_a_second_save_and_load() {
    let dir = TempDir::new().unwrap();
    let path = dir.path().to_str().unwrap().to_string();
    drop(published_disk_graph(dir.path(), &[(1, "nm_1", "c0")]));

    let mut handle = crate::graph::io::file::load_file(&path).unwrap();
    add_docs(
        crate::graph::handle::make_dir_graph_mut(&mut handle),
        &[(2, "nm_2", "c1")],
    );
    crate::graph::io::file::save_graph(&mut handle, &path).unwrap();
    drop(handle);

    let reloaded = crate::graph::io::file::load_file(&path).unwrap();
    assert_eq!(
        global_lookup(&reloaded, "title", "nm_2").map(|hits| hits.len()),
        Some(1),
        "the save rebuilt the global title bundle over the final node set"
    );
    assert_eq!(
        rows(&reloaded, "MATCH (n:Doc) WHERE n.name = 'nm_2' RETURN n.id"),
        1
    );
    assert_eq!(
        rows(&reloaded, "MATCH (n:Doc) WHERE n.name = 'nm_1' RETURN n.id"),
        1
    );
}