geographdb-core 0.3.1

# geographdb-core Manual

## Purpose

`geographdb-core` provides spatial indexing, sectioned `.geo` storage, CFG block storage, and graph algorithms. Magellan can use it through its optional `geometric-backend` feature.

## Repository Layout

- `src/spatial/` - octree indexing, Morton encoding, and distance filtering.
- `src/storage/` - sectioned storage, sidecar path helpers, graph/CFG/symbol adapters, and WAL records.
- `src/cfg_store.rs` - high-level CFG block store backed by the octree and storage manager.
- `src/algorithms/` - CFG and graph algorithms used by code-intelligence tools.
- `tests/` - integration and corruption-regression tests.
- `benches/` - Criterion benchmark entrypoint.

Ignored local-only content includes debug examples, Python binding experiments, `target/`, lockfiles, patch leftovers, and generated databases.

## Using The Crate

From crates.io:

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

For local Magellan development:

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

Magellan enables it through its optional `geometric-backend` feature.

## 4D Traversal

Use the 4D traversal API when graph analysis should respect both code-structure
position and temporal validity. This is useful for code-intelligence snapshots,
CFG evolution, and spatially constrained path reasoning.

```rust
use geographdb_core::{
    reachable_4d, GraphNode4D, SpatialRegion, TemporalEdge, TemporalWindow,
    TraversalContext4D,
};
use glam::Vec3;

let nodes = vec![
    GraphNode4D {
        id: 1,
        x: 0.0,
        y: 0.0,
        z: 42.0,
        begin_ts: 0,
        end_ts: 100,
        properties: Default::default(),
        successors: vec![TemporalEdge {
            dst: 2,
            weight: 1.0,
            begin_ts: 0,
            end_ts: 100,
        }],
    },
    GraphNode4D {
        id: 2,
        x: 1.0,
        y: 0.0,
        z: 42.0,
        begin_ts: 0,
        end_ts: 100,
        properties: Default::default(),
        successors: vec![],
    },
];

let ctx = TraversalContext4D {
    time_window: Some(TemporalWindow { start: 10, end: 20 }),
    spatial_region: Some(SpatialRegion::Sphere {
        center: Vec3::new(0.0, 0.0, 42.0),
        radius: 2.0,
    }),
    graph_weight: 1.0,
    spatial_weight: 0.0,
    temporal_weight: 0.0,
};

let reachable = reachable_4d(&nodes, 1, &ctx);
assert_eq!(reachable, vec![1, 2]);
```

The existing `CfgGraphNode` algorithms remain unchanged. Convert storage records
or CFG blocks into `GraphNode4D` when time-aware and space-aware analysis is
required. Use `GraphNode4D::properties` for JSON metadata that should be
projected by the 4D Cypher-like query layer, for example
`MATCH (a)-[:CONNECTS]->(b) RETURN a.name, b.name`.

## 4D Demo Scenarios

The crate ships runnable 4D graph demos: temporal dependencies, constrained
impact analysis, route adaptation, time-respecting delivery, signal propagation,
dynamic bottleneck resilience, orbit constellation, metamaterial design, and
protein conformation.

They double as executable documentation:

```bash
cargo run --example demo_4d_dependency_timeline
cargo run --example demo_4d_cypher_bottlenecks
cargo run --example demo_4d_cypher_impact_radius
cargo run --example demo_4d_cypher_match_filters
cargo run --example demo_4d_cypher_queries
cargo run --example demo_4d_cypher_disaster_response
cargo run --example demo_4d_cypher_signal_propagation
cargo run --example demo_4d_cypher_temporal_route
cargo run --example demo_4d_impact_radius
cargo run --example demo_4d_route_planning
cargo run --example demo_4d_signal_propagation
cargo run --example demo_4d_temporal_bottlenecks
cargo run --example demo_4d_temporal_delivery
cargo run --example demo_4d_orbit_constellation
cargo run --example demo_4d_metamaterial_design
cargo run --example demo_4d_protein_conformation
```

For machine-readable output:

```bash
cargo run --quiet --example demo_4d_dependency_timeline -- --json > dependency-timeline.json
cargo run --quiet --example demo_4d_cypher_bottlenecks -- --json > cypher-bottlenecks.json
cargo run --quiet --example demo_4d_cypher_impact_radius -- --json > cypher-impact-radius.json
cargo run --quiet --example demo_4d_cypher_match_filters -- --json > cypher-match-filters.json
cargo run --quiet --example demo_4d_cypher_queries -- --json > cypher-queries.json
cargo run --quiet --example demo_4d_cypher_signal_propagation -- --json > cypher-signal-propagation.json
cargo run --quiet --example demo_4d_cypher_temporal_route -- --json > cypher-temporal-route.json
cargo run --quiet --example demo_4d_impact_radius -- --json > impact-radius.json
cargo run --quiet --example demo_4d_route_planning -- --json > route-planning.json
cargo run --quiet --example demo_4d_signal_propagation -- --json > signal-propagation.json
cargo run --quiet --example demo_4d_temporal_bottlenecks -- --json > temporal-bottlenecks.json
cargo run --quiet --example demo_4d_temporal_delivery -- --json > temporal-delivery.json
cargo run --quiet --example demo_4d_orbit_constellation -- --json > orbit-constellation.json
```

Checked sample JSON outputs are kept in `examples/results/`.

Use them as templates for:

- Cypher-like pattern, property projection, and procedure queries over 4D graph
  data;
- dependency timelines where reachability, shortest paths, and SCCs change as
  edges appear or expire;
- impact-radius queries where topology alone over-reports affected nodes, but
  spatial and temporal filters narrow the answer;
- route planning where an A* path changes because part of the graph is only
  valid during an earlier time window.
- signal propagation where time-dependent Dijkstra computes earliest arrivals,
  unreachable nodes, and arrival frontiers from one source.
- bottleneck analysis where articulation points and bridges are critical in one
  time window and disappear after a temporary relay creates redundancy.
- temporal delivery where the best route depends on arrival time at each hop,
  not only on a static time-window filter.

## Feature Flags

- `default`: no optional telemetry dependencies.
- `telemetry`: enables tracing and dashmap-backed instrumentation helpers.
- `debug-prints`: enables local debug instrumentation points.

## Development Workflow

Run checks from the crate root:

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

Before committing, confirm the package list contains only public docs, source, tests, and benchmarks. It must not include Python binding artifacts, debug examples, generated databases, `target/`, `.orig`, or `.rej` files.

## Publishing

1. Confirm `Cargo.toml` has the intended version and `license = "GPL-3.0-only"`.
2. Run `cargo test`.
3. Run `cargo publish --dry-run`.
4. Tag the release after publishing succeeds.
5. Update Magellan to consume the crates.io version instead of the local path dependency.

## License

This crate is licensed under GPL-3.0-only. See `LICENSE`.