zgraph-project_dump.txt

📦 Dumping from: C:\Workspaces\Zigadel\code\ZLibs\ZGraph
📤 Output: C:\Workspaces\Zigadel\code\ZLibs\ZGraph\project_dump.txt
📁 Max file size: 104857600 bytes
🚫 Ignore rules (in order):
  .git
  .github
  .zig-cache
  C:/Workspaces/Zigadel/code/ZLibs/ZGraph/project_dump.txt

🧱 Filtered Tree:
- .dpignore
- .gitignore
- build.zig
- build.zig.zon
- docs
  - docs/algorithms
  - docs/conversion_strategies.md
  - docs/file_specs
    - docs/file_specs/zgraph-spec.md
    - docs/file_specs/zgraphb-spec.md
  - docs/perf_tuning.md
  - docs/roadmap.md
  - docs/safety_and_threading.md
  - docs/storage_design.md
  - docs/zson_config.md
- LICENSE
- project_dump.txt
- README.md
- src
  - src/lib
    - src/lib/algorithms
      - src/lib/algorithms/flow
        - src/lib/algorithms/flow/edmonds_karp.zig
        - src/lib/algorithms/flow/flow.zig
        - src/lib/algorithms/flow/ford_fulkerson.zig
      - src/lib/algorithms/mst
        - src/lib/algorithms/mst/kruskal.zig
        - src/lib/algorithms/mst/mst.zig
        - src/lib/algorithms/mst/prim.zig
      - src/lib/algorithms/shortest_path
        - src/lib/algorithms/shortest_path/bellman_ford.zig
        - src/lib/algorithms/shortest_path/djikstra.zig
        - src/lib/algorithms/shortest_path/floyd_warshall.zig
        - src/lib/algorithms/shortest_path/shortest_path.zig
      - src/lib/algorithms/spectral
        - src/lib/algorithms/spectral/cheeger_inequality.zig
        - src/lib/algorithms/spectral/eigenvalues.zig
        - src/lib/algorithms/spectral/eigenvectors.zig
        - src/lib/algorithms/spectral/graph_fourier_transform.zig
        - src/lib/algorithms/spectral/laplacian_matrix.zig
        - src/lib/algorithms/spectral/pagerank_spectral.zig
        - src/lib/algorithms/spectral/spectral_clustering.zig
        - src/lib/algorithms/spectral/spectral.zig
      - src/lib/algorithms/traversal
        - src/lib/algorithms/traversal/bfs.zig
        - src/lib/algorithms/traversal/bidirectional_bfs.zig
        - src/lib/algorithms/traversal/connected_components.zig
        - src/lib/algorithms/traversal/dfs.zig
        - src/lib/algorithms/traversal/traversal.zig
    - src/lib/core
      - src/lib/core/edge.zig
      - src/lib/core/graph_storage.zig
      - src/lib/core/graph.zig
      - src/lib/core/node.zig
    - src/lib/data_structures
      - src/lib/data_structures/adjacency_list.zig
      - src/lib/data_structures/adjacency_matrix.zig
      - src/lib/data_structures/gpu
        - src/lib/data_structures/gpu/adjacency_matrix_vram.zig
        - src/lib/data_structures/gpu/compressed_sparse_column.zig
        - src/lib/data_structures/gpu/compressed_sparse_row.zig
        - src/lib/data_structures/gpu/gpu_graph.zig
      - src/lib/data_structures/incidence_matrix.zig
  - src/main.zig
  - src/root.zig
- ZGraph.MasterPlan.md
- ZGraph.Spec.md

📄 File Contents:

`.dpignore`: >>>

.git
.github
.zig-cache
<<<

`.gitignore`: >>>

.zig-cache/
zig-out/
.DS_Store
.env
<<<

`build.zig`: >>>

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // ---- Core module (reused everywhere) ------------------------------------
    const zgraph_root = b.createModule(.{
        .root_source_file = b.path("src/root.zig"),
        .target = target,
        .optimize = optimize,
    });

    // ---- Static library (installable) ---------------------------------------
    const lib = b.addLibrary(.{
        .name = "zgraph",
        .linkage = .static, // replacement for addStaticLibrary on 0.16
        .root_module = zgraph_root,
    });
    b.installArtifact(lib);

    // ---- CLI executable (installable + runnable) ----------------------------
    const exe = b.addExecutable(.{
        .name = "zgraph-cli",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
        // NOTE: no .target / .optimize here; they belong on the module
    });
    // Allow @import("zgraph_root") in src/main.zig
    exe.root_module.addImport("zgraph_root", zgraph_root);
    b.installArtifact(exe);

    // `zig build run`
    const run_step = b.step("run", "Run zgraph CLI");
    const run_cmd = b.addRunArtifact(exe);
    run_step.dependOn(&run_cmd.step);

    // ---- Unit tests (module tests) ------------------------------------------
    const unit_tests = b.addTest(.{
        .root_module = zgraph_root,
        // NOTE: no .target / .optimize here either
    });
    const run_unit = b.addRunArtifact(unit_tests);

    const test_step = b.step("test", "Run unit tests");
    test_step.dependOn(&run_unit.step);

    // ---- Integration tests (optional; skip if file missing) -----------------
    const integration_step = b.step("integration-test", "Run integration tests");
    const integration_path = "src/tests/integration/integration_tests.zig";

    const have_integration = blk: {
        _ = std.fs.cwd().statFile(integration_path) catch break :blk false;
        break :blk true;
    };

    if (have_integration) {
        const integration_tests = b.addTest(.{
            .root_module = b.createModule(.{
                .root_source_file = b.path(integration_path),
                .target = target,
                .optimize = optimize,
            }),
        });
        integration_tests.root_module.addImport("zgraph_root", zgraph_root);

        const run_integration = b.addRunArtifact(integration_tests);
        integration_step.dependOn(&run_integration.step);
    } else {
        // Replaced b.print(...) with std.log.info(...)
        std.log.info("note: integration tests not found at '{s}', skipping.", .{integration_path});
    }

    // ---- Aggregate: `zig build test-all` ------------------------------------
    const all_tests = b.step("test-all", "Run unit + integration tests");
    all_tests.dependOn(&run_unit.step);
    all_tests.dependOn(integration_step);
}

<<<

`build.zig.zon`: >>>

.{
    // This is the default name used by packages depending on this one. For
    // example, when a user runs `zig fetch --save <url>`, this field is used
    // as the key in the `dependencies` table. Although the user can choose a
    // different name, most users will stick with this provided value.
    //
    // It is redundant to include "zig" in this name because it is already
    // within the Zig package namespace.
    .name = .zgraph,
    .fingerprint = 0xd41c7dc566f3ae8e,

    // This is a [Semantic Version](https://semver.org/).
    // In a future version of Zig it will be used for package deduplication.
    .version = "0.0.0",

    // This field is optional.
    // This is currently advisory only; Zig does not yet do anything
    // with this value.
    //.minimum_zig_version = "0.11.0",

    // This field is optional.
    // Each dependency must either provide a `url` and `hash`, or a `path`.
    // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
    // Once all dependencies are fetched, `zig build` no longer requires
    // internet connectivity.
    .dependencies = .{
        // See `zig fetch --save <url>` for a command-line interface for adding dependencies.
        //.example = .{
        //    // When updating this field to a new URL, be sure to delete the corresponding
        //    // `hash`, otherwise you are communicating that you expect to find the old hash at
        //    // the new URL. If the contents of a URL change this will result in a hash mismatch
        //    // which will prevent zig from using it.
        //    .url = "https://example.com/foo.tar.gz",
        //
        //    // This is computed from the file contents of the directory of files that is
        //    // obtained after fetching `url` and applying the inclusion rules given by
        //    // `paths`.
        //    //
        //    // This field is the source of truth; packages do not come from a `url`; they
        //    // come from a `hash`. `url` is just one of many possible mirrors for how to
        //    // obtain a package matching this `hash`.
        //    //
        //    // Uses the [multihash](https://multiformats.io/multihash/) format.
        //    .hash = "...",
        //
        //    // When this is provided, the package is found in a directory relative to the
        //    // build root. In this case the package's hash is irrelevant and therefore not
        //    // computed. This field and `url` are mutually exclusive.
        //    .path = "foo",
        //
        //    // When this is set to `true`, a package is declared to be lazily
        //    // fetched. This makes the dependency only get fetched if it is
        //    // actually used.
        //    .lazy = false,
        //},
    },

    // Specifies the set of files and directories that are included in this package.
    // Only files and directories listed here are included in the `hash` that
    // is computed for this package. Only files listed here will remain on disk
    // when using the zig package manager. As a rule of thumb, one should list
    // files required for compilation plus any license(s).
    // Paths are relative to the build root. Use the empty string (`""`) to refer to
    // the build root itself.
    // A directory listed here means that all files within, recursively, are included.
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        // For example...
        //"LICENSE",
        //"README.md",
    },
}

<<<

`LICENSE`: >>>


<<<

`README.md`: >>>

# ZGraph

ZGraph is a high-performance, in-memory graph library with:

- **Pluggable storages**: adjacency list, adjacency matrix, incidence matrix.
- **Compile-time graph semantics**: `directed` / `undirected`, `weighted` / `unweighted`.
- **Unified algorithms** that operate across storages via a common trait surface.
- **Portable formats**:
  - `.zgraph` – human-readable, human-writable
  - `.zgraphb` – compressed, chunked binary for fast I/O / mmap
- **Robust conversion strategies** (duplicate, streamed, chunked, copy-on-write) to switch layouts under tight memory budgets.

ZGraphDB (paged container) builds on the same chunks and APIs; algorithms continue to live in ZGraph.

## Status

- ✅ Core storages compile and pass tests on Zig 0.16.
- ✅ `AdjacencyList`, `AdjacencyMatrix`, `IncidenceMatrix` with CRUD + neighbor ops.
- ✅ `.zgraph` / `.zgraphb` specifications documented; parsers/writers in progress.
- 🚧 Conversion strategies module & CLI utilities.

See **[ZGraph.Spec.md](./ZGraph.Spec.md)** for the canonical checklist and roadmap.

## Install

```bash
zig build test
zig build run
```

Zig: 0.16.x

## Quick start

```c++
const GS = @import("src/lib/core/graph_storage.zig").GraphStorage;
const Storage = GS(.AdjacencyList, true, true); // directed, weighted

var g = Storage.init(std.heap.page_allocator);
defer g.deinit();

try g.addEdge(0, 1, 3.5);
try g.addEdge(1, 1, 7.5);

if (g.getNeighbors(0)) |edges| {
    // ...
}
```

### Convert storage (e.g., list → matrix) with a memory budget

```zig
const conv = @import("src/lib/conversion/strategies.zig");
var dst = try conv.convertStorage(
    std.heap.page_allocator,
    Storage,                             // source type
    .AdjacencyMatrix, true, true,        // dest type + semantics
    &g,
    .Streamed,                           // strategy
    .{ .max_bytes_in_flight = 4 * 1024 * 1024 * 1024 }, // 4 GiB
);
defer dst.deinit();
```

### Import / Export

```bash
# text -> binary
zig build run -- convert --in graph.zgraph --out graph.zgraphb

# validate and print stats
zig build run -- stats --in graph.zgraphb
```

## Design pillars

- **Predictable performance**: zero-copy views, cache-friendly CSR, zstd block compression.
- **Compatibility**: readers ignore unknown chunks; text & binary round-trip.
- **Safety**: memory ownership is explicit; threads guarded by mutexes where needed.
- **Tested**: unit, property, and fuzz tests; algorithm parity across storages.

## Repo layout (idealized)

```
ZGraph/
├─ README.md
├─ ZGraph.Spec.md                  # Source of truth (feature checklist)
├─ LICENSE
├─ build.zig
├─ zig.mod
├─ docs/
│  ├─ formats/
│  │  ├─ zgraph-text-spec.md
│  │  └─ zgraphb-binary-spec.md
│  ├─ algorithms/
│  │  ├─ traversal.md
│  │  ├─ shortest_paths.md
│  │  ├─ connectivity.md
│  │  ├─ flow_cut.md
│  │  ├─ centrality.md
│  │  └─ spectral.md
│  ├─ storage_design.md
│  ├─ conversion_strategies.md
│  ├─ perf_tuning.md
│  ├─ safety_and_threading.md
│  └─ roadmap.md
├─ examples/
│  ├─ tiny/
│  │  ├─ triangle.zgraph
│  │  ├─ weighted_digraph.zgraph
│  │  └─ attributes.zgraph
│  ├─ conversions/
│  │  ├─ list_to_matrix.zig
│  │  └─ streamed_live_convert.zig
│  └─ cli/
│     ├─ import_export.zig
│     └─ metrics.zig
├─ src/
│  ├─ root.zig
│  ├─ lib/
│  │  ├─ core/
│  │  │  ├─ node.zig
│  │  │  ├─ edge.zig
│  │  │  ├─ graph_storage.zig
│  │  │  ├─ iterators.zig
│  │  │  └─ attributes.zig
│  │  ├─ data_structures/
│  │  │  ├─ adjacency_list.zig
│  │  │  ├─ adjacency_matrix.zig
│  │  │  └─ incidence_matrix.zig
│  │  ├─ formats/
│  │  │  ├─ zgraph_text.zig
│  │  │  ├─ zgraphb.zig
│  │  │  └─ chunk_provider.zig
│  │  ├─ conversion/
│  │  │  ├─ strategies.zig
│  │  │  ├─ duplicate_convert.zig
│  │  │  ├─ streamed_convert.zig
│  │  │  ├─ chunked_convert.zig
│  │  │  └─ cow_convert.zig
│  │  ├─ indices/
│  │  │  ├─ csr.zig
│  │  │  └─ degree_table.zig
│  │  ├─ algorithms/
│  │  │  ├─ traversal/
│  │  │  │  ├─ bfs.zig
│  │  │  │  └─ dfs.zig
│  │  │  ├─ shortest_paths/
│  │  │  │  ├─ dijkstra.zig
│  │  │  │  ├─ bellman_ford.zig
│  │  │  │  └─ floyd_warshall.zig
│  │  │  ├─ connectivity/
│  │  │  │  ├─ union_find.zig
│  │  │  │  └─ strongly_connected.zig
│  │  │  ├─ flow_cut/
│  │  │  │  ├─ edmonds_karp.zig
│  │  │  │  └─ dinic.zig
│  │  │  ├─ centrality/
│  │  │  │  ├─ pagerank.zig
│  │  │  │  └─ betweenness.zig
│  │  │  └─ spectral/
│  │  │     ├─ laplacian.zig
│  │  │     └─ power_iteration.zig
│  │  ├─ io/
│  │  │  ├─ file.zig
│  │  │  ├─ csv.zig
│  │  │  └─ zstd.zig
│  │  ├─ mem/
│  │  │  ├─ alloc.zig
│  │  │  └─ pool.zig
│  │  └─ util/
│  │     ├─ bitset.zig
│  │     ├─ hash.zig
│  │     └─ time.zig
│  └─ cli/
│     ├─ zgraph.zig
│     └─ subcommands/
│        ├─ convert.zig
│        ├─ validate.zig
│        ├─ build_index.zig
│        └─ stats.zig
├─ tests/
│  ├─ unit/
│  │  ├─ adjacency_list_test.zig
│  │  ├─ adjacency_matrix_test.zig
│  │  ├─ incidence_matrix_test.zig
│  │  ├─ formats_text_test.zig
│  │  ├─ formats_binary_test.zig
│  │  ├─ conversion_strategies_test.zig
│  │  └─ algorithms_smoke_test.zig
│  ├─ property/
│  │  ├─ graph_idempotence_test.zig
│  │  └─ random_graph_agreement_test.zig
│  ├─ fuzz/
│  │  └─ fuzzer.zig
│  └─ data/
│     ├─ tiny_graphs/*.zgraph
│     └─ medium_graphs/*.zgraph
├─ tools/
│  ├─ scripts/
│  │  ├─ gen_random_graph.zig
│  │  └─ bench_matrix_vs_list.zig
│  └─ perf/
│     └─ flamegraph_instructions.md
└─ benches/
   ├─ micro/
   │  ├─ csr_iter_bench.zig
   │  └─ parse_zgraph_bench.zig
   └─ macro/
      ├─ bfs_vs_dijkstra_bench.zig
      └─ convert_streamed_vs_duplicate.zig
```

