geographdb-core 0.1.0

Geometric graph database core - 3D spatial indexing for code analysis
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

# geographdb-core

3D spatial indexing and graph-storage primitives for CFG and graph analysis.

This crate provides octree indexing, Morton ordering, sectioned storage, CFG block storage, and graph algorithms for tools that model control-flow and graph structure geometrically.

## Features

- Octree spatial indexing for 3D points and bounding boxes
- Morton code ordering for cache-friendly spatial locality
- Sectioned storage for graph, symbol, and CFG records
- CFG-oriented storage and query helpers
- Graph algorithms including A*, SCC, dominance, loops, slicing, and topological ordering

## Code-Intelligence Use Case

Magellan stores control-flow blocks in 3D space:

- X = structural or dominance depth
- Y = loop nesting level
- Z = function or path grouping dimension

Tools can then query control-flow structure using geometric locality.

```rust
use geographdb_core::spatial::{BoundingBox, Octree};
use geographdb_core::storage::NodePoint;
use glam::Vec3;

let bounds = BoundingBox::new(
    Vec3::new(0.0, 0.0, 0.0),
    Vec3::new(100.0, 100.0, 100.0),
);
let mut octree = Octree::new(bounds);

octree.insert(NodePoint { id: 1, x: 0.0, y: 0.0, z: 42.0 });
octree.insert(NodePoint { id: 2, x: 1.0, y: 0.0, z: 42.0 });
octree.insert(NodePoint { id: 3, x: 2.0, y: 1.0, z: 42.0 });

let nearby = octree.query_sphere(Vec3::new(1.0, 0.0, 42.0), 2.0);
assert_eq!(nearby.len(), 3);
```

## Installation

```toml
[dependencies]
geographdb-core = "0.1"
```

For local development with Magellan:

```toml
geographdb-core = { path = "../geographdb-core" }
```

## Scope

This crate contains the Rust core used for spatial CFG and graph storage. Language bindings and larger application crates are separate packages.

## Public API Areas

- `spatial`: `Octree`, `BoundingBox`, Morton encoding, and SIMD distance filtering.
- `storage`: sectioned `.geo` storage, sidecar path helpers, graph/CFG/symbol section adapters, and WAL records.
- `cfg_store`: high-level CFG block storage backed by spatial indexing.
- `algorithms`: graph algorithms for CFG analysis and path reasoning.

## Feature Flags

- `telemetry`: enables tracing and dashmap-backed instrumentation helpers.
- `debug-prints`: enables debug instrumentation points used during local investigation.

## Documentation

- [API.md](API.md) describes the public modules and common types.
- [MANUAL.md](MANUAL.md) covers local development, verification, and publishing.
- [CHANGELOG.md](CHANGELOG.md) records release changes.

## Verification

```bash
cargo check
cargo test
cargo publish --dry-run
cargo package --list
```

## License

GPL-3.0-only. See [LICENSE](LICENSE).