Grand Diomande Research · Full HTML Reader

Graph Kernel Full Integration Architecture

The Graph Kernel is the **sole admissibility authority** for context retrieval. All paths to `memory_turns` must go through Graph Kernel verification. This document defines the integration architecture across all systems.

Agents That Account for Themselves architecture technical paper candidate score 46 .md

Full Public Reader

Graph Kernel Full Integration Architecture

Status: Implementation Ready
Last Updated: 2026-01-03

Executive Summary

The Graph Kernel is the sole admissibility authority for context retrieval. All paths to `memory_turns` must go through Graph Kernel verification. This document defines the integration architecture across all systems.

Current State

Component	Graph Kernel Integration	Status
cc-graph-kernel	Core implementation	✅ Complete
cc-agent-service	Python client + hook	✅ Complete
cc-agent-sdk	MCP tools (4 tools)	✅ Complete
cc-rag-plus-plus	Partial (21 bypass paths)	⚠️ Needs Migration
Cloud Agents	GraphKernelHook available	✅ Complete

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                            CLIENT LAYER                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  Agent SDK (TS)  │  Cloud Agents  │  MCP Tools  │  Direct Clients           │
│       │                 │               │              │                    │
│       └─────────────────┴───────────────┴──────────────┘                    │
│                              │                                               │
│                    ┌─────────▼────────┐                                     │
│                    │  Graph Kernel    │  ← HMAC Token Authority              │
│                    │  Service :8001   │                                      │
│                    └────────┬─────────┘                                     │
│                             │                                               │
│              ┌──────────────┼──────────────┐                                │
│              ▼              ▼              ▼                                │
│     ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                       │
│     │  RAG++      │  │  Orbit      │  │  Training   │                       │
│     │  Retrieval  │  │  Context    │  │  Pipeline   │                       │
│     └──────┬──────┘  └──────┬──────┘  └──────┬──────┘                       │
│            │                │                │                              │
│            └────────────────┼────────────────┘                              │
│                             │                                               │
│                    ┌────────▼────────┐                                      │
│                    │    Supabase     │                                      │
│                    │  memory_turns   │                                      │
│                    └─────────────────┘                                      │
└─────────────────────────────────────────────────────────────────────────────┘

Integration Points

1. Graph Kernel Service (Rust)

Endpoint: `https://graph-kernel-xxxxxxxx.run.app` (Cloud Run)
Local: `http://localhost:8001`

API:

POST /api/slice          → AdmissibleEvidenceBundle
POST /api/slice/batch    → Vec<AdmissibleEvidenceBundle>
GET  /api/policies       → Vec<PolicyRef>
POST /api/policies       → PolicyRef
GET  /health             → ServiceHealth
POST /api/verify_token   → VerificationResult

2. RAG++ Integration (Python)

Files requiring migration:

File	Function	Direct Query	Replacement
`mcp/orbit_mcp_server.py`	`orbit_search()`	`.table("memory_turns")`	`SliceEnforcingClient`
`mcp/orbit_mcp_server.py`	`orbit_context()`	`.table("memory_turns")`	`SliceEnforcingClient`
`slice/anchor.py`	`resolve_explicit()`	`.table("memory_turns")`	Validate via Graph Kernel
`slice/anchor.py`	`resolve_from_session()`	`.table("memory_turns")`	Graph Kernel validation
`ingestion/primitive_enricher.py`	Insert	Direct insert	Add provenance metadata
`ingestion/prompt_ingester.py`	Insert	Direct insert	Add provenance metadata
`ingestion/embedder.py`	Update	Metadata update	Graph Kernel enrichment API
`ml/cognitivetwin_v3/ingest/supabase_extractor.py`	`extract_all_turns()`	Bulk extract	Filter via Graph Kernel
`retrieval/query.py`	`MemoryRetriever.search()`	Default search	Require explicit mode
`retrieval/query.py`	`_text_search()`	Fallback search	Add admissibility marking
`retrieval/query.py`	`get_similar_conversations()`	RPC search	Filter by slice

3. Agent SDK Integration (TypeScript) ✅ COMPLETE

The Agent SDK provides 4 Graph Kernel tools in `core/cc-agent-sdk/src/tools/graph_kernel.ts`:

Tool	Description
`graphKernelSliceTool`	Generate deterministic context slice
`graphKernelVerifyTool`	Verify admissibility token
`graphKernelBatchSliceTool`	Batch slice generation
`graphKernelHealthTool`	Health check endpoint

Usage:

typescript

import {
  graphKernelTools,
  getGraphKernelTool
} from '@comp-core/agent-sdk/tools';

// Get slice tool
const sliceTool = getGraphKernelTool('graphKernelSliceTool');
const slice = await sliceTool.handler({
  anchor_turn_id: 'turn_123',
  depth: 3,
  max_turns: 100,
}, context);

// Verify token
const verifyTool = getGraphKernelTool('graphKernelVerifyTool');
const verified = await verifyTool.handler({
  [sensitive field redacted],
}, context);

See: [17-AGENT_SDK.md](17-AGENT_SDK.md) for full Agent SDK documentation

4. Cloud Agents SDK Integration ✅ COMPLETE

Add Graph Kernel hook to agent configuration:

python

from cc_agent_service.graph_kernel import GraphKernelHook

hook = GraphKernelHook(
    endpoint="https://graph-kernel-xxxxxxxx.run.app",
    max_context_turns=64,
    include_in_system_prompt=True,
)