## License

MIT

<<<

`ZGraph.MasterPlan.md`: >>>

# ZGraph — Unified Master Plan (Reconciled)

This document merges the current repository state with the idealized goals and becomes the **single source of truth**. Items are marked as:
- ✅ Done
- 🚧 Partial / scaffolding present
- ⭕ Not started

---

## A. Semantics & Types
- ✅ A1. Compile-time graph semantics (`directed`, `weighted`) across storages
- ✅ A2. Self-loops & multi-edges covered by tests
- ⭕ A3. Attributes (node/edge KV with typed values)
- ✅ A4. Numeric node IDs (u64/usize) in use
- ⭕ A5. Storage-agnostic iterators (common trait iterators)

## B. Storage Backends (in-memory)
- ✅ B1. AdjacencyList: CRUD + neighbor ops + tests
- ✅ B2. AdjacencyMatrix: CRUD + present bitset + tests
- ✅ B3. IncidenceMatrix: rows, sign/weight semantics, edge_set, parallel builder, tests
- ⭕ B4. CSR / ReverseCSR indices (standalone, optional overlays)
- ⭕ B5. Attribute storage (typed, columnar, interning)

## C. Common Trait Surface
- ✅ C1. `GraphStorage(type, directed, weighted)` factory
- ✅ C2. Core ops: init/deinit/add/remove/has/getNeighbors
- ⭕ C3. Attribute API (node/edge getters/setters)
- ⭕ C4. Iteration policy & attribute filters

## D. Conversion Strategies
- ⭕ D1–D7. Strategies + API + tests (`Duplicate`, `Streamed`, `Chunked`, `CopyOnWrite`)

## E. File Formats
- 🚧 E1. `.zgraph` text spec documented; runtime reader/writer pending
- 🚧 E2. `.zgraphb` binary spec documented; runtime reader/writer pending

## F. Algorithms
- 🚧 F1. Traversal (BFS/DFS/CC) — source files exist; unify over trait; add tests
- 🚧 F2. Shortest paths (Dijkstra/Bellman-Ford/Floyd-Warshall) — wire and test
- 🚧 F3. Connectivity (SCC) — add Tarjan/Kosaraju; tests
- 🚧 F4. Flow (Edmonds-Karp present; add Dinic); tests
- 🚧 F5. Centrality (PageRank present; add Betweenness); tests
- 🚧 F6. Spectral (Laplacian, eigen routines present); tests & trait integration

## G. Indices & Acceleration
- ⭕ G1. CSR build/use
- ⭕ G2. Reverse CSR (directed)
- ⭕ G3. Degree table
- ⭕ G4. Index persistence in `.zgraphb` optional blocks
- ⭕ G5. Rebuild-on-demand hooks

## H. Attributes
- ⭕ H1. Node & Edge KV (`int|float|bool|string`)
- ⭕ H2. Storage-agnostic attribute map with typed accessors
- ⭕ H3. Text↔Binary column mapping (string table)
- ⭕ H4. Attribute filters in iterators
- ⭕ H5. Tests for mixed types, missing values, interning

## I. I/O & CLI
- ⭕ I1. CLI subcommands: `convert`, `validate`, `build-index`, `stats`
- ⭕ I2. Streaming I/O (chunked) for both formats
- ⭕ I3. zstd dictionaries & auto-tuning

## J. Concurrency & Memory
- ✅ J0. IncidenceMatrix parallel builder + mutex guarding
- ⭕ J1. Threading doc & invariants
- ⭕ J2. Parallel builders for CSR & conversions where safe
- ⭕ J3. Allocator strategy knobs (GPA/Arena/Page) + docs
- ⭕ J4. Zero-copy `.zgraphb` readers (mmap)
- ⭕ J5. Stress tests (OOM behavior)

## K. Testing & Quality
- ✅ K1. Unit tests for storages
- ⭕ K2. Property tests (round-trips, cross-storage equivalence)
- ⭕ K3. Fuzzers for text/binary parsers
- ⭕ K4. Benchmarks (micro/macro) and tracked results
- ⭕ K5. CI (Win/macOS/Linux; Zig 0.16.x)
- ⭕ K6. `zig fmt` + static checks gates

## L. Documentation
- ✅ L1. README
- 🚧 L2. Detailed specs for `.zgraph`/`.zgraphb` (needs sync with runtime)
- ⭕ L3. Algorithm docs and complexity notes
- ⭕ L4. Conversion strategy doc (memory math & decision table)
- ⭕ L5. Perf tuning guide (allocators, cache, zstd params)
- ⭕ L6. Roadmap milestones mapping to this checklist

---

# Execution Order (Do This Next, Exactly)

## Phase 1 — Lock the Core Interfaces
1. **Define common trait surface (`GraphLike`)** with adapters over existing storages:
   - `neighbors(u)`, `hasEdge(u,v)`, `weight(u,v)?`, `nodeCount()`, `edgeCount()`
2. **Iterator policy**: stable order + attribute filter hooks; basic `NodeIter`, `EdgeFromIter`

## Phase 2 — Attributes (foundation for formats)
3. **Typed attribute store** (node & edge): `int|float|bool|string` + string interning
4. **Attribute API** on the trait surface + tests
5. **Iterator filters** using attributes

## Phase 3 — File Formats (runtime)
6. **`.zgraph` reader/writer** (streaming CSV-ish with schemas; tolerant of unknown sections); round-trip tests
7. **`.zgraphb` reader/writer** (chunked blocks + zstd + mmap-friendly); round-trip & parity tests
8. **Text↔Binary parity**: load(text)->save(binary)->load(binary) == load(text)

## Phase 4 — Conversion Strategies (memory-bounded)
9. `convertStorage` API + **Duplicate** strategy
10. **Streamed** strategy (destroy-as-you-go option; memory ceiling tests)
11. **Chunked** strategy (node sharding; parallel)
12. **Copy-On-Write** adapter (lazy migration) + background compaction
13. **Invariants & ceilings** property tests

## Phase 5 — Indices & Acceleration
14. **CSR/ReverseCSR** build & use as optional overlays for any storage
15. **Degree table** and **index persistence** blocks in `.zgraphb`
16. **Rebuild-on-demand** hooks

## Phase 6 — Algorithms (unify + verify)
17. Traversal (BFS/DFS/CC) over trait + CSR; tests across storages
18. Shortest paths (Dijkstra/BF/FW) with layout decision table; tests
19. Connectivity/SCC (Tarjan/Kosaraju); tests
20. Flow (finish Dinic); tests
21. Centrality (PageRank + Betweenness); tests
22. Spectral (laplacian, eigen); tests & perf

## Phase 7 — CLI, Streaming I/O, Docs, Quality Gates
23. CLI subcommands: `convert`, `validate`, `build-index`, `stats`
24. Streaming I/O for both formats + zstd dictionaries
25. Documentation: conversion strategies, perf tuning, thread model; keep specs synced
26. Property tests, fuzzers, benches; CI on all platforms; formatting/static checks gates

---

## Acceptance Criteria (per phase, condensed)
- **Formats:** Round-trips preserve counts, attributes, weights; unknown sections/blocks ignored.
- **Conversion:** Peak memory measured below ceiling; equivalence of neighbor sets/weights post-convert.
- **Indices:** CSR neighbors == storage neighbors; persisted indices reload correctly.
- **Algorithms:** Identical results across storages (given same semantics); perf within expected bounds.
- **CLI:** Non-zero exit on invalid files; stats match library queries; build-index regenerates CSR.
- **Docs:** Examples compile; decision tables match implemented behavior.

<<<

`ZGraph.Spec.md`: >>>

# ZGraph.Spec — Canonical Specification (Full & Final)

**Status:** Authoritative source of truth  
**Versioning:** Spec v1.0 (maps to ZGraph 1.x)  
**Scope:** ZGraph library (in-memory storages, algorithms, formats, conversion, CLI). ZGraphDB is a separate paged container that **reuses** these formats and **calls into** ZGraph algorithms.

> In Zig, **unit tests live with their source**. Integration/e2e and other suites live under `tests/*` and are wired via `build.zig`.

---

## 0. Design Goals (Non‑negotiables)

- **One trait surface**: All algorithms operate across any storage (list/matrix/incidence/CSR).
- **Compile-time semantics**: `directed`, `weighted` as comptime flags, no runtime branches in hot loops.
- **Attributes first‑class**: Node/edge KV attributes (`int|float|bool|string`), columnar under the hood.
- **Zero-copy where possible**: mmap `.zgraphb`, zstd-chunked blocks, CSR overlays.
- **Memory-bounded conversions**: multiple strategies with verifiable ceilings.
- **Forward-compatible formats**: readers ignore unknown sections/blocks. Round-trip `.zgraph` ⇄ `.zgraphb`.
- **Determinism**: canonical iteration order and serialized output for reproducible builds.
- **Safety**: explicit allocators, clear ownership; synchronization in parallel builders only.

---

## 1. Module Topology (Final Layout)

```
ZGraph/
├─ README.md                         # quickstart
├─ ZGraph.Spec.md                    # THIS file (canonical spec & checklist)
├─ LICENSE
├─ build.zig
├─ zig.mod
├─ docs/
│  ├─ formats/
│  │  ├─ zgraph-text-spec.md         # extracted from §6.1
│  │  └─ zgraphb-binary-spec.md      # extracted from §6.2
│  ├─ algorithms/*.md                # explainer docs per family
│  ├─ conversion_strategies.md
│  ├─ perf_tuning.md
│  └─ safety_and_threading.md
├─ src/
│  ├─ root.zig
│  ├─ lib/
│  │  ├─ core/
│  │  │  ├─ types.zig                # common types & Error sets
│  │  │  ├─ graph_like.zig           # trait surface + adapters
│  │  │  ├─ attributes.zig           # schema + column store + API
│  │  │  ├─ graph_storage.zig        # GraphStorage(Enum..) factory
│  │  │  └─ iterators.zig            # NodeIter, EdgeFromIter, AllEdgeIter
│  │  ├─ data_structures/
│  │  │  ├─ adjacency_list.zig
│  │  │  ├─ adjacency_matrix.zig
│  │  │  └─ incidence_matrix.zig
│  │  ├─ indices/
│  │  │  ├─ csr.zig                  # forward CSR
│  │  │  └─ csr_reverse.zig          # reverse CSR
│  │  ├─ formats/
│  │  │  ├─ zgraph_text.zig          # streaming reader/writer
│  │  │  └─ zgraphb.zig              # chunked binary reader/writer + mmap
│  │  ├─ conversion/
│  │  │  ├─ strategies.zig           # public API (ConvertStrategy, convertStorage)
│  │  │  ├─ duplicate_convert.zig
│  │  │  ├─ streamed_convert.zig
│  │  │  ├─ chunked_convert.zig
│  │  │  └─ cow_convert.zig
│  │  ├─ algorithms/
│  │  │  ├─ traversal/
│  │  │  │  ├─ bfs.zig
│  │  │  │  └─ dfs.zig
│  │  │  ├─ connectivity/
│  │  │  │  ├─ components.zig        # UF + CC
│  │  │  │  └─ scc.zig               # Tarjan / Kosaraju
│  │  │  ├─ shortest_paths/
│  │  │  │  ├─ dijkstra.zig
│  │  │  │  ├─ bellman_ford.zig
│  │  │  │  └─ floyd_warshall.zig
│  │  │  ├─ flow/
│  │  │  │  ├─ edmonds_karp.zig
│  │  │  │  └─ dinic.zig
│  │  │  ├─ centrality/
│  │  │  │  ├─ pagerank.zig
│  │  │  │  └─ betweenness.zig
│  │  │  └─ spectral/
│  │  │     ├─ laplacian.zig
│  │  │     └─ power_iteration.zig
│  │  ├─ io/
│  │  │  ├─ file.zig                 # path/FS utils
│  │  │  └─ zstd.zig                 # compression shim
│  │  ├─ mem/
│  │  │  ├─ alloc.zig                # GPA/Arena convenience
│  │  │  └─ pool.zig                 # edge/node pools (optional)
│  │  └─ util/
│  │     ├─ bitset.zig
│  │     ├─ hash.zig
│  │     └─ time.zig
│  └─ cli/
│     ├─ zgraph.zig                  # CLI entry
│     └─ subcommands/
│        ├─ convert.zig
│        ├─ validate.zig
│        ├─ build_index.zig
│        └─ stats.zig
├─ tests/
│  ├─ integration/
│  │  ├─ convert_roundtrip_test.zig
│  │  ├─ conversion_memory_ceiling_test.zig
│  │  └─ algorithms_cross_storage_test.zig
│  ├─ e2e/
│  │  ├─ cli_convert_and_stats_test.zig
│  │  └─ cli_build_index_test.zig
│  ├─ property/
│  │  ├─ random_graph_equivalence_test.zig
│  │  └─ formats_fuzz_text_binary.zig
│  └─ data/
│     ├─ tiny/*.zgraph
│     └─ medium/*.zgraph
└─ benches/
   ├─ micro/*.zig
   └─ macro/*.zig
```

---

## 2. Common Types & Error Sets (`core/types.zig`)

```zig
pub const NodeId = u64;
pub const Weight = f64;             // Present only when weighted=true

pub const Semantic = struct {
    directed: bool,
    weighted: bool,
};

pub const GraphError = error{
    OutOfMemory,
    InvalidNode,
    InvalidEdge,
    EdgeNotFound,
    EdgeAlreadyExists,
    GraphNotWeighted,
    ParseError,
    UnsupportedVersion,
    IoError,
    SchemaMismatch,
    Overflow,
};
```

---

## 3. Trait Surface (`core/graph_like.zig`)

