overgraph 0.1.0__tar.gz

overgraph-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,26 @@
+---
+name: Bug Report
+about: Something isn't working right
+title: ""
+labels: bug
+assignees: ""
+---
+
+**What happened?**
+A clear description of the bug.
+
+**What did you expect?**
+What should have happened instead.
+
+**How to reproduce**
+Steps or a minimal code example:
+
+```
+// your code here
+```
+
+**Environment**
+- OS: [e.g., macOS 14, Ubuntu 22.04, Windows 11]
+- Language: [Rust / Node.js / Python]
+- OverGraph version: [e.g., 0.1.0]
+- Rust version (if building from source): [e.g., 1.75.0]

overgraph-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature Request
+about: Suggest something new
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**What's the use case?**
+Describe what you're trying to do and why the current API doesn't cover it.
+
+**What would the API look like?**
+If you have ideas about how this would work, show an example:
+
+```
+// your ideal API here
+```
+
+**Anything else?**
+Any context, alternatives you've considered, or related issues.

overgraph-0.1.0/.github/workflows/benchmarks.yml

@@ -0,0 +1,250 @@
+name: Benchmarks
+
+on:
+  workflow_dispatch:
+    inputs:
+      profile:
+        description: "Benchmark profile"
+        required: false
+        default: small
+        type: choice
+        options:
+          - small
+          - medium
+          - large
+      baseline_root:
+        description: "Optional baseline root dir (defaults to docs/04-quality/reports/baselines/gha-ubuntu-22.04/<profile>)"
+        required: false
+        type: string
+      fail_on_warning:
+        description: "Fail workflow when only warning-threshold regressions are found"
+        required: false
+        default: false
+        type: boolean
+  schedule:
+    - cron: "0 7 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 180
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Resolve benchmark config
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            PROFILE="${{ inputs.profile }}"
+            BASELINE_ROOT_INPUT="${{ inputs.baseline_root }}"
+            FAIL_ON_WARNING="${{ inputs.fail_on_warning }}"
+          else
+            PROFILE="medium"
+            BASELINE_ROOT_INPUT=""
+            FAIL_ON_WARNING="false"
+          fi
+
+          if [[ -n "${BASELINE_ROOT_INPUT}" ]]; then
+            BASELINE_ROOT="${BASELINE_ROOT_INPUT}"
+          else
+            BASELINE_ROOT="docs/04-quality/reports/baselines/gha-ubuntu-22.04/${PROFILE}"
+          fi
+
+          case "${PROFILE}" in
+            small)
+              WARMUP=10
+              ITERS=30
+              ;;
+            medium)
+              WARMUP=20
+              ITERS=80
+              ;;
+            large)
+              WARMUP=20
+              ITERS=80
+              ;;
+            *)
+              echo "Unsupported profile: ${PROFILE}" >&2
+              exit 1
+              ;;
+          esac
+
+          RUN_TAG="ci-$(date -u +%Y%m%dT%H%M%SZ)-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+
+          {
+            echo "PROFILE=${PROFILE}"
+            echo "BASELINE_ROOT=${BASELINE_ROOT}"
+            echo "WARMUP=${WARMUP}"
+            echo "ITERS=${ITERS}"
+            echo "RUN_TAG=${RUN_TAG}"
+            echo "FAIL_ON_WARNING=${FAIL_ON_WARNING}"
+          } >> "$GITHUB_ENV"
+
+      - name: Setup Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build artifacts
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install system deps
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install -y pkg-config libssl-dev
+
+      - name: Install Node deps + build connector
+        shell: bash
+        run: |
+          set -euo pipefail
+          npm ci --prefix overgraph-node
+          npm --prefix overgraph-node run build
+
+      - name: Install Python deps + build connector
+        shell: bash
+        run: |
+          set -euo pipefail
+          python3 -m pip install --upgrade pip
+          python3 -m pip install maturin==1.7.8
+          python3 -m pip install -e overgraph-python
+
+      - name: Run benchmark suite
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p bench-artifacts/runs/rust
+          mkdir -p bench-artifacts/runs/node
+          mkdir -p bench-artifacts/runs/python
+
+          scripts/bench/run-rust.sh \
+            --profile "${PROFILE}" \
+            --warmup "${WARMUP}" \
+            --iters "${ITERS}" \
+            --output-root bench-artifacts/runs/rust \
+            --run-id "${RUN_TAG}-rust-${PROFILE}"
+
+          scripts/bench/run-node.sh \
+            --profile "${PROFILE}" \
+            --warmup "${WARMUP}" \
+            --iters "${ITERS}" \
+            --output-root bench-artifacts/runs/node \
+            --run-id "${RUN_TAG}-node-${PROFILE}"
+
+          scripts/bench/run-python.sh \
+            --profile "${PROFILE}" \
+            --warmup "${WARMUP}" \
+            --iters "${ITERS}" \
+            --output-root bench-artifacts/runs/python \
+            --run-id "${RUN_TAG}-python-${PROFILE}"
+
+      - name: Validate cross-language parity
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p bench-artifacts/parity
+
+          python3 tools/bench/validate_parity.py \
+            --rust "bench-artifacts/runs/rust/${RUN_TAG}-rust-${PROFILE}/rust.json" \
+            --node "bench-artifacts/runs/node/${RUN_TAG}-node-${PROFILE}/node.json" \
+            --python "bench-artifacts/runs/python/${RUN_TAG}-python-${PROFILE}/python.json" \
+            --report-json bench-artifacts/parity/parity-report.json \
+            --report-md bench-artifacts/parity/parity-report.md
+
+      - name: Compare to baseline
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p bench-artifacts/compare
+
+          status=0
+          for lang in rust node python; do
+            candidate_json="bench-artifacts/runs/${lang}/${RUN_TAG}-${lang}-${PROFILE}/${lang}.json"
+            baseline_json="${BASELINE_ROOT}/${lang}.json"
+            report_md="bench-artifacts/compare/${lang}-compare.md"
+            report_json="bench-artifacts/compare/${lang}-compare.json"
+
+            if [[ ! -f "${candidate_json}" ]]; then
+              echo "Missing candidate file: ${candidate_json}" >&2
+              status=2
+              continue
+            fi
+
+            if [[ -f "${baseline_json}" ]]; then
+              args=(
+                python3 tools/bench/compare_baseline.py
+                --baseline "${baseline_json}"
+                --candidate "${candidate_json}"
+                --allowlist docs/04-quality/regression-allowlist.json
+                --warn-threshold-pct 10
+                --fail-threshold-pct 20
+                --report-md "${report_md}"
+                --report-json "${report_json}"
+              )
+              if [[ "${FAIL_ON_WARNING}" == "true" ]]; then
+                args+=(--fail-on-warning)
+              fi
+
+              set +e
+              "${args[@]}"
+              rc=$?
+              set -e
+
+              if (( rc > status )); then
+                status=$rc
+              fi
+            else
+              {
+                echo "# Benchmark Baseline Comparison"
+                echo
+                echo "- Language: \`${lang}\`"
+                echo "- Status: \`error\`"
+                echo "- Reason: required baseline file not found at \`${baseline_json}\`"
+              } > "${report_md}"
+              status=2
+            fi
+          done
+
+          exit "${status}"
+
+      - name: Publish comparison summary
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -f "bench-artifacts/parity/parity-report.md" ]]; then
+            echo "## parity-report.md" >> "$GITHUB_STEP_SUMMARY"
+            cat "bench-artifacts/parity/parity-report.md" >> "$GITHUB_STEP_SUMMARY"
+            echo >> "$GITHUB_STEP_SUMMARY"
+          fi
+          if compgen -G "bench-artifacts/compare/*.md" > /dev/null; then
+            for file in bench-artifacts/compare/*.md; do
+              echo "## $(basename "${file}")" >> "$GITHUB_STEP_SUMMARY"
+              cat "${file}" >> "$GITHUB_STEP_SUMMARY"
+              echo >> "$GITHUB_STEP_SUMMARY"
+            done
+          fi
+
+      - name: Upload benchmark artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-${{ env.RUN_TAG }}-${{ env.PROFILE }}
+          path: bench-artifacts
+          if-no-files-found: error
+          retention-days: 30

overgraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo registry and build
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Build
+        run: cargo build --all-targets --features cli
+
+      - name: Run tests
+        run: cargo test --features cli
+
+      - name: Run tests (no default features)
+        run: cargo test

overgraph-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,177 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  # ──────────────────────────────────────────────
+  # Rust: publish to crates.io
+  # ──────────────────────────────────────────────
+  # Uses API token for first publish. After v0.1.0 is live, configure
+  # Trusted Publishing on crates.io and switch to crates-io-auth-action.
+  publish-rust:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-publish-${{ hashFiles('**/Cargo.lock') }}
+      - run: cargo publish -p overgraph
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+  # ──────────────────────────────────────────────
+  # Node.js: build native binaries for each platform
+  # ──────────────────────────────────────────────
+  build-node:
+    name: Build Node.js (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install dependencies
+        working-directory: overgraph-node
+        run: npm install
+      - name: Build native module
+        working-directory: overgraph-node
+        run: npx napi build --platform --release --target ${{ matrix.target }}
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: node-${{ matrix.target }}
+          path: overgraph-node/*.node
+          if-no-files-found: error
+
+  # ──────────────────────────────────────────────
+  # Node.js: publish to npm
+  # ──────────────────────────────────────────────
+  # Uses granular access token for first publish. After v0.1.0 is live,
+  # configure Trusted Publishing on npmjs.com and switch to OIDC.
+  publish-node:
+    name: Publish to npm
+    needs: build-node
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: overgraph-node/artifacts
+          pattern: node-*
+      - name: Move binaries into place
+        working-directory: overgraph-node
+        run: |
+          for dir in artifacts/node-*/; do
+            cp "$dir"*.node .
+          done
+          ls -la *.node
+      - name: Publish
+        working-directory: overgraph-node
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  # ──────────────────────────────────────────────
+  # Python: build wheels for each platform
+  # ──────────────────────────────────────────────
+  build-python:
+    name: Build Python (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: macos-latest
+            target: aarch64-apple-darwin
+          - os: macos-latest
+            target: x86_64-apple-darwin
+          - os: ubuntu-latest
+            target: x86_64-unknown-linux-gnu
+          - os: windows-latest
+            target: x86_64-pc-windows-msvc
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: overgraph-python
+          target: ${{ matrix.target }}
+          args: --release --out ../dist
+          manylinux: auto
+      - name: Upload wheel
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-${{ matrix.target }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build-python-sdist:
+    name: Build Python sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          working-directory: overgraph-python
+          command: sdist
+          args: --out ../dist
+      - name: Upload sdist
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  # ──────────────────────────────────────────────
+  # Python: publish to PyPI (Trusted Publishers — no token needed)
+  # ──────────────────────────────────────────────
+  publish-python:
+    name: Publish to PyPI
+    needs: [build-python, build-python-sdist]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          pattern: python-*
+          merge-multiple: true
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

overgraph-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Build artifacts
+/target
+*.so
+*.dylib
+*.dSYM/
+
+# Node.js
+node_modules/
+*.node
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+.pytest_cache/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.local
+
+# Claude Code
+.claude/
+CLAUDE.md
+AGENTS.md
+
+# Internal development docs (not public-facing)
+docs/internal/
+
+# Research notes
+research-docs/

overgraph-0.1.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-03-04
+
+Initial release.
+
+### Core Engine
+- Log-structured merge tree storage engine, written entirely in Rust with zero C/C++ dependencies
+- Write-ahead log with CRC32 integrity checks and crash recovery
+- Configurable durability: `Immediate` (fsync per write) or `GroupCommit` (batched fsync, ~20x throughput)
+- Immutable segments with memory-mapped reads (no application-level caching)
+- Background compaction with metadata sidecars, raw binary copy, and metadata-driven index building
+- Atomic manifest updates with rollback safety
+- Directory-scoped databases (each DB is a self-contained folder)
+
+### Data Model
+- Typed nodes with `(type_id, key)` upsert semantics
+- Typed edges with optional `(from, to, type_id)` uniqueness
+- Weighted nodes and edges (`f32` weight field)
+- Schemaless properties encoded as MessagePack (supports null, bool, int, float, string, bytes, arrays)
+
+### Graph Operations
+- Single and batch upsert for nodes and edges
+- Packed binary batch format for maximum throughput
+- Delete with tombstone-based soft deletion
+- Atomic `graph_patch` for multi-operation mutations
+- Point lookups by ID, by `(type_id, key)`, and by `(from, to, type_id)` triple
+- Bulk reads with sorted merge-walk (not per-item lookups)
+
+### Query and Traversal
+- 1-hop and 2-hop neighbor expansion with edge type filters and direction control
+- Constrained 2-hop: traverse specific edge types, filter target nodes by type
+- Top-K neighbors by weight, recency, or decay-adjusted score
+- Property equality search (hash-indexed)
+- Type-based node and edge listing with counts
+- Time-range queries on a sorted timestamp index
+- Subgraph extraction up to N hops deep
+- Personalized PageRank from seed nodes
+- Graph adjacency export with type filters
+
+### Temporal Features
+- Bi-temporal edges with `valid_from` and `valid_to` timestamps
+- Point-in-time queries via `at_epoch` parameter
+- Edge invalidation (mark as no longer valid without deleting)
+- Exponential decay scoring via `decay_lambda` parameter
+
+### Pagination
+- Keyset pagination on all collection-returning APIs
+- Stable cursors across concurrent writes
+- K-way merge with binary-seek cursor for efficient multi-source pagination
+
+### Retention
+- Manual `prune()` by age, weight threshold, or node type
+- Named prune policies stored in manifest, evaluated at read time (lazy expiration) and compaction time (physical deletion)
+- Automatic edge cascade on node pruning
+
+### Indexes
+- Outgoing and incoming adjacency indexes with delta-encoded postings
+- `(type_id, key)` to node_id key index
+- `type_id` to sorted ID list type index
+- Property equality hash index
+- Sorted timestamp index for time-range queries
+- Tombstone index
+
+### Performance
+- Node lookups: ~200ns
+- Neighbor traversal: ~2μs
+- Batch writes: 600K+ nodes/sec
+- Sorted cursor walk for batch adjacency operations (PPR, subgraph, export)
+- Memtable backpressure (64MB hard cap)
+- Segment format v5 with metadata sidecars for fast filtered compaction
+
+### Node.js Connector
+- napi-rs bindings with full API parity
+- Sync and async variants of every method
+- Lazy getters on record types (no deserialization until access)
+- Typed arrays (`Float64Array`, `BigInt64Array`) for bulk data
+- Packed binary batch protocol for node and edge upserts
+- Context manager support
+
+### Python Connector
+- PyO3 + maturin bindings with full API parity
+- Sync `OverGraph` and async `AsyncOverGraph` classes
+- GIL released for all Rust calls via `py.allow_threads()`
+- Lazy `.props` deserialization
+- `IdArray` lazy sequence wrapper
+- Context manager support (`with` / `async with`)
+- PEP 561 type stubs (`.pyi`)
+- Compaction progress callback with Python exception capture
+
+### CLI
+- `overgraph inspect <path>`: show manifest, segment count, node/edge counts, WAL size, prune policies
+
+### CI
+- Cross-platform CI: macOS, Linux, Windows
+- Benchmark CI with regression detection and cross-language parity validation
+
+[0.1.0]: https://github.com/Bhensley5/overgraph/releases/tag/v0.1.0