Graph Kernel DEP Audit V2

Graph Kernel DEP Audit V2

OpenClaw CompCore — Deep Engineering Posture Assessment
Version: 2.0.0 · Date: 2026-02-14
Auditor: Automated Code Analysis + Live Service Inspection
Codebase: `core/semantic/cc-graph-kernel/` — ~11,241 lines Rust

---

Executive Summary

The Graph Kernel is a remarkably well-architected provenance engine. It achieves something rare: a Rust service with genuine cryptographic security guarantees enforced at the type level, deterministic behavior verified through golden tests, and a clean separation between its core library (zero I/O) and its service layer (Axum + PostgreSQL). The codebase punches above its weight.

That said, this audit identifies 47 specific findings across 12 dimensions. The most critical: the 291ms latency is entirely addressable (90

Overall Health Score: 7.4 / 10 — Production-viable with clear improvement vectors.

---

Dimension Scores

---

1. Code Quality — 8/10

Strengths

- Zero `unsafe` blocks. The entire codebase uses safe Rust exclusively. No raw pointer manipulation, no transmutes, no FFI unsafety.

- `#![warn(missing_docs)]` and `#![warn(clippy::all)]` are set at the crate root (`lib.rs`). Every public item has doc comments. This is discipline most production Rust codebases lack.

- Type-driven design. `TurnId`, `SliceFingerprint`, `GraphSnapshotHash`, `AdmissibilityToken` — each concept gets its own newtype wrapper with domain-specific methods. No stringly-typed APIs.

- Error handling is idiomatic. `thiserror` for domain errors, `Result` propagation throughout. The `SlicerError` enum covers all failure modes with descriptive variants.

- Canonical ordering everywhere. `BTreeMap` over `HashMap`, sorted `Vec<TurnSnapshot>` and `Vec<Edge>`, `Ord` implementations on domain types. This isn't accidental — it's systematic determinism enforcement.

Findings

Clippy Compliance

The crate compiles cleanly with `#![warn(clippy::all)]`. No clippy suppressions beyond `too_many_arguments`. Static analysis posture is strong.

---

2. Architecture — 9/10

Strengths

• Feature-gated layering is exemplary. The crate compiles three ways:
• `default` — Pure library, zero I/O, no async runtime. Suitable for embedding.
• `postgres` — Adds sqlx + tokio for database access.
• `service` — Full HTTP service with Axum, CORS, tracing.

This means the core slicing logic can be used as a library in other Rust crates without pulling in a web framework. This is the correct way to build a Rust service.

- `GraphStore` trait abstraction. The `async_trait`-based `GraphStore` trait enables clean backend swapping. `InMemoryGraphStore` for tests, `PostgresGraphStore` for production. Adding SQLite would require only implementing this trait.

- Dual-purpose design is cleanly separated. Context slicing (the `slicer` module) and knowledge graph CRUD (the `routes` module) share the same `PostgresGraphStore` but have no coupling between them. They could be split into separate services trivially.

- Atlas subsystem. The atlas module (snapshot → batch slicer → overlap → influence → bundler) is a complete graph analytics pipeline with its own schema version. This is architectural foresight — it enables pre-computed graph structure without coupling to the real-time API.

- Policy registry with hash-stable fingerprints. Policies are immutable once registered, referenced by content hash, and the registry itself has a composite fingerprint. This enables reproducible policy resolution across deployments.

Findings

---

3. Performance — 5/10

The 291ms Problem

This is the single most impactful finding. The benchmark data is unambiguous:

The Rust code itself is fast. Serialization is ~1ms. HMAC computation is sub-millisecond. The xxHash64 fingerprinting is sub-microsecond. The problem is entirely architectural: every query crosses the Atlantic (or at minimum a VPC boundary) to reach Supabase.

Connection Pooling

Current configuration:

max_connections: 10
min_connections: 2
connect_timeout: 10s
idle_timeout: 300s
max_lifetime: 1800s
test_before_acquire: true

The `test_before_acquire: true` setting adds a `SELECT 1` round-trip before every connection acquisition. For a remote database with 200ms RTT, this adds 200ms to the first query on every connection checkout. This should be `false` for local deployments and conditionally set based on `DB_TEST_BEFORE_ACQUIRE` env var.

Findings

---

4. Data Model — 7/10

Triple Schema

CREATE TABLE knowledge_graph (
    id BIGSERIAL PRIMARY KEY,
    subject TEXT NOT NULL,
    predicate TEXT NOT NULL,
    object TEXT NOT NULL,
    confidence DOUBLE PRECISION DEFAULT 0.5,
    source TEXT DEFAULT 'unknown',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(subject, predicate, object)
);

Indexes present: `idx_knowledge_subject`, `idx_knowledge_predicate`, `idx_knowledge_confidence`.

Live Data Profile (as of audit)

Findings

---

5. Security — 9/10

Strengths

The Graph Kernel's security model is its crown jewel. The HMAC-signed admissibility framework is the strongest security implementation I've seen in a sub-15KLOC codebase:

- HMAC-SHA256 token signing with a 128-bit truncated output. The canonical string includes 6 fields + a version marker, preventing field reordering attacks.

- Type-level enforcement via `AdmissibleEvidenceBundle`. This type can only be constructed through `from_verified()`, which requires the HMAC secret and performs verification. Downstream APIs that accept `AdmissibleEvidenceBundle` get compile-time guarantee that the evidence was kernel-authorized.

- 8 security invariants (INV-GK-001 through INV-GK-008) are documented, each with corresponding incident types, severity levels, and response procedures.

- `SliceBoundaryGuard` prevents SQL injection by construction. Database queries for slice retrieval use parameterized arrays (`WHERE id = ANY($1)`) with the guard as the only way to produce the parameter.

- Token verification cache with constant-time comparison and LRU eviction. Performance target: <5ms p99 for cached verification.

Findings

---

6. Testing — 8/10

Test Inventory

Strengths

- The 100-run determinism tests (`test_same_anchor_same_slice_id_100_runs`, `test_slice_fingerprint_byte_level`) are the gold standard for deterministic system testing. Most codebases don't test this rigorously.

- Benchmark suite covers cold verification, cached verification, cache misses, cache contention (multi-threaded), and HMAC computation overhead. This enables regression detection.

- `InMemoryGraphStore` enables fast, deterministic testing without database dependencies. Test helper functions (`make_turn`, `build_linear_graph`, `build_branching_graph`) are well-factored.

Findings

---

7. Documentation — 9/10

Inventory

Strengths

- The research paper is genuine scholarship. Formal definitions, proper citations, comparative analysis against 9 industry systems. This positions the project for publication, not just internal documentation.

- The architecture doc is a complete reference. API endpoints, data model, deployment guide, configuration reference, operational runbook — all in one document. New contributors can onboard from this alone.

- Inline documentation density is exceptional. Module-level docs explain purpose. Function docs explain contracts. Security invariants are documented inline where enforced.

Findings

---

8. Dependencies — 7/10

Cargo.toml Audit

Findings

---

9. Operational — 7/10

What's Present

• Structured JSON logging compatible with Cloud Logging / Cloud Trace
• Request tracing with correlation IDs (X-Cloud-Trace-Context)
• Health check hierarchy: `/health` (detailed), `/health/live` (liveness), `/health/ready` (readiness), `/health/startup` (startup probe) — Cloud Run compatible
• Graceful shutdown handling SIGTERM and Ctrl+C
• Connection pool monitoring via `pool_stats()` in health response

Findings

---

10. Scale — 6/10

Current Operating Point

Findings

---

11. Known Bugs — 6/10

Active Issues

---

12. Missing Features — 5/10

---

Overall Health Assessment

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   OVERALL HEALTH SCORE:  7.4 / 10                           ║
║                                                              ║
║   Verdict: PRODUCTION-VIABLE with clear improvement paths    ║
║                                                              ║
║   Critical path: Latency (local DB) → Entity normalization   ║
║   → Server-side traversal → Prometheus metrics               ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Score Breakdown

What Makes This Codebase Special

1. The provenance engine concept is novel. No other system in the graph database / RAG space combines deterministic context slicing with HMAC-signed admissibility tokens. The research paper correctly identifies this as a new infrastructure category.

2. Type-level security enforcement. The `AdmissibleEvidenceBundle` pattern — where the type itself is proof of verification — is genuinely elegant. It turns security violations into compile errors.

3. The documentation-to-code ratio is remarkable. A research paper, architecture doc, evaluation report, improvement plan, and dense inline docs for an 11K-line codebase. This project is more documented than most 100K-line projects.

What Needs Attention

1. Get off the remote database for reads. The SQLite proxy (already implemented in Python) is the right pattern. The Rust service should support SQLite natively via a feature flag.

2. Entity normalization belongs in Rust. The Python middleware is a workaround. A `canonicalize_entity()` function at the route handler level would close the normalization gap permanently.

3. Server-side traversal is the highest-impact feature. A single new endpoint would transform the Graph Kernel's multi-hop story from "N round-trips" to "one query."

---

Audit generated from static analysis of the cc-graph-kernel crate, live service inspection at localhost:8001, benchmark data from graph-kernel-evaluation.md, and documentation review.