### 3.1. Interface (generic over storages)
```zig
pub fn GraphLike(comptime directed: bool, comptime weighted: bool) type {
    return struct {
        // Required
        pub fn nodeCount(self: *const @This()) usize;
        pub fn edgeCount(self: *const @This()) usize;
        pub fn hasNode(self: *const @This(), u: NodeId) bool;
        pub fn hasEdge(self: *const @This(), u: NodeId, v: NodeId) bool;
        pub fn addNode(self: *@This(), u: NodeId) !void;
        pub fn removeNode(self: *@This(), u: NodeId) !void;
        pub fn addEdge(self: *@This(), u: NodeId, v: NodeId, weight: if (weighted) Weight else void) !void;
        pub fn removeEdge(self: *@This(), u: NodeId, v: NodeId) !void;

        // Iteration (stable order)
        pub fn nodeIter(self: *const @This()) NodeIter;
        pub fn edgeFromIter(self: *const @This(), u: NodeId) EdgeFromIter;

        // Optional weight accessor
        pub fn getWeight(self: *const @This(), u: NodeId, v: NodeId) if (weighted) ?Weight else void;

        // Attributes are attached via Attributes API (§5) and accessed by id
    };
}
```

### 3.2. Iterators (`core/iterators.zig`)
```zig
pub const NodeIter = struct {
    // next() -> ?NodeId
};
pub const EdgeFromIter = struct {
    // next() -> ?struct{ dst: NodeId, weight: if (weighted) ?Weight else void }
};
pub const AllEdgeIter = struct {
    // next() -> ?struct{ src: NodeId, dst: NodeId, weight: if (weighted) ?Weight else void }
};
```

---

## 4. Graph Storage Factory (`core/graph_storage.zig`)

```zig
pub const GraphStorageType = enum { AdjacencyList, AdjacencyMatrix, IncidenceMatrix };

pub fn GraphStorage(comptime st: GraphStorageType, comptime directed: bool, comptime weighted: bool) type;
```
Each storage implements the GraphLike interface via thin adapters (or directly match the surface).

---

## 5. Attributes (Schema + Column Store) (`core/attributes.zig`)

### 5.1. Types
```zig
pub const ValueType = enum { Int, Float, Bool, String };
pub const Value = union(ValueType) {
    Int: i64,
    Float: f64,
    Bool: bool,
    String: u32, // interned string id (0xFFFFFFFF == null)
};

pub const ColumnDesc = struct { name: []const u8, ty: ValueType };
pub const Schema = struct {
    node: []const ColumnDesc,
    edge: []const ColumnDesc,
};
```

### 5.2. Column Storage
- Node columns: arrays keyed by node index (sparse map for arbitrary NodeId → dense index mapping).
- Edge columns: arrays keyed by **edge ordinal** (storage-provided stable edge id) or `(src,dst)` mapping.
- Strings: UTF‑8 table with dedup; id `0xFFFFFFFF` = null.

### 5.3. API
```zig
pub const Attributes = struct {
    pub fn init(alloc: std.mem.Allocator, schema: Schema) !Attributes;
    pub fn deinit(self: *Attributes) void;

    // Node attributes
    pub fn setNode(self: *Attributes, node: NodeId, key: []const u8, val: Value) !void;
    pub fn getNode(self: *const Attributes, node: NodeId, key: []const u8) ?Value;

    // Edge attributes (by endpoints; storage adapter resolves edge id)
    pub fn setEdge(self: *Attributes, src: NodeId, dst: NodeId, key: []const u8, val: Value) !void;
    pub fn getEdge(self: *const Attributes, src: NodeId, dst: NodeId, key: []const u8) ?Value;

    // String table
    pub fn intern(self: *Attributes, s: []const u8) !u32;
    pub fn lookup(self: *const Attributes, id: u32) ?[]const u8;
};
```

### 5.4. Filters (for iterators)
```zig
pub const AttrFilter = struct {
    // Example: key="active", op="==", val=true
    key: []const u8,
    op: enum { Eq, Ne, Lt, Le, Gt, Ge, Exists },
    val: ?Value = null,
};

// Applied via iterator adaptors:
pub fn filteredNodeIter(g: anytype, attrs: *const Attributes, filter: AttrFilter) NodeIter;
```

---

## 6. File Formats (Runtime + On-disk) (`formats/*`)

### 6.1. `.zgraph` — Text (Human)  
**Header** (required):
```
#!zgraph 1
graph = directed|undirected
weights = weighted|unweighted
schema.node = name:string,group:int,active:bool
schema.edge = label:string,capacity:float
```

**Sections** (order-free, repeatable, append behavior):
- `[NODES]` rows: `id, <node-props-by-schema>`
- `[EDGES]`
  - if weighted: `src, dst, weight, <edge-props>`
  - else:       `src, dst, <edge-props>`
- `[META]` free-form `key=value` lines (ignored by reader unless known)
- `[INDEX]` hints (optional), ignored by reader
- `[TAGS]` free-form labels

**CSV rules**: RFC4180-ish; quoted fields with `""`; empty -> unset.

**Reader/Writer API** (`formats/zgraph_text.zig`):
```zig
pub const TextOptions = struct { canonical: bool = true };

pub fn read(alloc: Allocator, rdr: anytype) !struct{
    semantic: Semantic,
    schema: Schema,
    nodes: []NodeId,
    edges: []struct{ src: NodeId, dst: NodeId, weight: ?Weight },
    attrs: Attributes,
};

pub fn write(alloc: Allocator, w: anytype, g: anytype, attrs: *const Attributes, opts: TextOptions) !void;
```

### 6.2. `.zgraphb` — Binary (Chunked, Compressed)  
**Header**:
- Magic: `ZGB1`
- Version: u16
- Flags: bitfield (directed, weighted, varint_ids, has_indices, compression)
- Offsets to blocks; global CRC32

**Blocks** (individually zstd-compressed if enabled):
- **StringTable**: contiguous UTF‑8, u32 ids
- **SchemaBlock**: column descriptors (node/edge)
- **NodeTable**: COUNT, varint NodeId list (or fixed u64), optional NodeId→dense map
- **EdgeTable**: COUNT, varint src, varint dst, `[f64 weight]` if weighted
- **NodeColumns** / **EdgeColumns**: per-column typed vectors
- **Indices** (optional): CSR, ReverseCSR, DegreeTable
- **Meta**: key/value table

**Reader/Writer API** (`formats/zgraphb.zig`):
```zig
pub const BinaryOptions = struct {
    compression: enum { none, zstd } = .zstd,
    block_size: usize = 1 << 20, // 1 MiB
    mmap: bool = true,
};

pub fn read(alloc: Allocator, rdr_or_path: anytype) !struct{
    semantic: Semantic,
    schema: Schema,
    provider: ChunkProvider, // zero-copy block access if mmap
    attrs: AttributesView,   // read-only view
    edge_index: ?CSRView,
};

pub fn write(alloc: Allocator, w_or_path: anytype, g: anytype, attrs: *const Attributes, opts: BinaryOptions) !void;
```

**Forward compatibility**: unknown blocks skipped; offsets allow appending blocks; version gates behavior.

---

## 7. Conversion Strategies (`conversion/*`)

### 7.1. API
```zig
pub const ConvertStrategy = enum { Duplicate, Streamed, Chunked, CopyOnWrite };

pub const ConvertOpts = struct {
    max_bytes_in_flight: usize = 0,  // 0 = auto
    chunk_nodes: usize = 0,          // only for Chunked
    destroy_source: bool = false,    // allowed for Streamed
};

pub fn convertStorage(
    alloc: Allocator,
    comptime Src: type,
    comptime dst_type: GraphStorageType,
    comptime directed: bool,
    comptime weighted: bool,
    src: *Src,
    strategy: ConvertStrategy,
    opts: ConvertOpts,
) !anytype; // returns destination storage
```

### 7.2. Behavior Guarantees
- **Duplicate**: peak ≈ |src| + |dst|; no source mutation.
- **Streamed**: peak bounded by `max(chunk, dst_window)`; may mutate/destroy source if `destroy_source=true`.
- **Chunked**: shard nodes; parallelizable; peak ≈ |chunk| + overhead.
- **CopyOnWrite**: lazy migration via adapter; background compaction optional.

### 7.3. Tests
- Node/edge/weight parity after conversion.  
- Memory ceilings verified under synthetic big graphs (integration tests).

---

## 8. Indices & Acceleration (`indices/*`)

### 8.1. CSR
```zig
pub const CSR = struct {
    // row_offsets.len = nodeCount + 1
    row_offsets: []usize,
    col_indices: []NodeId,
    weights: if (weighted) ?[]Weight else void,

    pub fn build(alloc: Allocator, g: anytype) !CSR;
    pub fn deinit(self: *CSR, alloc: Allocator) void;

    pub fn neighbors(self: *const CSR, u: NodeId) []const NodeId; // O(1) slice
};
```

### 8.2. Reverse CSR (directed only)
```zig
pub const CSRReverse = struct {
    // same shape as CSR but on incoming edges
    pub fn build(alloc: Allocator, g: anytype) !CSRReverse;
};
```

### 8.3. Degree Table
```zig
pub const DegreeTable = struct {
    in_deg: []u32,  // or omitted if undirected
    out_deg: []u32,
    pub fn build(alloc: Allocator, g: anytype) !DegreeTable;
};
```

**Persistence**: optional blocks in `.zgraphb` with checksums; rebuilt if absent or stale.

---

## 9. Algorithms (`algorithms/*`) — Uniform over GraphLike

### 9.1. Traversal
```zig
pub fn bfs(alloc: Allocator, g: anytype, src: NodeId) ![]NodeId;
pub fn dfs_preorder(alloc: Allocator, g: anytype, src: NodeId) ![]NodeId;
pub fn connected_components(alloc: Allocator, g: anytype) ![]u32; // label per node
```

### 9.2. Shortest Paths
```zig
pub fn dijkstra(alloc: Allocator, g: anytype, src: NodeId) !struct{ dist: []f64, prev: []?NodeId };
pub fn bellman_ford(alloc: Allocator, g: anytype, src: NodeId) !struct{ dist: []f64, prev: []?NodeId, has_neg_cycle: bool };
pub fn floyd_warshall(alloc: Allocator, g: anytype) ![][]f64;
```

### 9.3. Connectivity & SCC
```zig
pub fn strongly_connected(alloc: Allocator, g: anytype) ![]u32; // component id per node
```

### 9.4. Flow
```zig
pub fn edmonds_karp(alloc: Allocator, g: anytype, s: NodeId, t: NodeId, capacity_key: []const u8) !f64;
pub fn dinic(alloc: Allocator, g: anytype, s: NodeId, t: NodeId, capacity_key: []const u8) !f64;
```

### 9.5. Centrality
```zig
pub fn pagerank(alloc: Allocator, g: anytype, damping: f64, iters: usize, tol: f64) ![]f64;
pub fn betweenness(alloc: Allocator, g: anytype, normalized: bool) ![]f64;
```

### 9.6. Spectral
```zig
pub fn laplacian(alloc: Allocator, g: anytype) !struct{ L: anytype };
pub fn power_iteration(alloc: Allocator, A: anytype, iters: usize, tol: f64) !struct{ eigvec: []f64, eigval: f64 };
```

**Choice of layout at runtime**: decision table maps algorithm → preferred index/storage; auto-build CSR if enabled in options.

---

## 10. CLI (`src/cli`)

```
zgraph convert    --in <path> --out <path> [--to <list|matrix|incidence>] [--binary|--text] [--compression zstd|none] [--strategy duplicate|streamed|chunked|cow] [--max-bytes N]
zgraph validate   --in <path>
zgraph build-index --in <path> [--csr] [--reverse]
zgraph stats      --in <path> [--json]
```

**Exit codes**: non-zero on invalid input/failed validation.  
**JSON `stats`**: nodes, edges, degree histograms, components, optional timings.

---

## 11. Testing Strategy

- **Unit tests** with sources (Zig convention) — storages, formats readers/writers, algorithms.
- **Integration tests** (`tests/integration`) — round trips, cross-storage equivalence, conversion invariants, memory ceilings.
- **E2E tests** (`tests/e2e`) — CLI flows.
- **Property tests** (`tests/property`) — random graphs, fuzz text/binary parsers.
- **Data fixtures** (`tests/data`) — tiny & medium graphs.
- **`build.zig`** provides: `zig build test`, `zig build test-all`, and filtered suites.

---

## 12. Performance Targets (initial)

- **Parse `.zgraphb`**: ≥ 2 GB/s per core when uncompressed; with zstd, ≥ 700 MB/s/core (dict-enabled).  
- **CSR neighbor iteration**: contiguous scans; no allocations after build.  
- **Conversion**: streamed peak memory within ±5% of configured ceiling on synthetic workload.  
- **Parallel build** (incidence/CSR): ≥ 80% CPU utilization on 8 cores.

---

## 13. Concurrency & Memory

- Thread safety: graph mutation not thread-safe unless explicitly documented (e.g., parallel builders).  
- Readers (mmap `.zgraphb`) are thread-safe; shared immutable structures.  
- Allocator knobs: GPA, Arena, Page; document trade-offs (docs/perf_tuning.md).

---

## 14. Backward/Forward Compatibility

- `.zgraph` is tolerant: unknown sections ignored.  
- `.zgraphb` blocks are skippable; new blocks may be appended; version gates semantics.  
- Idempotent round-trips: text ⇄ binary ⇄ in-memory produce equivalent graphs (counts, edges, weights, attributes).

---

## 15. Acceptance Criteria (Global)

- Algorithms return **identical results** across storages (given same semantics and adequate precision).  
- Conversions preserve edges/weights/attributes; indices rebuild or persist.  
- Formats round-trip with **no data loss**; unknown data preserved where spec allows.  
- CLI exposes all core flows; non-zero exit for invalid inputs; JSON stats match library queries.  
- Documentation & examples compile; decision tables match implementation.

---

## 16. Roadmap (Strict Order of Execution)

1. **GraphLike surface + iterators** (adapters for all storages).  
2. **Attributes**: schema + column store + API + tests.  
3. **`.zgraph`**: streaming reader/writer + round-trip tests.  
4. **`.zgraphb`**: chunked+zstd + mmap reader + parity tests.  
5. **Conversion strategies**: Duplicate → Streamed → Chunked → COW (+ ceiling tests).  
6. **CSR & Reverse CSR** (optional overlays) + degree table + persistence blocks.  
7. **Algorithms unification**: traversal → shortest paths → SCC → flow → centrality → spectral.  
8. **CLI**: convert / validate / build-index / stats.  
9. **Property/fuzz/benches/CI** + docs (conversion, perf, safety).

---

## 17. Public API Summary (import points)

```zig
const GS = @import("src/lib/core/graph_storage.zig").GraphStorage;
const GL = @import("src/lib/core/graph_like.zig");
const Attr = @import("src/lib/core/attributes.zig");
const Cvt = @import("src/lib/conversion/strategies.zig");
const FTxt = @import("src/lib/formats/zgraph_text.zig");
const FBin = @import("src/lib/formats/zgraphb.zig");
const CSR = @import("src/lib/indices/csr.zig");

// Example:
const Storage = GS(.AdjacencyList, true, true);
var g = Storage.init(alloc);
defer g.deinit();
try g.addEdge(1, 2, 3.5);

var attrs = try Attr.Attributes.init(alloc, .{
    .node = &[_]Attr.ColumnDesc{ .{ .name="name", .ty=.String } },
    .edge = &[_]Attr.ColumnDesc{ .{ .name="capacity", .ty=.Float } },
});
defer attrs.deinit();
try attrs.setEdge(1, 2, "capacity", .{ .Float=10.0 });

try FTxt.write(alloc, stdout, g, &attrs, .{});
```

<<<

`main.zig`: >>>