agent_service = AgentService(default_hooks=[hook])

SliceEnforcingClient Wrapper

The key integration component for RAG++:

python

# core/cc-rag-plus-plus/rag_plusplus/slice/enforcing_client.py

class SliceEnforcingClient:
    """
    Wrapper that enforces all queries go through Graph Kernel.

    This is the ONLY approved way to query memory_turns in production.
    Direct Supabase access is blocked except for ingestion.
    """

    def __init__(
        self,
        supabase: Client,
        graph_kernel_url: str = "http://localhost:8001",
    ):
        self.supabase = supabase
        self.kernel = GraphKernelClient(graph_kernel_url)

    async def search(
        self,
        query: str,
        anchor_turn_id: str,
        policy_ref: Optional[PolicyRef] = None,
        limit: int = 10,
    ) -> SliceScopedResults:
        """
        Search within an admissible slice only.

        1. Get slice from Graph Kernel
        2. Filter query to slice.turn_ids
        3. Return with provenance chain
        """
        # Get admissible slice
        slice_export = await self.kernel.slice(anchor_turn_id, policy_ref)

        # Search only within admissible turns
        results = await self._vector_search(
            query=query,
            turn_ids=slice_export.turn_ids,
            limit=limit,
        )

        return SliceScopedResults(
            results=results,
            provenance=RetrievalProvenance(
                slice_id=slice_export.slice_id,
                anchor_turn_id=anchor_turn_id,
                policy_ref=policy_ref,
                retrieval_mode="slice",
            ),
        )

    async def search_global(
        self,
        query: str,
        limit: int = 10,
    ) -> GlobalResults:
        """
        Search entire fabric (explicit global mode).

        Results are MARKED as non-admissible and cannot trigger promotions.
        """
        results = await self._vector_search(query=query, limit=limit)

        return GlobalResults(
            results=results,
            provenance=RetrievalProvenance(
                slice_id=None,
                retrieval_mode="global",
                is_admissible=False,  # Explicitly marked
            ),
        )

Deployment Steps

1. Create GCP Secrets

bash

# Create HMAC secret (32+ bytes)
openssl rand -base64 32 | gcloud secrets create kernel-hmac-secret --data-file=-

# Verify database-url secret exists
gcloud secrets describe database-url

2. Deploy Graph Kernel Service

bash

cd core/cc-graph-kernel
gcloud builds submit --config=cloudbuild-service.yaml

3. Get Service URL

bash

gcloud run services describe graph-kernel --region=us-central1 --format="value(status.url)"

4. Update Environment Variables

bash

# In RAG++ .env
GRAPH_KERNEL_URL=https://graph-kernel-xxxxxxxx.run.app

# In Agent SDK
export GRAPH_KERNEL_URL=https://graph-kernel-xxxxxxxx.run.app

5. Run Integration Tests

bash

# Test Graph Kernel connectivity
curl https://graph-kernel-xxxxxxxx.run.app/health

# Test slice generation
curl -X POST https://graph-kernel-xxxxxxxx.run.app/api/slice \
  -H "Content-Type: application/json" \
  -d '{"anchor_turn_id": "uuid-of-a-turn"}'

Migration Strategy

### Phase 1: Deploy Service (Day 1)
- Deploy Graph Kernel to Cloud Run
- Verify health endpoints
- Test with sample slices

### Phase 2: Add Wrapper (Day 2-3)
- Create `SliceEnforcingClient` in RAG++
- Add provenance tracking to all results
- Don't break existing queries (add alongside)

### Phase 3: Migrate High-Risk Paths (Day 4-7)
- MCP server (orbit_mcp_server.py)
- Anchor resolution (anchor.py)
- Training pipeline (supabase_extractor.py)

### Phase 4: Agent SDK Integration ✅ COMPLETE
- ✅ Added graphKernelSliceTool, graphKernelVerifyTool, graphKernelBatchSliceTool, graphKernelHealthTool
- ✅ Agent SDK fully documented in [17-AGENT_SDK.md](17-AGENT_SDK.md)
- ✅ GraphKernelHook available for cloud agents

### Phase 5: Deprecate Direct Queries (Day 11-14)
- Add linter rule to flag `.table("memory_turns")`
- Remove direct queries from service code
- Run full integration tests

Success Criteria

[ ] All retrieval goes through Graph Kernel (100
[x] Admissibility tokens verified on every slice
[x] Content hash verification enabled
[x] Benchmark: <5ms p99 for cached verification
[x] Agent SDK has graph_kernel_slice tool (+ 3 more tools)
[x] Cloud agents use GraphKernelHook
[ ] Training pipeline filters through Graph Kernel
[ ] RAG++ bypass paths migrated to SliceEnforcingClient

Monitoring

Prometheus Metrics

# Slice generation
gk_slice_duration_seconds{policy="v1"} histogram
gk_slice_turns_count{policy="v1"} histogram

# Token verification
gk_verification_duration_seconds{cached="true|false"} histogram
gk_cache_hit_ratio gauge

# Admissibility violations
gk_admissibility_violations_total counter
gk_global_query_count_total counter

Alerts

High latency: p99 > 100ms for slice generation
Verification failures: Error rate > 0.1
Cache hit ratio: Below 80

Promotion Decision

Promote into a technical note or architecture paper with implementation anchors.

Source Anchor

Comp-Core/docs/architecture/16-GRAPH_KERNEL_INTEGRATION.md

Detected Structure

Method · Evaluation · Code Anchors · Architecture