Grand Diomande Research · Full HTML Reader

Graph Kernel Service

The Graph Kernel runs as a REST API service for slice-conditioned retrieval. It's the **admissibility authority** for the semantic system.

Agents That Account for Themselves research note experiment writeup candidate score 22 .md

Full Public Reader

Graph Kernel Service

The Graph Kernel runs as a REST API service for slice-conditioned retrieval. It's the admissibility authority for the semantic system.

Quick Start

Local Development

bash

cd core/semantic/cc-graph-kernel

# Run with local dev database
DATABASE_URL=postgresql://localhost:5432/ragpp \
KERNEL_HMAC_SECRET=dev_secret \
LOG_FORMAT=pretty \
cargo run --bin graph_kernel_service --features service

Docker Build

bash

# Build image
docker build -f Dockerfile.service -t graph-kernel .

# Run container
docker run -p 8001:8001 \
  -e DATABASE_URL=postgresql://... \
  -e KERNEL_HMAC_SECRET=your_secret \
  graph-kernel

With Docker Compose (RAG++ Stack)

bash

cd core/retrieval/cc-rag-plus-plus

# Start with kernel + database
docker compose --profile with-kernel --profile with-db up -d

Environment Variables

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`KERNEL_HMAC_SECRET`	Yes (prod)	dev secret	HMAC secret for admissibility tokens
`PORT`	No	8001	Service port
`HOST`	No	[ip]	Bind address
`RUST_LOG`	No	info	Log level (debug, info, warn, error)
`LOG_FORMAT`	No	json	Log format (json, pretty)

API Endpoints

Slice Operations

#### `POST /api/slice`
Construct a context slice around an anchor turn.

json

{
  "anchor_turn_id": "turn_abc123",
  "policy_ref": {
    "policy_id": "slice_policy_v1",
    "params_hash": "..."
  }
}

Response includes:
- `slice_id`: Unique fingerprint
- `turn_ids`: Admissible turns
- `admissibility_token`: HMAC-signed proof

#### `POST /api/slice/batch`
Batch slice construction for multiple anchors.

Token Verification

#### `POST /api/verify_token`
Verify an admissibility token without HMAC secret.

Policy Management

#### `GET /api/policies`
List registered policies.

#### `POST /api/policies`
Register a new policy.

Health Checks

Endpoint	Purpose
`GET /health`	Detailed health (database, policies)
`GET /health/live`	Liveness probe (process alive)
`GET /health/ready`	Readiness probe (database connected)
`GET /health/startup`	Startup probe for Cloud Run

Cloud Run Deployment

bash

# Configure project
gcloud config set project YOUR_PROJECT

# Create secrets
gcloud secrets create kernel-hmac-secret --replication-policy=automatic
echo -n "$(openssl rand -hex 32)" | gcloud secrets versions add kernel-hmac-secret --data-file=-

gcloud secrets create database-url --replication-policy=automatic
echo -n "postgresql://..." | gcloud secrets versions add database-url --data-file=-

# Deploy
./deploy.sh

Or use Cloud Build:

bash

gcloud builds submit --config=cloudbuild-service.yaml .

Architecture

ServiceState
├── PostgresGraphStore (Arc)
│   └── Connection pool to Supabase
├── PolicyRegistry (Arc<RwLock>)
│   └── BTreeMap<PolicyRef, SlicePolicyV1>
└── HMAC Secret (Arc<Vec<u8>>)
    └── For signing admissibility tokens

Key Components

1. ContextSlicer - Builds admissible slices around anchors
2. PolicyRegistry - Hash-stable policy storage
3. AdmissibilityToken - HMAC-signed proof of slice membership

Integration with RAG++

RAG++ calls the Graph Kernel to:
1. Get admissible turn IDs for a query anchor
2. Filter vector search results to admissible set
3. Verify tokens on cached slices

python

# Python client example
async with SliceClient(graph_kernel_url) as client:
    slice_export = await client.get_slice(
        anchor_turn_id="turn_123",
        policy_ref=PolicyRef.default()
    )
    # slice_export.turn_ids contains admissible turns

Promotion Decision

Attach run IDs, datasets, metrics, and reproduction commands.

Source Anchor

Comp-Core/core/semantic/cc-graph-kernel/docs/SERVICE.md

Detected Structure

Method · Evaluation · Figures · Architecture