const std = @import("std");
const lib = @import("zgraph_root");

pub fn main() !void {
    std.debug.print("All your {s} are belong to us.\n", .{"codebase"});

    const stdout_file = std.io.getStdOut().writer();
    var bw = std.io.bufferedWriter(stdout_file);
    const stdout = bw.writer();

    try stdout.print("Run `zig build test` to run the tests.\n", .{});
    try bw.flush();
}

test "simple test" {
    var list = std.ArrayList(i32).initCapacity(std.testing.allocator, 0);
    defer list.deinit(std.testing.allocator);
    try list.append(std.testing.allocator, 42);
    try std.testing.expectEqual(@as(i32, 42), list.pop());
}

test "use other module" {
    _ = lib; // prevent unused
    try std.testing.expectEqual(@as(i32, 150), 100 + 50);
}

test "fuzz example" {
    const Context = struct {
        fn testOne(context: @This(), input: []const u8) anyerror!void {
            _ = context;
            try std.testing.expect(!std.mem.eql(u8, "canyoufindme", input));
        }
    };
    try std.testing.fuzz(Context{}, Context.testOne, .{});
}

<<<

`root.zig`: >>>

const std = @import("std");

// ✅ Core Graph Components
pub const Graph = @import("lib/core/graph.zig").Graph;
pub const Node = @import("lib/core/node.zig").Node;
pub const Edge = @import("lib/core/edge.zig").Edge;
pub const GraphStorage = @import("lib/core/graph_storage.zig").GraphStorage;

// ✅ Data Structures (Graph Representations)
pub const AdjacencyList = @import("lib/data_structures/adjacency_list.zig");
pub const AdjacencyMatrix = @import("lib/data_structures/adjacency_matrix.zig");
pub const IncidenceMatrix = @import("lib/data_structures/incidence_matrix.zig");

// pub const LaplacianMatrix = @import("lib/data_structures/laplacian_matrix.zig");

pub const data_structures = struct {
    pub const AdjacencyList = @import("lib/data_structures/adjacency_list.zig");
    pub const AdjacencyMatrix = @import("lib/data_structures/adjacency_matrix.zig");
    pub const IncidenceMatrix = @import("lib/data_structures/incidence_matrix.zig");
};
// // ✅ Graph Formats (Serialization & Parsing)
// pub const ZGraphFormat = @import("lib/formats/zgraph.zig");
// pub const JSONFormat = @import("lib/formats/json.zig");
// pub const DotFormat = @import("lib/formats/dot.zig");

// // ✅ Graph Algorithms
// pub const algorithms = struct {
//     pub const traversal = struct {
//         pub const bfs = @import("lib/algorithms/traversal/bfs.zig");
//         pub const dfs = @import("lib/algorithms/traversal/dfs.zig");
//     };

//     pub const shortest_path = struct {
//         pub const dijkstra = @import("lib/algorithms/shortest_path/dijkstra.zig");
//         pub const bellman_ford = @import("lib/algorithms/shortest_path/bellman_ford.zig");
//         pub const floyd_warshall = @import("lib/algorithms/shortest_path/floyd_warshall.zig");
//     };

//     pub const mst = struct {
//         pub const kruskal = @import("lib/algorithms/mst/kruskal.zig");
//         pub const prim = @import("lib/algorithms/mst/prim.zig");
//     };

//     pub const flow = struct {
//         pub const edmonds_karp = @import("lib/algorithms/flow/edmonds_karp.zig");
//         pub const ford_fulkerson = @import("lib/algorithms/flow/ford_fulkerson.zig");
//     };

//     pub const spectral = struct {
//         pub const laplacian_matrix = @import("lib/algorithms/spectral/laplacian_matrix.zig");
//         // pub const eigenvector_centrality = @import("lib/algorithms/spectral/eigenvector_centrality.zig");
//     };
// };

// // ✅ Utilities
// pub const utilities = struct {
//     pub const debug = @import("lib/utilities/debug.zig");
// };

// ✅ Ensure Zig detects all public functions and runs tests for this module
test {
    std.testing.refAllDecls(@This());
}

<<<

`adjacency_list.zig`: >>>

const std = @import("std");
const Allocator = std.mem.Allocator;
const Node = @import("../core/node.zig").Node;
const Edge = @import("../core/edge.zig").Edge;

pub fn AdjacencyList(comptime directed: bool, comptime weighted: bool) type {
    return struct {
        allocator: Allocator,
        adjacency: std.AutoHashMap(u64, std.ArrayList(Edge(weighted))),

        pub fn init(allocator: Allocator) @This() {
            return @This(){
                .allocator = allocator,
                .adjacency = std.AutoHashMap(u64, std.ArrayList(Edge(weighted))).init(allocator),
            };
        }

        pub fn deinit(self: *@This()) void {
            var it = self.adjacency.iterator();
            while (it.next()) |entry| {
                entry.value_ptr.deinit(self.allocator); // 0.16: requires allocator
            }
            self.adjacency.deinit();
        }

        pub fn addNode(self: *@This(), node_id: u64) !void {
            const entry = try self.adjacency.getOrPut(node_id);
            if (!entry.found_existing) {
                entry.value_ptr.* = try std.ArrayList(Edge(weighted)).initCapacity(self.allocator, 0); // 0.16 (fallible)
            }
        }

        pub fn removeNode(self: *@This(), node_id: u64) !void {
            if (self.adjacency.getPtr(node_id)) |edges| {
                edges.deinit(self.allocator); // 0.16
                _ = self.adjacency.remove(node_id);
            }

            if (!directed) {
                var it = self.adjacency.iterator();
                while (it.next()) |entry| {
                    var edges = entry.value_ptr;
                    var i: usize = 0;
                    while (i < edges.items.len) {
                        if (edges.items[i].dst == node_id) {
                            _ = edges.orderedRemove(i);
                        } else {
                            i += 1;
                        }
                    }
                }
            }
        }

        pub fn addEdge(self: *@This(), src: u64, dst: u64, weight: if (weighted) ?f64 else void) !void {
            var src_entry = try self.adjacency.getOrPut(src);
            if (!src_entry.found_existing) {
                src_entry.value_ptr.* = try std.ArrayList(Edge(weighted)).initCapacity(self.allocator, 0); // 0.16
            }

            var dst_entry = try self.adjacency.getOrPut(dst);
            if (!dst_entry.found_existing) {
                dst_entry.value_ptr.* = try std.ArrayList(Edge(weighted)).initCapacity(self.allocator, 0); // 0.16
            }

            // allow self-loops and multi-edges
            try src_entry.value_ptr.append(self.allocator, try Edge(weighted).init(self.allocator, src, dst, if (weighted) weight.? else {}));

            if (!directed) {
                try dst_entry.value_ptr.append(self.allocator, try Edge(weighted).init(self.allocator, dst, src, if (weighted) weight.? else {}));
            }
        }

        pub fn removeEdge(self: *@This(), src: u64, dst: u64) !void {
            if (self.adjacency.getPtr(src)) |edges| {
                try removeEdgeHelper(edges, dst);
                if (edges.items.len == 0) {
                    edges.deinit(self.allocator); // 0.16
                    _ = self.adjacency.remove(src);
                }
            } else {
                return error.EdgeNotFound;
            }

            if (!directed) {
                if (self.adjacency.getPtr(dst)) |edges2| {
                    try removeEdgeHelper(edges2, src);
                    if (edges2.items.len == 0) {
                        edges2.deinit(self.allocator); // 0.16
                        _ = self.adjacency.remove(dst);
                    }
                } else {
                    return error.EdgeNotFound;
                }
            }

            // extra cleanup if any empty lists remain
            if (self.adjacency.get(src)) |e1| {
                if (e1.items.len == 0) _ = self.adjacency.remove(src);
            }
            if (self.adjacency.get(dst)) |e2| {
                if (e2.items.len == 0) _ = self.adjacency.remove(dst);
            }
        }

        fn removeEdgeHelper(edges: *std.ArrayList(Edge(weighted)), target: u64) !void {
            var i: usize = 0;
            var removed: bool = false;
            while (i < edges.items.len) {
                if (edges.items[i].dst == target) {
                    _ = edges.orderedRemove(i);
                    removed = true;
                    break;
                }
                i += 1;
            }
            if (!removed) return error.EdgeNotFound;
        }

        pub fn getNeighbors(self: *@This(), node_id: u64) ?std.ArrayList(Edge(weighted)) {
            return self.adjacency.get(node_id);
        }

        fn ensureNodeExists(self: *@This(), node_id: u64) !void {
            const entry = try self.adjacency.getOrPut(node_id);
            if (!entry.found_existing) {
                entry.value_ptr.* = try std.ArrayList(Edge(weighted)).initCapacity(self.allocator, 0); // 0.16
            }
        }
    };
}

// Unit Tests (unchanged)
test "AdjacencyList: Initialize and Deinitialize" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();
    try std.testing.expectEqual(@as(usize, 0), list.adjacency.count());
}

test "AdjacencyList: Can add isolated nodes" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addNode(5);
    try list.addNode(10);

    try std.testing.expect(list.getNeighbors(5) != null);
    try std.testing.expect(list.getNeighbors(10) != null);
}

test "AdjacencyList: Removing an isolated node works correctly" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addNode(7);
    try list.removeNode(7);

    try std.testing.expect(list.getNeighbors(7) == null);
}

test "AdjacencyList: Retrieving neighbors of an isolated node returns null" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try std.testing.expect(list.getNeighbors(99) == null);
}

test "AdjacencyList: Add and Remove Edges" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 2, 5.0);
    try std.testing.expect(list.getNeighbors(1) != null);
    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(1).?.items.len);

    try list.removeEdge(1, 2);
    try std.testing.expectEqual(@as(usize, 0), if (list.getNeighbors(1)) |edges| edges.items.len else 0);
}

test "AdjacencyList: Removing a non-existent edge should return an error" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try std.testing.expectError(error.EdgeNotFound, list.removeEdge(1, 2));
}

test "AdjacencyList: Adding duplicate edges should increase count" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 2, 3.5);
    try list.addEdge(1, 2, 4.2); // Same edge, different weight

    try std.testing.expectEqual(@as(usize, 2), list.getNeighbors(1).?.items.len);
}

test "AdjacencyList: Removing a node should remove all associated edges" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 2, 4.5);
    try list.addEdge(1, 3, 3.0);
    try list.addEdge(2, 3, 2.0);

    try list.removeNode(1);

    try std.testing.expect(list.getNeighbors(1) == null);
    try std.testing.expect(list.getNeighbors(2) != null);
    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(2).?.items.len);
}

test "AdjacencyList: Removing a node with many connections removes all references" {
    var list = AdjacencyList(false, true).init(std.testing.allocator); // Undirected
    defer list.deinit();

    try list.addEdge(1, 2, 5.0);
    try list.addEdge(1, 3, 6.0);
    try list.addEdge(1, 4, 7.0);
    try list.addEdge(1, 5, 8.0);
    try list.addEdge(1, 6, 9.0);

    try std.testing.expectEqual(@as(usize, 5), list.getNeighbors(1).?.items.len);

    try list.removeNode(1);

    try std.testing.expect(list.getNeighbors(1) == null);

    for ([_]u64{ 2, 3, 4, 5, 6 }) |n| {
        try std.testing.expect(list.getNeighbors(n) != null);
        try std.testing.expectEqual(@as(usize, 0), list.getNeighbors(n).?.items.len);
    }
}

test "AdjacencyList: Removing self-loop should work correctly" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 1, 2.5);

    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(1).?.items.len);

    try list.removeEdge(1, 1);

    try std.testing.expectEqual(@as(usize, 0), if (list.getNeighbors(1)) |edges| edges.items.len else 0);
}

test "AdjacencyList: Can handle multiple self-loops and remove them correctly" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 1, 2.5);
    try list.addEdge(1, 1, 3.0);
    try list.addEdge(1, 1, 3.5);

    try std.testing.expectEqual(@as(usize, 3), list.getNeighbors(1).?.items.len);

    try list.removeEdge(1, 1);
    try std.testing.expectEqual(@as(usize, 2), list.getNeighbors(1).?.items.len);

    try list.removeEdge(1, 1);
    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(1).?.items.len);

    try list.removeEdge(1, 1);
    try std.testing.expectEqual(@as(usize, 0), if (list.getNeighbors(1)) |edges| edges.items.len else 0);
}

test "AdjacencyList: Removing a node in an undirected graph removes incoming edges" {
    var list = AdjacencyList(false, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 2, 4.5);
    try list.addEdge(1, 3, 3.0);
    try list.addEdge(2, 3, 2.0);

    try list.removeNode(2);

    try std.testing.expect(list.getNeighbors(2) == null);
    try std.testing.expect(list.getNeighbors(1) != null);
    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(1).?.items.len);
    try std.testing.expect(list.getNeighbors(3) != null);
    try std.testing.expectEqual(@as(usize, 1), list.getNeighbors(3).?.items.len);
}

test "AdjacencyList: Adding edge should auto-create nodes" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(99, 100, 3.5);
    try std.testing.expect(list.getNeighbors(99) != null);
    try std.testing.expect(list.getNeighbors(100) != null);
}

test "AdjacencyList: Removing a non-existent edge does nothing" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try std.testing.expectError(error.EdgeNotFound, list.removeEdge(42, 99));
}

test "AdjacencyList: Removing last edge removes empty nodes" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    try list.addEdge(1, 2, 5.0);
    try std.testing.expect(list.getNeighbors(1) != null);

    try list.removeEdge(1, 2);

    try std.testing.expect(list.getNeighbors(1) == null);
    try std.testing.expect(list.getNeighbors(2) == null);
}

test "AdjacencyList: Memory is properly freed on deinit" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);

    try list.addEdge(1, 2, 3.5);
    try list.addEdge(3, 4, 1.2);

    list.deinit(); // should release all memory with no leaks
}

test "AdjacencyList: Can handle large graphs efficiently" {
    var list = AdjacencyList(true, true).init(std.testing.allocator);
    defer list.deinit();

    var i: u64 = 0;
    while (i < 9_999) : (i += 1) {
        try list.addEdge(i, i + 1, @floatFromInt(i % 100));
    }

    try std.testing.expectEqual(@as(usize, 10_000), list.adjacency.count());
}

<<<

`adjacency_matrix.zig`: >>>

const std = @import("std");
const Allocator = std.mem.Allocator;
const BitSetRange = std.bit_set.Range;

pub fn AdjacencyMatrix(comptime directed: bool, comptime weighted: bool) type {
    return struct {
        allocator: Allocator,
        matrix: std.ArrayList([]if (weighted) ?f64 else bool),
        present_nodes: std.DynamicBitSetUnmanaged,
        node_count: usize,

        pub fn init(allocator: Allocator, initial_capacity: usize) !@This() {
            var matrix = try std.ArrayList([]if (weighted) ?f64 else bool).initCapacity(allocator, initial_capacity);
            for (0..initial_capacity) |_| {
                const row = try allocator.alloc(if (weighted) ?f64 else bool, initial_capacity);
                @memset(row, if (weighted) null else false);
                try matrix.append(allocator, row); // 0.16: needs allocator
            }

            var present_nodes = std.DynamicBitSetUnmanaged{};
            try present_nodes.resize(allocator, initial_capacity, false);
            present_nodes.setRangeValue(BitSetRange{ .start = 0, .end = initial_capacity }, false);

            return @This(){
                .allocator = allocator,
                .matrix = matrix,
                .present_nodes = present_nodes,
                .node_count = initial_capacity,
            };
        }

        pub fn deinit(self: *@This()) void {
            for (self.matrix.items) |row| {
                self.allocator.free(row);
            }
            self.matrix.deinit(self.allocator); // 0.16: needs allocator
            self.present_nodes.deinit(self.allocator);
        }

        pub fn addNode(self: *@This(), node_id: ?usize) !usize {
            const new_id = node_id orelse blk: {
                // Reuse a cleared bit if available
                var it = self.present_nodes.iterator(.{});
                while (it.next()) |i| {
                    if (!self.present_nodes.isSet(i)) break :blk i;
                }
                break :blk self.node_count;
            };

            if (new_id >= self.node_count) {
                const new_size = new_id + 1;

                // Expand each existing row
                for (self.matrix.items) |*row| {
                    row.* = try self.allocator.realloc(row.*, new_size);
                    @memset(row.*[self.node_count..new_size], if (weighted) null else false);
                }

                // Add new rows
                for (self.node_count..new_size) |_| {
                    const row = try self.allocator.alloc(if (weighted) ?f64 else bool, new_size);
                    @memset(row, if (weighted) null else false);
                    try self.matrix.append(self.allocator, row); // 0.16
                }

                try self.present_nodes.resize(self.allocator, new_size, false);
                self.node_count = new_size;
            }

            self.present_nodes.set(new_id);
            return new_id;
        }

        pub fn removeNode(self: *@This(), node_id: usize) !void {
            if (node_id >= self.node_count or !self.present_nodes.isSet(node_id)) {
                return error.InvalidNode;
            }
            self.present_nodes.unset(node_id);

            // Clear all edges to/from this node
            for (0..self.node_count) |i| {
                if (weighted) {
                    self.matrix.items[node_id][i] = null;
                    self.matrix.items[i][node_id] = null;
                } else {
                    self.matrix.items[node_id][i] = false;
                    self.matrix.items[i][node_id] = false;
                }
            }
        }

        pub fn addEdge(self: *@This(), src: usize, dst: usize, weight: if (weighted) ?f64 else void) !void {
            if (src >= self.node_count or dst >= self.node_count) return error.InvalidNode;
            self.matrix.items[src][dst] = if (weighted) weight.? else true;
            if (!directed) {
                self.matrix.items[dst][src] = if (weighted) weight.? else true;
            }
        }

        pub fn removeEdge(self: *@This(), src: usize, dst: usize) !void {
            if (src >= self.node_count or dst >= self.node_count) return error.InvalidNode;
            if (self.matrix.items[src][dst] == if (weighted) null else false)
                return error.EdgeNotFound;

            self.matrix.items[src][dst] = if (weighted) null else false;
            if (!directed) {
                self.matrix.items[dst][src] = if (weighted) null else false;
            }
        }

        pub fn getNeighbors(self: *@This(), node_id: usize) !std.ArrayList(usize) {
            if (node_id >= self.node_count or !self.present_nodes.isSet(node_id)) {
                return error.InvalidNode;
            }

            var neighbors = try std.ArrayList(usize).initCapacity(self.allocator, 0); // 0.16
            errdefer neighbors.deinit(self.allocator);

            for (0..self.matrix.items[node_id].len) |i| {
                if (self.present_nodes.isSet(i)) {
                    const val = self.matrix.items[node_id][i];
                    if (val != if (weighted) null else false) {
                        try neighbors.append(self.allocator, i); // 0.16
                    }
                }
            }
            return neighbors;
        }
    };
}

// -------------------------- Unit Tests --------------------------

test "AdjacencyMatrix: Initialize and Deinitialize" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 5);
    defer matrix.deinit();
    try std.testing.expectEqual(@as(usize, 5), matrix.node_count);
}

test "AdjacencyMatrix: Add and Remove Nodes with Auto-Assigned IDs" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 2);
    defer matrix.deinit();

    const id1 = try matrix.addNode(null);
    const id2 = try matrix.addNode(null);

    try std.testing.expectEqual(@as(usize, 4), matrix.node_count);
    try std.testing.expectEqual(@as(usize, 2), id1);
    try std.testing.expectEqual(@as(usize, 3), id2);

    try matrix.removeNode(id1);
    try std.testing.expectError(error.InvalidNode, matrix.getNeighbors(id1));
}

test "AdjacencyMatrix: Add and Remove Nodes with Explicit ID" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 2);
    defer matrix.deinit();

    _ = try matrix.addNode(5); // Explicit ID
    try std.testing.expectEqual(@as(usize, 6), matrix.node_count);

    _ = try matrix.addNode(2); // Mid-range explicit ID
    try std.testing.expectEqual(@as(usize, 6), matrix.node_count); // Node count should not change

    try matrix.removeNode(2);
    try std.testing.expectError(error.InvalidNode, matrix.getNeighbors(2)); // Node should be removed
}

test "AdjacencyMatrix: Remove Nonexistent Node Returns Error" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try std.testing.expectError(error.InvalidNode, matrix.removeNode(10));
}

test "AdjacencyMatrix: Add and Remove Edges" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try matrix.addEdge(0, 1, 3.5);
    try std.testing.expect(matrix.matrix.items[0][1] != null);

    try matrix.removeEdge(0, 1);
    try std.testing.expect(matrix.matrix.items[0][1] == null);
}

test "AdjacencyMatrix: Remove Nonexistent Edge Returns Error" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try std.testing.expectError(error.EdgeNotFound, matrix.removeEdge(0, 2));
}

test "AdjacencyMatrix: Get Neighbors" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 4);
    defer matrix.deinit();

    // Mark nodes as live (harmless if already live)
    _ = try matrix.addNode(1);
    _ = try matrix.addNode(2);
    _ = try matrix.addNode(3);

    try matrix.addEdge(1, 2, {});
    try matrix.addEdge(1, 3, {});

    var neighbors = try matrix.getNeighbors(1);
    defer neighbors.deinit(std.testing.allocator); // 0.16

    try std.testing.expectEqual(@as(usize, 2), neighbors.items.len);
}

test "AdjacencyMatrix: Get Neighbors of Invalid Node Returns Error" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try std.testing.expectError(error.InvalidNode, matrix.getNeighbors(10));
}

test "AdjacencyMatrix: Self-Loops" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try matrix.addEdge(1, 1, 7.5);
    try std.testing.expect(matrix.matrix.items[1][1] == 7.5);
}

test "AdjacencyMatrix: Adding and Removing a Self-Loop Edge" {
    var matrix = try AdjacencyMatrix(true, true).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try matrix.addEdge(1, 1, 7.5);
    try std.testing.expect(matrix.matrix.items[1][1] == 7.5);

    try matrix.removeEdge(1, 1);
    try std.testing.expect(matrix.matrix.items[1][1] == null);
}

test "AdjacencyMatrix: Add and Remove Many Nodes" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 2);
    defer matrix.deinit();

    var added: usize = 0;
    while (added < 10) : (added += 1) {
        _ = try matrix.addNode(null);
    }

    // Remove 5 distinct live nodes
    var removed: usize = 0;
    var id: usize = 0;
    while (removed < 5 and id < matrix.node_count) : (id += 1) {
        if (matrix.present_nodes.isSet(id)) {
            try matrix.removeNode(id);
            removed += 1;
        }
    }

    const remaining = blk: {
        var count: usize = 0;
        var it = matrix.present_nodes.iterator(.{});
        while (it.next()) |_| {
            count += 1;
        }
        break :blk count;
    };

    try std.testing.expectEqual(@as(usize, 5), remaining);
}

test "AdjacencyMatrix: Remove Last Node" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 3);
    defer matrix.deinit();

    _ = try matrix.addNode(2);
    try matrix.removeNode(2);
    try std.testing.expect(!matrix.present_nodes.isSet(2));
}

test "AdjacencyMatrix: Get Neighbors of Isolated Node" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 3);
    defer matrix.deinit();

    _ = try matrix.addNode(1);

    var neighbors = try matrix.getNeighbors(1);
    defer neighbors.deinit(std.testing.allocator); // 0.16

    try std.testing.expectEqual(@as(usize, 0), neighbors.items.len);
}

test "AdjacencyMatrix: Ensure Node Expansion with Explicit ID" {
    var matrix = try AdjacencyMatrix(true, false).init(std.testing.allocator, 3);
    defer matrix.deinit();

    _ = try matrix.addNode(7);
    _ = try matrix.addNode(2);
    try std.testing.expectEqual(@as(usize, 8), matrix.node_count);

    try matrix.addEdge(7, 2, {});
    var neighbors = try matrix.getNeighbors(7);
    defer neighbors.deinit(std.testing.allocator); // 0.16

    try std.testing.expectEqual(@as(usize, 1), neighbors.items.len);
    try std.testing.expectEqual(@as(usize, 2), neighbors.items[0]);
}

test "AdjacencyMatrix: Undirected Edge Propagation" {
    var matrix = try AdjacencyMatrix(false, false).init(std.testing.allocator, 3);
    defer matrix.deinit();

    try matrix.addEdge(0, 1, {});
    try std.testing.expect(matrix.matrix.items[1][0]); // bidirectional edge exists
}

test "AdjacencyMatrix: Handle Large Graphs" {
    var matrix = try AdjacencyMatrix(false, true).init(std.testing.allocator, 10_000);
    defer matrix.deinit();

    for (0..9_999) |i| {
        try matrix.addEdge(i, i + 1, @floatFromInt(i % 100));
    }

    try std.testing.expectEqual(@as(usize, 10_000), matrix.node_count);
}

test "AdjacencyMatrix: Fully Connected Large Graph" {
    var matrix = try AdjacencyMatrix(false, true).init(std.testing.allocator, 100);
    defer matrix.deinit();

    for (0..100) |i| {
        _ = try matrix.addNode(i);
    }

    for (0..100) |i| {
        for (0..100) |j| {
            if (i != j) try matrix.addEdge(i, j, @floatFromInt(i + j));
        }
    }

    var neighbors = try matrix.getNeighbors(50);
    defer neighbors.deinit(std.testing.allocator); // 0.16

    try std.testing.expectEqual(@as(usize, 99), neighbors.items.len);
}

<<<

`incidence_matrix.zig`: >>>

const std = @import("std");
const Allocator = std.mem.Allocator;
const Thread = std.Thread;

fn createGraph() !IncidenceMatrix(false, true) {
    var block_alloc = try BlockAllocator.init(std.heap.page_allocator, 1024);
    defer block_alloc.deinit();
    const allocator = block_alloc.getAllocator();
    return IncidenceMatrix(false, true).init(allocator, 10);
}

const BlockAllocator = struct {
    allocator: std.mem.Allocator,
    block_size: usize,
    blocks: std.ArrayList([]i8),

    pub fn init(underlying_allocator: std.mem.Allocator, block_size: usize) !BlockAllocator {
        return BlockAllocator{
            .allocator = underlying_allocator,
            .block_size = block_size,
            .blocks = try std.ArrayList([]i8).initCapacity(underlying_allocator, 0), // 0.16
        };
    }

    pub fn getAllocator(self: *BlockAllocator) std.mem.Allocator {
        return self.allocator;
    }

    pub fn allocate(self: *BlockAllocator) ![]i8 {
        const block = try self.allocator.alloc(i8, self.block_size);
        try self.blocks.append(self.allocator, block); // 0.16
        return block;
    }

    pub fn deinit(self: *BlockAllocator) void {
        for (self.blocks.items) |block| {
            self.allocator.free(block);
        }
        self.blocks.deinit(self.allocator); // 0.16
    }
};

/// Incidence Matrix Graph Structure
/// Supports directed/undirected and weighted/unweighted graphs.
/// Uses an incidence matrix for edge representation.
pub fn IncidenceMatrix(comptime directed: bool, comptime weighted: bool) type {
    return struct {
        const Mutex = std.Thread.Mutex;

        allocator: Allocator,
        matrix: std.ArrayList([]if (weighted) ?f64 else i8),
        node_count: usize,
        edge_count: usize,
        edge_set: std.AutoHashMap(struct { usize, usize }, void),
        mutex: Mutex,

        pub fn init(allocator: std.mem.Allocator, initial_capacity: usize) !@This() {
            var matrix = try std.ArrayList([]if (weighted) ?f64 else i8).initCapacity(allocator, initial_capacity); // 0.16

            for (0..initial_capacity) |_| {
                const row = try allocator.alloc(if (weighted) ?f64 else i8, 0);
                try matrix.append(allocator, row); // 0.16
            }

            return @This(){
                .allocator = allocator,
                .matrix = matrix,
                .node_count = initial_capacity,
                .edge_count = 0,
                .edge_set = std.AutoHashMap(struct { usize, usize }, void).init(allocator),
                .mutex = Mutex{},
            };
        }

        pub fn deinit(self: *@This()) void {
            for (self.matrix.items) |row| {
                self.allocator.free(row);
            }
            self.matrix.deinit(self.allocator); // 0.16
            self.edge_set.deinit();
        }

        fn resizeMatrix(self: *@This(), node_id: usize, new_capacity: usize) !void {
            if (node_id >= self.node_count) return error.InvalidNode;

            if (self.matrix.items[node_id].len < new_capacity) {
                self.matrix.items[node_id] = try self.allocator.realloc(self.matrix.items[node_id], new_capacity);
                @memset(self.matrix.items[node_id][self.edge_count..new_capacity], if (weighted) null else 0);
            }
        }

        pub fn addNode(self: *@This()) !usize {
            const new_id = self.node_count;
            self.node_count += 1;

            const new_row = try self.allocator.alloc(if (weighted) ?f64 else i8, self.edge_count);
            @memset(new_row, if (weighted) @as(?f64, null) else @as(i8, 0));

            try self.matrix.append(self.allocator, new_row); // 0.16

            return new_id;
        }

        pub fn removeNode(self: *@This(), node_id: usize) !void {
            if (node_id >= self.node_count) return error.InvalidNode;

            self.mutex.lock();
            defer self.mutex.unlock();

            var it = self.edge_set.iterator();
            while (it.next()) |entry| {
                const key = entry.key_ptr.*;
                if (key[0] == node_id or key[1] == node_id) {
                    _ = self.edge_set.remove(key);
                }
            }

            self.allocator.free(self.matrix.items[node_id]);
            _ = self.matrix.orderedRemove(node_id);

            self.node_count -= 1;
        }

        pub fn addEdge(self: *@This(), src: usize, dst: usize, weight: if (weighted) ?f64 else void) !usize {
            if (src >= self.node_count or dst >= self.node_count) return error.InvalidNode;

            self.mutex.lock();
            defer self.mutex.unlock();

            if (self.edge_set.contains(.{ src, dst })) return error.EdgeAlreadyExists;

            // ✅ Ensure rows are large enough
            try self.resizeMatrix(src, self.edge_count + 1);
            try self.resizeMatrix(dst, self.edge_count + 1);

            if (weighted) {
                self.matrix.items[src][self.edge_count] = weight.?;
                self.matrix.items[dst][self.edge_count] = if (directed) -weight.? else weight.?;
            } else {
                self.matrix.items[src][self.edge_count] = 1;
                self.matrix.items[dst][self.edge_count] = if (directed) -1 else 1;
            }

            try self.edge_set.put(.{ src, dst }, {});
            if (!directed) {
                try self.edge_set.put(.{ dst, src }, {});
            }

            self.edge_count += 1;

            return self.edge_count - 1;
        }

        pub fn hasEdge(self: *@This(), src: usize, dst: usize) bool {
            if (src >= self.node_count or dst >= self.node_count) return false;

            if (self.edge_set.contains(.{ src, dst })) {
                return true;
            }

            for (0..self.edge_count) |edge_id| {
                if (self.matrix.items[src].len > edge_id and self.matrix.items[dst].len > edge_id) {
                    if ((weighted and self.matrix.items[src][edge_id] != null) or (!weighted and self.matrix.items[src][edge_id] != 0)) {
                        return true;
                    }
                }
            }

            return false;
        }

        pub fn updateEdgeWeight(self: *@This(), src: usize, dst: usize, new_weight: f64) !void {
            if (!weighted) return error.GraphNotWeighted;
            if (!self.hasEdge(src, dst)) return error.EdgeDoesNotExist;

            self.mutex.lock(); // 🔒 Ensure thread safety
            defer self.mutex.unlock();

            self.matrix.items[src][self.edge_count - 1] = new_weight;
            self.matrix.items[dst][self.edge_count - 1] = if (directed) -new_weight else new_weight;
        }

        pub fn reserveEdges(self: *@This(), additional_edges: usize) !void {
            const new_capacity = self.edge_count + additional_edges;

            for (0..self.node_count) |node_id| {
                try self.resizeMatrix(node_id, new_capacity);
            }
        }

        pub fn prepareParallelEdges(self: *@This(), additional_edges: usize) !void {
            self.mutex.lock();
            defer self.mutex.unlock();

            for (0..self.node_count) |node_id| {
                try self.resizeMatrix(node_id, self.edge_count + additional_edges);
            }
        }

        pub fn addEdgesParallel(self: *@This(), start: usize, end: usize) !void {
            const num_threads = try std.Thread.getCpuCount();
            var threads = try std.ArrayList(std.Thread).initCapacity(self.allocator, num_threads);
            defer threads.deinit(self.allocator); // 0.16

            // Precompute batches
            var batches = try self.allocator.alloc(std.ArrayList(struct { usize, usize }), num_threads);
            defer self.allocator.free(batches);

            for (0..num_threads) |i| {
                batches[i] = try std.ArrayList(struct { usize, usize }).initCapacity(self.allocator, 0); // 0.16
                errdefer batches[i].deinit(self.allocator);
            }

            for (start..end) |i| {
                for (i + 1..self.node_count) |j| {
                    try batches[i % num_threads].append(self.allocator, .{ i, j }); // 0.16
                }
            }

            for (0..num_threads) |i| {
                try threads.append(self.allocator, try std.Thread.spawn(.{}, worker, .{ self, batches[i].items })); // 0.16
            }

            for (threads.items) |*thread| {
                thread.join();
            }

            for (0..num_threads) |i| {
                batches[i].deinit(self.allocator); // 0.16
            }
        }

        pub fn worker(graph: *IncidenceMatrix(false, false), edges: []struct { usize, usize }) void {
            var count: usize = 0;
            for (edges) |edge| {
                _ = graph.addEdge(edge[0], edge[1], {}) catch |err| {
                    if (err == error.EdgeAlreadyExists) continue;
                    continue;
                };
                count += 1;
            }
        }

        pub fn removeEdge(self: *@This(), edge_id: usize) !void {
            if (edge_id >= self.edge_count) return; // ✅ Prevent out-of-bounds removal

            self.mutex.lock();
            defer self.mutex.unlock();

            // Collect edges to remove
            var edges_to_remove = try std.ArrayList(struct { usize, usize }).initCapacity(self.allocator, 0); // 0.16
            defer edges_to_remove.deinit(self.allocator);

            var it = self.edge_set.iterator();
            while (it.next()) |entry| {
                const key = entry.key_ptr.*;
                if (self.matrix.items[key[0]].len > edge_id and self.matrix.items[key[1]].len > edge_id) {
                    try edges_to_remove.append(self.allocator, key); // 0.16
                }
            }

            // Remove collected edges
            for (edges_to_remove.items) |edge| {
                _ = self.edge_set.remove(edge);
                if (!directed) {
                    _ = self.edge_set.remove(.{ edge[1], edge[0] }); // ✅ Remove reverse for undirected graphs
                }
            }

            // ✅ Shift adjacency matrix elements left to remove the edge
            for (self.matrix.items) |*row| {
                if (row.*.len > 0 and edge_id < row.*.len - 1) { // 🔥 Fix integer overflow
                    @memcpy(row.*[edge_id .. row.*.len - 1], row.*[edge_id + 1 ..]);
                }

                if (row.*.len > 0) { // 🔥 Only shrink if there's something left
                    row.* = try self.allocator.realloc(row.*, row.*.len - 1);
                }
            }

            self.edge_count -= 1;
        }

        pub fn getNeighbors(self: *@This(), node_id: usize) !std.ArrayList(usize) {
            if (node_id >= self.node_count) return error.InvalidNode;

            var neighbors = try std.ArrayList(usize).initCapacity(self.allocator, 0); // 0.16
            errdefer neighbors.deinit(self.allocator);

            var seen = std.AutoHashMap(usize, bool).init(self.allocator);
            defer seen.deinit();

            var it = self.edge_set.iterator();
            while (it.next()) |entry| {
                const key = entry.key_ptr.*;
                if (key[0] == node_id) {
                    if (!seen.contains(key[1])) {
                        try seen.put(key[1], true);
                        try neighbors.append(self.allocator, key[1]); // 0.16
                    }
                } else if (key[1] == node_id) {
                    if (!seen.contains(key[0])) {
                        try seen.put(key[0], true);
                        try neighbors.append(self.allocator, key[0]); // 0.16
                    }
                }
            }

            return neighbors;
        }

        pub fn toAdjacencyList(self: *@This()) !std.AutoHashMap(usize, std.ArrayList(usize)) {
            var adj_list = std.AutoHashMap(usize, std.ArrayList(usize)).init(self.allocator);
            errdefer adj_list.deinit();

            for (0..self.node_count) |node| {
                const neighbors = try self.getNeighbors(node);
                try adj_list.put(node, neighbors);
            }

            return adj_list;
        }
    };
}

fn getRandomNode(max: usize) usize {
    var buf: u64 = undefined;
    std.crypto.random.bytes(std.mem.asBytes(&buf)); // Fill the `u64` buffer with random bytes
    return @as(usize, buf % max); // Ensure the value is within range
}

// ------------------------------- Tests -------------------------------

test "IncidenceMatrix: Initialize and Deinitialize" {
    std.debug.print("\n====== Test: Initialization ======\n", .{});
    const allocator = std.heap.page_allocator;
    var matrix = try IncidenceMatrix(true, true).init(allocator, 5);
    defer matrix.deinit();

    try std.testing.expectEqual(@as(usize, 5), matrix.node_count);
    try std.testing.expectEqual(@as(usize, 0), matrix.edge_count);
}

test "IncidenceMatrix: Add and Remove Nodes" {
    const allocator = std.heap.page_allocator;
    var matrix = try IncidenceMatrix(true, true).init(allocator, 2);
    defer matrix.deinit();

    const id = try matrix.addNode();
    try std.testing.expectEqual(@as(usize, 3), matrix.node_count);
    try std.testing.expect(id == 2);
}

test "IncidenceMatrix: Add and Remove Edges" {
    const allocator = std.heap.page_allocator;
    var matrix = try IncidenceMatrix(true, true).init(allocator, 3);
    defer matrix.deinit();

    const edge_id = try matrix.addEdge(0, 1, 3.5);
    try std.testing.expectEqual(@as(usize, 1), matrix.edge_count);

    try matrix.removeEdge(edge_id);
    try std.testing.expectEqual(@as(usize, 0), matrix.edge_count);
}

test "IncidenceMatrix: Get Neighbors" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(false, false).init(allocator, 4);
    defer matrix.deinit();

    _ = try matrix.addEdge(1, 2, {});
    _ = try matrix.addEdge(1, 3, {});

    var neighbors = try matrix.getNeighbors(1);
    defer neighbors.deinit(allocator); // 0.16

    // ✅ Ensure we have exactly 2 neighbors
    try std.testing.expectEqual(@as(usize, 2), neighbors.items.len);

    // ✅ Ensure both 2 and 3 exist, regardless of order
    try std.testing.expect((neighbors.items[0] == 2 and neighbors.items[1] == 3) or
        (neighbors.items[0] == 3 and neighbors.items[1] == 2));
}

test "IncidenceMatrix: Get Neighbors (Debug Check)" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(false, false).init(allocator, 4);
    defer matrix.deinit();

    _ = try matrix.addEdge(1, 2, {});
    _ = try matrix.addEdge(1, 3, {});

    var neighbors = try matrix.getNeighbors(1);
    defer neighbors.deinit(allocator); // 0.16

    // ✅ Ensure exactly 2 neighbors
    try std.testing.expectEqual(@as(usize, 2), neighbors.items.len);

    // ✅ Check that both 2 and 3 exist, regardless of order
    try std.testing.expect((neighbors.items[0] == 2 and neighbors.items[1] == 3) or
        (neighbors.items[0] == 3 and neighbors.items[1] == 2));
}

test "IncidenceMatrix: Invalid Node in AddEdge" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(true, true).init(allocator, 3);
    defer matrix.deinit();

    const result = matrix.addEdge(0, 10, 2.5);
    try std.testing.expectError(error.InvalidNode, result);
}

test "IncidenceMatrix: Invalid Edge Removal" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(true, true).init(allocator, 3);
    defer matrix.deinit();

    try matrix.removeEdge(10); // ✅ Should not panic
}

test "IncidenceMatrix: Directed Edge Correctness" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(true, false).init(allocator, 3);
    defer matrix.deinit();

    _ = try matrix.addEdge(0, 1, {});

    if (matrix.matrix.items.len > 0) {
        try std.testing.expectEqual(@as(i8, 1), matrix.matrix.items[0][0]);
    } else return error.RowNotAllocated;

    if (matrix.matrix.items.len > 1) {
        try std.testing.expectEqual(@as(i8, -1), matrix.matrix.items[1][0]);
    } else return error.RowNotAllocated;
}

test "IncidenceMatrix: Weighted Edge Correctness" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(true, true).init(allocator, 3);
    defer matrix.deinit();

    _ = try matrix.addEdge(0, 1, 7.5);

    if (matrix.matrix.items.len > 0) {
        try std.testing.expectEqual(@as(f64, 7.5), matrix.matrix.items[0][0]);
    } else return error.RowNotAllocated;

    if (matrix.matrix.items.len > 1) {
        try std.testing.expectEqual(@as(f64, -7.5), matrix.matrix.items[1][0]);
    } else return error.RowNotAllocated;
}

test "IncidenceMatrix: High-Precision Edge Weights" {
    var matrix = try IncidenceMatrix(true, true).init(std.heap.page_allocator, 5);
    defer matrix.deinit();

    _ = try matrix.addEdge(0, 1, 1.0000001);
    _ = try matrix.addEdge(1, 2, 3.1415926535);

    try std.testing.expectEqual(@as(f64, 1.0000001), matrix.matrix.items[0][0]);
    try std.testing.expectEqual(@as(f64, -3.1415926535), matrix.matrix.items[2][1]);
}

test "IncidenceMatrix: Large Fully Connected Graph" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    var matrix = try IncidenceMatrix(false, false).init(allocator, 100);
    defer matrix.deinit();

    for (0..100) |i| {
        for (i + 1..100) |j| {
            _ = try matrix.addEdge(i, j, {});
        }
    }

    try std.testing.expectEqual(@as(usize, 100 * 99 / 2), matrix.edge_count);
}

test "IncidenceMatrix: Large Dense Graph (Optimized)" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    const node_count = 100;
    var matrix = try IncidenceMatrix(false, true).init(allocator, node_count);
    defer matrix.deinit();

    for (0..node_count) |i| {
        for (i + 1..node_count) |j| {
            _ = try matrix.addEdge(i, j, @floatFromInt(i + j));
        }
    }

    try std.testing.expectEqual(@as(usize, node_count * (node_count - 1) / 2), matrix.edge_count);
}

test "IncidenceMatrix: Large Dense Graph (Parallel, Optimized)" {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){}; // ✅ Use GPA for parallel test
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();

    const node_count = 100;
    var matrix = try IncidenceMatrix(false, false).init(allocator, node_count);
    defer matrix.deinit();

    try matrix.prepareParallelEdges(node_count * (node_count - 1) / 2);

    // **✅ New Parallel Edge Processing**
    try matrix.addEdgesParallel(0, node_count);

    try std.testing.expectEqual(@as(usize, node_count * (node_count - 1) / 2), matrix.edge_count);
}

test "IncidenceMatrix: Massive Graph Stress Test" {
    var matrix = try IncidenceMatrix(false, false).init(std.heap.page_allocator, 1000);
    defer matrix.deinit();

    for (0..1000) |i| {
        for (i + 1..1000) |j| {
            _ = try matrix.addEdge(i, j, {});
        }
    }

    try std.testing.expectEqual(@as(usize, 1000 * 999 / 2), matrix.edge_count);
}

<<<

`adjacency_matrix_vram.zig`: >>>

// GPU-resident adjacency matrix (for small dense graphs)

<<<

`compressed_sparse_column.zig`: >>>

// CSC format (dual to CSR)

<<<

`compressed_sparse_row.zig`: >>>

// CSR format for GPU graph processing

<<<

`gpu_graph.zig`: >>>

// Wrapper to manage GPU-accelerated graphs

<<<

`edge.zig`: >>>

const std = @import("std");

/// 🚀 Flexible Value Type for Edge Metadata
const ValueType = union(enum) {
    int: i64,
    float: f64,
    boolean: bool,
    string: []const u8, // ✅ Only allocate strings when necessary
};

/// 🚀 Generic Edge Definition with Arbitrary Data Support
pub fn Edge(comptime weighted: bool) type {
    return struct {
        src: u64,
        dst: u64,
        data: std.StringHashMap(ValueType), // ✅ FIXED: Proper HashMap for Strings
        weight: if (weighted) f64 else void,
        allocator: std.mem.Allocator,

        /// 🚀 Initialize Edge
        pub fn init(allocator: std.mem.Allocator, src: u64, dst: u64, weight: if (weighted) f64 else void) !@This() {
            return @This(){
                .src = src,
                .dst = dst,
                .data = std.StringHashMap(ValueType).init(allocator), // ✅ FIXED
                .weight = if (weighted) weight else {},
                .allocator = allocator,
            };
        }

        /// 🚀 Deinitialize Edge (Prevent Memory Leaks)
        pub fn deinit(self: *@This()) void {
            var iter = self.data.iterator();
            while (iter.next()) |entry| {
                self.allocator.free(entry.key_ptr.*);
                if (entry.value_ptr.* == .string) { // ✅ Only free memory for string values
                    self.allocator.free(entry.value_ptr.string);
                }
            }
            self.data.deinit();
        }

        /// 🚀 Set Data with Proper Memory Management
        /// 🚀 Set Data with Proper Memory Management
        pub fn setData(self: *@This(), key: []const u8, value: ValueType) !void {
            if (key.len == 0) return error.InvalidKey; // Prevent empty keys

            // ✅ Free existing value if present
            if (self.data.getPtr(key)) |existing_value| {
                if (existing_value.* == .string) {
                    self.allocator.free(existing_value.string);
                }
            }

            // ✅ Fetch the stored key
            var old_key: ?[]const u8 = null;
            if (self.data.getKeyPtr(key)) |key_ptr| {
                old_key = key_ptr.*;
            }

            // ✅ Remove old key-value pair before inserting a new one
            if (self.data.remove(key)) {
                if (old_key) |key_ptr| {
                    self.allocator.free(key_ptr);
                }
            }

            // ✅ Allocate new key and value
            const key_dup: []const u8 = try self.allocator.dupe(u8, key);
            var value_dup: ValueType = value;

            if (value == .string) {
                value_dup.string = try self.allocator.dupe(u8, value.string);
            }

            try self.data.put(key_dup, value_dup);
        }

        /// 🚀 Retrieve Data (Efficient Pointer-Based Access)
        pub fn getData(self: *@This(), key: []const u8) ?*const ValueType {
            return self.data.getPtr(key);
        }

        /// 🚀 Remove Data (Properly Frees Allocated Strings)
        pub fn removeData(self: *@This(), key: []const u8) !void {
            if (key.len == 0) return error.InvalidKey; // 🚀 Prevents empty keys

            // ✅ Retrieve value before removing
            if (self.data.getPtr(key)) |value| {
                if (value.* == .string) {
                    self.allocator.free(value.string);
                }
            }

            // ✅ Fetch the key stored in the hashmap
            var old_key: ?[]const u8 = null;
            if (self.data.getKeyPtr(key)) |key_ptr| {
                old_key = key_ptr.*;
            }

            // ✅ Remove key-value pair
            if (self.data.remove(key)) {
                if (old_key) |key_ptr| {
                    self.allocator.free(key_ptr);
                }
            } else {
                return error.KeyNotFound; // 🚀 Explicitly return an error if key is missing
            }
        }

        /// 🚀 Debug Print (Handles All `ValueType` Cases)
        pub fn debugPrint(self: *const @This()) void {
            if (weighted) {
                std.debug.print("Edge {} -> {} (Weight: {d})\n", .{ self.src, self.dst, self.weight });
            } else {
                std.debug.print("Edge {} -> {}\n", .{ self.src, self.dst });
            }

            var iter = self.data.iterator();
            while (iter.next()) |entry| {
                std.debug.print("  {s}: ", .{entry.key_ptr.*});

                switch (entry.value_ptr.*) {
                    .int => |v| std.debug.print("{}\n", .{v}),
                    .float => |v| std.debug.print("{d}\n", .{v}),
                    .boolean => |v| std.debug.print("{}\n", .{v}),
                    .string => |v| std.debug.print("\"{s}\"\n", .{v}),
                }
            }
        }
    };
}

// ✅ Unit Test for Proper Memory Management & Error Debugging
test "Edge: Memory Management" {
    const allocator = std.testing.allocator;

    // ✅ Weighted Edge
    const WeightedEdge = Edge(true);
    var e = try WeightedEdge.init(allocator, 1, 2, 5.7);
    defer e.deinit(); // ✅ Ensure cleanup

    try e.setData("type", ValueType{ .string = "friendship" });

    std.testing.expectEqual(@as(u64, 1), e.src) catch |err| {
        std.debug.print("[TEST FAILURE] WeightedEdge Debug:\n", .{});
        e.debugPrint();
        return err;
    };

    std.testing.expectEqual(@as(u64, 2), e.dst) catch |err| {
        std.debug.print("[TEST FAILURE] WeightedEdge Debug:\n", .{});
        e.debugPrint();
        return err;
    };

    std.testing.expectEqual(@as(f64, 5.7), e.weight) catch |err| {
        std.debug.print("[TEST FAILURE] WeightedEdge Debug:\n", .{});
        e.debugPrint();
        return err;
    };

    std.testing.expectEqualStrings("friendship", e.getData("type").?.string) catch |err| {
        std.debug.print("[TEST FAILURE] WeightedEdge Debug:\n", .{});
        e.debugPrint();
        return err;
    };

    // ✅ Unweighted Edge
    const UnweightedEdge = Edge(false);
    var e2 = try UnweightedEdge.init(allocator, 3, 4, {});
    defer e2.deinit(); // ✅ Ensure cleanup

    try e2.setData("type", ValueType{ .string = "follows" });

    std.testing.expectEqual(@as(u64, 3), e2.src) catch |err| {
        std.debug.print("[TEST FAILURE] UnweightedEdge Debug:\n", .{});
        e2.debugPrint();
        return err;
    };

    std.testing.expectEqual(@as(u64, 4), e2.dst) catch |err| {
        std.debug.print("[TEST FAILURE] UnweightedEdge Debug:\n", .{});
        e2.debugPrint();
        return err;
    };

    std.testing.expectEqualStrings("follows", e2.getData("type").?.string) catch |err| {
        std.debug.print("[TEST FAILURE] UnweightedEdge Debug:\n", .{});
        e2.debugPrint();
        return err;
    };
}

// ✅ Debug Print Test (Only Runs If the Test Fails)
test "Edge: Debug Print" {
    const allocator = std.testing.allocator;
    const TestEdge = Edge(true);
    var e = try TestEdge.init(allocator, 10, 20, 3.14);
    defer e.deinit();

    std.testing.expectEqual(@as(f64, 3.14), e.weight) catch |err| {
        std.debug.print("[TEST FAILURE] Edge Debug Print:\n", .{});
        e.debugPrint();
        return err;
    };
}

// ✅ Additional Tests: Ensure removeData() handles errors
test "Edge: Remove Data" {
    const allocator = std.testing.allocator;
    const TestEdge = Edge(true);
    var e = try TestEdge.init(allocator, 1, 2, 5.7);
    defer e.deinit();

    try e.setData("type", ValueType{ .string = "friendship" });

    try e.removeData("type"); // ✅ Try to remove existing key
    try std.testing.expect(e.getData("type") == null);

    // ✅ Try to remove a non-existent key and expect a KeyNotFound error
    try std.testing.expectError(error.KeyNotFound, e.removeData("non_existent"));
}

test "Edge: Overwrite Stress Test" {
    const allocator = std.testing.allocator;
    const TestEdge = Edge(true);
    var e = try TestEdge.init(allocator, 1, 2, 5.7);
    defer e.deinit();

    try e.setData("status", ValueType{ .string = "initial" });
    try e.setData("status", ValueType{ .string = "updated" });
    try e.setData("status", ValueType{ .string = "final" });

    // ✅ Ensure the key still exists
    const status_opt = e.getData("status") orelse return error.StatusNotFound;
    if (status_opt.* != .string) return error.UnexpectedValueType;

    try std.testing.expectEqualStrings("final", status_opt.string);
}

<<<

`graph_storage.zig`: >>>

const std = @import("std");
const testing = std.testing;
const Allocator = std.mem.Allocator;

pub const GraphStorageType = enum {
    AdjacencyList,
    AdjacencyMatrix,
    IncidenceMatrix,
};

/// Generic Graph Storage Abstraction
pub fn GraphStorage(comptime storage_type: GraphStorageType, comptime directed: bool, comptime weighted: bool) type {
    return switch (storage_type) {
        .AdjacencyList => @import("../data_structures/adjacency_list.zig").AdjacencyList(directed, weighted),
        .AdjacencyMatrix => @import("../data_structures/adjacency_matrix.zig").AdjacencyMatrix(directed, weighted),
        .IncidenceMatrix => @import("../data_structures/incidence_matrix.zig").IncidenceMatrix(directed, weighted),
    };
}

test "GraphStorage: Ensure Each Type Instantiates Correctly" {
    const allocator = testing.allocator;
    const initial_capacity = 100; // Required for AdjacencyMatrix & IncidenceMatrix

    inline for (std.meta.fields(GraphStorageType)) |field| {
        const storage_type: GraphStorageType = @field(GraphStorageType, field.name);
        const Storage = GraphStorage(storage_type, true, true);

        var storage = if (storage_type == .AdjacencyList)
            Storage.init(allocator)
        else
            try Storage.init(allocator, initial_capacity);

        defer if (@hasDecl(Storage, "deinit")) storage.deinit();

        try testing.expect(@TypeOf(storage) == Storage);
    }
}

test "GraphStorage: Ensure Nodes Can Be Added and Removed" {
    const allocator = testing.allocator;
    const Storage = GraphStorage(GraphStorageType.AdjacencyList, true, true);

    var storage = Storage.init(allocator);
    defer if (@hasDecl(Storage, "deinit")) storage.deinit();

    try storage.addNode(1);
    try testing.expect(storage.getNeighbors(1) != null);
    try storage.removeNode(1);
    try testing.expect(storage.getNeighbors(1) == null);
}

test "GraphStorage: Ensure Different Storage Types Work Independently" {
    const allocator = testing.allocator;
    const initial_capacity = 100;

    const StorageA = GraphStorage(GraphStorageType.AdjacencyList, true, true);
    const StorageB = GraphStorage(GraphStorageType.AdjacencyMatrix, true, true);

    var storage_a = StorageA.init(allocator);
    defer if (@hasDecl(StorageA, "deinit")) storage_a.deinit();

    var storage_b = try StorageB.init(allocator, initial_capacity);
    defer if (@hasDecl(StorageB, "deinit")) storage_b.deinit();

    _ = try storage_a.addNode(1);
    _ = try storage_b.addNode(1);

    // AdjacencyList: returns ?ArrayList
    {
        const maybe_neighbors_a = storage_a.getNeighbors(1);
        try testing.expect(maybe_neighbors_a != null);
        if (maybe_neighbors_a) |neighbors_a_const| {
            var neighbors_a = neighbors_a_const; // make mutable copy for deinit
            defer neighbors_a.deinit(allocator);
            try testing.expect(neighbors_a.items.len >= 0);
        }
    }

    // AdjacencyMatrix: returns !ArrayList
    {
        var neighbors_b = try storage_b.getNeighbors(1); // mutable
        defer neighbors_b.deinit(allocator);
        try testing.expect(neighbors_b.items.len >= 0);
    }

    try storage_a.removeNode(1);

    {
        try testing.expect(storage_a.getNeighbors(1) == null);
    }

    {
        var neighbors_b = try storage_b.getNeighbors(1); // mutable
        defer neighbors_b.deinit(allocator);
        try testing.expect(neighbors_b.items.len >= 0);
    }
}

test "GraphStorage: Debug Print Should Not Crash" {
    const allocator = testing.allocator;
    const initial_capacity = 100;
    const Storage = GraphStorage(GraphStorageType.IncidenceMatrix, true, true);

    var storage = try Storage.init(allocator, initial_capacity);
    defer if (@hasDecl(Storage, "deinit")) storage.deinit();

    if (@hasDecl(Storage, "debugPrint")) {
        storage.debugPrint();
    }
}

<<<

`graph.zig`: >>>

const std = @import("std");

pub fn Graph(comptime weighted: bool, comptime Storage: type) type {
    return struct {
        allocator: std.mem.Allocator,
        storage: Storage,
        heterogeneous: bool, // ✅ Restore heterogeneous support
        node_types: ?std.AutoHashMap(u64, []const u8), // ✅ Only allocated if converted to heterogeneous
        edge_types: ?std.AutoHashMap(u64, []const u8), // ✅ Only allocated if converted to heterogeneous

        /// 🚀 Initialize Graph with Chosen Storage
        pub fn init(allocator: std.mem.Allocator) @This() {
            return @This(){
                .allocator = allocator,
                .storage = Storage.init(allocator),
                .heterogeneous = false, // ✅ Default to homogeneous
                .node_types = null,
                .edge_types = null,
            };
        }

        /// 🚀 Deinitialize Graph
        pub fn deinit(self: *@This()) void {
            if (self.heterogeneous) {
                if (self.node_types) |*nt| {
                    var it = nt.iterator();
                    while (it.next()) |entry| {
                        self.allocator.free(entry.value_ptr.*);
                    }
                    nt.deinit();
                }

                if (self.edge_types) |*et| {
                    var it = et.iterator();
                    while (it.next()) |entry| {
                        self.allocator.free(entry.value_ptr.*);
                    }
                    et.deinit();
                }
            }

            self.storage.deinit();
        }

        /// 🚀 Convert Graph to Heterogeneous (Explicit User Action)
        pub fn convertToHeterogeneous(self: *@This()) !void {
            if (self.heterogeneous) return error.AlreadyHeterogeneous;
            self.node_types = std.AutoHashMap(u64, []const u8).init(self.allocator);
            self.edge_types = std.AutoHashMap(u64, []const u8).init(self.allocator);
            self.heterogeneous = true;
        }

        /// 🚀 Add Node (Supports Heterogeneous Graphs)
        pub fn addNode(self: *@This(), id: u64, label: []const u8, node_type: ?[]const u8) !void {
            try self.storage.addNode(id, label); // Ensure label is used!

            if (self.heterogeneous) {
                if (node_type == null) return error.MissingNodeType;
                const allocated_type = try self.allocator.dupe(u8, node_type.?);
                try self.node_types.?.put(id, allocated_type);
            } else if (node_type != null) {
                return error.GraphIsHomogeneous;
            }
        }

        pub fn removeNode(self: *@This(), node_id: u64) !void {
            try self.storage.removeNode(node_id);
            if (self.heterogeneous) {
                _ = self.node_types.?.remove(node_id);
            }
        }

        /// 🚀 Add Edge (Supports Heterogeneous Graphs)
        pub fn addEdge(self: *@This(), src: u64, dst: u64, weight: if (weighted) ?f64 else void, edge_type: ?[]const u8) !void {
            try self.storage.addEdge(src, dst, weight);

            if (self.heterogeneous) {
                if (edge_type == null) return error.MissingEdgeType;
                const edge_key = generateEdgeKey(src, dst);
                const hashed_key = hashEdgeKey(edge_key);
                const allocated_edge_type = try self.allocator.dupe(u8, edge_type.?);
                try self.edge_types.?.put(hashed_key, allocated_edge_type);
            } else if (edge_type != null) {
                return error.GraphIsHomogeneous;
            }
        }

        pub fn removeEdge(self: *@This(), src: u64, dst: u64) !void {
            try self.storage.removeEdge(src, dst);
            if (self.heterogeneous) {
                const edge_key = generateEdgeKey(src, dst);
                const hashed_key = hashEdgeKey(edge_key);
                _ = self.edge_types.?.remove(hashed_key);
            }
        }

        /// 🚀 Get Node Type (for Heterogeneous Graphs)
        pub fn getNodeType(self: *const @This(), id: u64) ?[]const u8 {
            if (!self.heterogeneous) return null;
            return self.node_types.?.get(id);
        }

        /// 🚀 Get Edge Type (for Heterogeneous Graphs)
        pub fn getEdgeType(self: *@This(), src: u64, dst: u64) ?[]const u8 {
            if (!self.heterogeneous) return null;
            const edge_key = generateEdgeKey(src, dst);
            const hashed_key = hashEdgeKey(edge_key);
            return self.edge_types.?.get(hashed_key);
        }

        /// 🚀 Debug Print (for Visualization)
        pub fn debugPrint(self: *@This()) void {
            std.debug.print("Graph:\n", .{});
            self.storage.debugPrint();

            if (self.heterogeneous) {
                std.debug.print("  Heterogeneous Node Types:\n", .{});
                var node_it = self.node_types.?.iterator();
                while (node_it.next()) |entry| {
                    std.debug.print("    Node {}: Type \"{s}\"\n", .{ entry.key_ptr.*, entry.value_ptr.* });
                }

                std.debug.print("  Heterogeneous Edge Types:\n", .{});
                var edge_it = self.edge_types.?.iterator();
                while (edge_it.next()) |entry| {
                    std.debug.print("    Edge Hash {}: Type \"{s}\"\n", .{ entry.key_ptr.*, entry.value_ptr.* });
                }
            }
        }

        /// 🚀 Helper Functions
        fn generateEdgeKey(src: u64, dst: u64) u128 {
            return (@as(u128, src) << 64) | dst;
        }

        fn hashEdgeKey(edge_key: u128) u64 {
            return std.hash.Wyhash.hash(0, std.mem.asBytes(&edge_key));
        }
    };
}

// test "Graph: Initialize and Deinitialize" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     if (g.nodes.count() != 0 or g.edges.count() != 0) {
//         std.debug.print("\n[ERROR] Graph should be empty on initialization! Nodes: {d}, Edges: {d}\n", .{ g.nodes.count(), g.edges.count() });
//     }

//     try std.testing.expectEqual(@as(usize, 0), g.nodes.count());
//     try std.testing.expectEqual(@as(usize, 0), g.edges.count());
// }

// test "Graph: Add Nodes (Homogeneous)" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "NodeA", null);
//     try g.addNode(2, "NodeB", null);

//     if (!g.nodes.contains(1) or !g.nodes.contains(2)) {
//         std.debug.print("\n[ERROR] Nodes not added correctly! Node 1 exists: {any}, Node 2 exists: {any}\n", .{ g.nodes.contains(1), g.nodes.contains(2) });
//     }

//     try std.testing.expect(g.nodes.contains(1));
//     try std.testing.expect(g.nodes.contains(2));
// }

// test "Graph: Add Nodes (Heterogeneous)" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.convertToHeterogeneous();
//     try g.addNode(1, "NodeA", "TypeA");
//     try g.addNode(2, "NodeB", "TypeB");

//     if (g.getNodeType(1) == null or g.getNodeType(2) == null) {
//         std.debug.print("\n[ERROR] Node types missing! Node 1 Type: {?s}, Node 2 Type: {?s}\n", .{ g.getNodeType(1), g.getNodeType(2) });
//     }

//     try std.testing.expectEqualStrings("TypeA", g.getNodeType(1).?);
//     try std.testing.expectEqualStrings("TypeB", g.getNodeType(2).?);
// }

// test "Graph: Remove Node" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "NodeA", null);
//     try g.addNode(2, "NodeB", null);
//     try g.addEdge(1, 2, 3.5, null);

//     g.removeNode(1);

//     if (g.nodes.contains(1)) {
//         std.debug.print("\n[ERROR] Node 1 was not removed!\n", .{});
//     }

//     if (g.edges.get(1) != null) {
//         std.debug.print("\n[ERROR] Edges from Node 1 were not removed!\n", .{});
//     }

//     try std.testing.expect(!g.nodes.contains(1));
//     try std.testing.expect(g.edges.get(1) == null);
// }

// test "Graph: Add and Remove Edges (Homogeneous Directed)" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "NodeA", null);
//     try g.addNode(2, "NodeB", null);
//     try g.addEdge(1, 2, 3.5, null);

//     if (!g.edges.contains(1)) {
//         std.debug.print("\n[ERROR] Edge 1 -> 2 was not added!\n", .{});
//     }

//     try std.testing.expect(g.edges.contains(1));
//     try std.testing.expectEqual(@as(usize, 1), g.edges.get(1).?.items.len);

//     g.removeEdge(1, 2);

//     if (g.edges.contains(1)) {
//         std.debug.print("\n[ERROR] Edge 1 -> 2 was not removed!\n", .{});
//     }

//     try std.testing.expectEqual(@as(usize, 0), if (g.edges.get(1)) |e| e.items.len else 0);
// }

// test "Graph: Add and Remove Edges (Homogeneous Undirected)" {
//     var g = Graph(false, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "NodeA", null);
//     try g.addNode(2, "NodeB", null);
//     try g.addEdge(1, 2, 3.5, null);

//     if (!g.edges.contains(1) or !g.edges.contains(2)) {
//         std.debug.print("\n[ERROR] Undirected edges not added properly! Edges from 1: {any}, Edges from 2: {any}\n", .{ g.edges.get(1), g.edges.get(2) });
//     }

//     try std.testing.expectEqual(@as(usize, 1), g.edges.get(1).?.items.len);
//     try std.testing.expectEqual(@as(usize, 1), g.edges.get(2).?.items.len);

//     g.removeEdge(1, 2);

//     if (g.edges.contains(1) or g.edges.contains(2)) {
//         std.debug.print("\n[ERROR] Undirected edge 1 <-> 2 was not removed properly!\n", .{});
//     }

//     try std.testing.expectEqual(@as(usize, 0), if (g.edges.get(1)) |e| e.items.len else 0);
//     try std.testing.expectEqual(@as(usize, 0), if (g.edges.get(2)) |e| e.items.len else 0);
// }

// test "Graph: Add Edge (Heterogeneous)" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.convertToHeterogeneous();
//     try g.addNode(1, "NodeA", "TypeA");
//     try g.addNode(2, "NodeB", "TypeB");
//     try g.addEdge(1, 2, 2.5, "Strong Connection");

//     if (g.getEdgeType(1, 2) == null or !std.mem.eql(u8, g.getEdgeType(1, 2).?, "Strong Connection")) {
//         std.debug.print("\n[ERROR] Edge 1 -> 2 type mismatch! Expected: 'Strong Connection', Found: {?s}\n", .{g.getEdgeType(1, 2).?});
//     }

//     try std.testing.expectEqualStrings("Strong Connection", g.getEdgeType(1, 2).?);
// }

// test "Graph: Cycle Detection (Acyclic Graphs)" {
//     var g = Graph(true, true, false).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "A", null);
//     try g.addNode(2, "B", null);
//     try g.addEdge(1, 2, {}, null);

//     try std.testing.expectError(error.CycleDetected, g.addEdge(2, 1, {}, null));
// }

// test "Graph: Remove Edge" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "NodeA", null);
//     try g.addNode(2, "NodeB", null);
//     try g.addEdge(1, 2, 4.5, null);

//     g.removeEdge(1, 2);

//     if (g.edges.get(1) != null and g.edges.get(1).?.items.len > 0) {
//         std.debug.print("\n[ERROR] Edge 1 -> 2 was not removed correctly!\n", .{});
//     }

//     try std.testing.expectEqual(@as(usize, 0), if (g.edges.get(1)) |e| e.items.len else 0);
// }

// test "Graph: Debug Print (Only on Failure)" {
//     var g = Graph(true, false, true).init(std.testing.allocator);
//     defer g.deinit();

//     try g.addNode(1, "A", null);
//     try g.addNode(2, "B", null);
//     try g.addEdge(1, 2, 4.5, null);

//     if (!g.nodes.contains(1) or !g.nodes.contains(2) or !g.edges.contains(1)) {
//         std.debug.print("\n[ERROR] Debug Print - Graph is missing expected elements!\n", .{});
//         g.debugPrint();
//     }

//     try std.testing.expect(g.nodes.contains(1));
//     try std.testing.expect(g.nodes.contains(2));
//     try std.testing.expect(g.edges.contains(1));
// }

<<<

`node.zig`: >>>

const std = @import("std");

const ValueType = union(enum) {
    int: i64,
    float: f64,
    boolean: bool,
    string: []const u8,
};

pub const Node = struct {
    allocator: std.mem.Allocator,
    id: u64,
    label: []const u8,
    data: std.StringHashMap(ValueType),

    pub fn init(allocator: std.mem.Allocator, id: u64, label: []const u8) !Node {
        return Node{
            .allocator = allocator,
            .id = id,
            .label = try allocator.dupe(u8, label),
            .data = std.StringHashMap(ValueType).init(allocator),
        };
    }

    pub fn deinit(self: *Node) void {
        self.allocator.free(self.label);

        var iter = self.data.iterator();
        while (iter.next()) |entry| {
            self.allocator.free(entry.key_ptr.*);

            // ✅ Ensure we only free memory if it's a string
            if (entry.value_ptr.* == .string) {
                self.allocator.free(entry.value_ptr.string);
            }
        }

        self.data.deinit();
    }

    pub fn getData(self: *const Node, key: []const u8) ?*const ValueType {
        if (key.len == 0) return null; // 🚀 Return null immediately if key is empty

        return self.data.getPtr(key);
    }

    pub fn setData(self: *Node, key: []const u8, value: ValueType) !void {
        if (key.len == 0) return error.InvalidKey; // 🚀 Prevents empty keys

        // ✅ Check if key exists before overwriting
        if (self.data.getPtr(key)) |existing_value| {
            if (existing_value.* == .string) {
                self.allocator.free(existing_value.string);
            }
        }

        // ✅ Retrieve old key pointer correctly
        var old_key_ptr: ?[]const u8 = null;
        if (self.data.getKeyPtr(key)) |existing_key_ptr| {
            old_key_ptr = existing_key_ptr.*;
        }

        // ✅ Remove existing key before replacing
        if (self.data.remove(key)) {
            if (old_key_ptr) |key_str| {
                self.allocator.free(key_str); // Free old key memory safely
            }
        }

        // ✅ Allocate new key and value
        const key_dup = try self.allocator.dupe(u8, key);
        var value_dup: ValueType = value;
        if (value == .string) {
            value_dup.string = try self.allocator.dupe(u8, value.string);
        }

        // ✅ Insert into hashmap
        try self.data.put(key_dup, value_dup);
    }

    pub fn removeData(self: *Node, key: []const u8) !void {
        if (key.len == 0) return error.InvalidKey; // 🚀 Prevents empty keys

        // ✅ Ensure key exists before removing
        if (self.data.getPtr(key)) |value| {
            if (value.* == .string) {
                self.allocator.free(value.string);
            }
        } else {
            return error.KeyNotFound; // 🚀 Explicit error when key does not exist
        }

        // ✅ Retrieve the actual key stored in the hashmap before modifying
        var old_key_ptr: ?[]const u8 = null;
        if (self.data.getKeyPtr(key)) |stored_key_ptr| {
            old_key_ptr = stored_key_ptr.*;
        }

        // ✅ Remove key-value pair before freeing memory
        if (self.data.remove(key)) {
            if (old_key_ptr) |key_str| {
                self.allocator.free(key_str);
            }
        } else {
            return error.KeyNotFound; // 🚀 Safety check: ensure key actually got removed
        }
    }
};

// Unit Tests
test "Node: Initialization & Deinitialization" {
    var n = try Node.init(std.testing.allocator, 1, "Test Node");
    defer n.deinit();
    try std.testing.expectEqual(@as(u64, 1), n.id);
    try std.testing.expectEqualStrings("Test Node", n.label);
}

test "Node: Set and Get Data" {
    var n = try Node.init(std.testing.allocator, 2, "Data Node");
    defer n.deinit();

    try n.setData("key1", ValueType{ .string = "value1" });
    try n.setData("key2", ValueType{ .int = 42 });

    try std.testing.expectEqualStrings("value1", n.getData("key1").?.string);
    try std.testing.expectEqual(@as(i64, 42), n.getData("key2").?.int);
}

test "Node: Overwrite Existing Data" {
    var n = try Node.init(std.testing.allocator, 3, "Overwrite Test");
    defer n.deinit();

    try n.setData("key", ValueType{ .string = "initial" });
    try n.setData("key", ValueType{ .string = "updated" });

    try std.testing.expectEqualStrings("updated", n.getData("key").?.string);
}

test "Node: Remove Data" {
    var n = try Node.init(std.testing.allocator, 4, "Remove Test");
    defer n.deinit();

    try n.setData("key", ValueType{ .string = "to be removed" });
    try n.removeData("key"); // ✅ Now catching potential errors

    try std.testing.expect(n.getData("key") == null);
}

// 🚀 New Tests: Edge Cases
test "Node: Handle Empty Key" {
    var n = try Node.init(std.testing.allocator, 5, "Empty Key Test");
    defer n.deinit();

    // Expect setData to fail with an InvalidKey error
    try std.testing.expectError(error.InvalidKey, n.setData("", ValueType{ .string = "empty" }));

    // Expect getData to return null for an empty key
    try std.testing.expect(n.getData("") == null);

    // Expect removeData to fail with an InvalidKey error
    try std.testing.expectError(error.InvalidKey, n.removeData(""));
}

test "Node: Overwrite Stress Test" {
    var n = try Node.init(std.testing.allocator, 6, "Overwrite Stress Test");
    defer n.deinit();

    try n.setData("key", ValueType{ .string = "first" });
    try n.setData("key", ValueType{ .string = "second" });
    try n.setData("key", ValueType{ .string = "third" });

    try std.testing.expectEqualStrings("third", n.getData("key").?.string);
}

test "Node: Remove Non-Existent Key" {
    var n = try Node.init(std.testing.allocator, 7, "Remove Non-Existent");
    defer n.deinit();

    // ✅ Expect `removeData` to return an error for a non-existent key
    try std.testing.expectError(error.KeyNotFound, n.removeData("does_not_exist"));

    try std.testing.expect(n.getData("does_not_exist") == null);
}

<<<

`bfs.zig`: >>>


<<<

`bidirectional_bfs.zig`: >>>


<<<

`connected_components.zig`: >>>


<<<

`dfs.zig`: >>>


<<<

`traversal.zig`: >>>


<<<

`cheeger_inequality.zig`: >>>


<<<

`eigenvalues.zig`: >>>


<<<

`eigenvectors.zig`: >>>


<<<

`graph_fourier_transform.zig`: >>>


<<<

`laplacian_matrix.zig`: >>>


<<<

`pagerank_spectral.zig`: >>>


<<<

`spectral_clustering.zig`: >>>


<<<

`spectral.zig`: >>>


<<<

`bellman_ford.zig`: >>>


<<<

`djikstra.zig`: >>>


<<<

`floyd_warshall.zig`: >>>


<<<

`shortest_path.zig`: >>>


<<<

`kruskal.zig`: >>>


<<<

`mst.zig`: >>>


<<<

`prim.zig`: >>>


<<<

`edmonds_karp.zig`: >>>


<<<

`flow.zig`: >>>


<<<

`ford_fulkerson.zig`: >>>


<<<

`conversion_strategies.md`: >>>


<<<

`perf_tuning.md`: >>>


<<<

`roadmap.md`: >>>


<<<

`safety_and_threading.md`: >>>


<<<

`storage_design.md`: >>>


<<<

`zson_config.md`: >>>


<<<

`zgraph-spec.md`: >>>


<<<

`zgraphb-spec.md`: >>>


<<<