Graph Kernel

┌──────────────────────────────────────────────────────────────────────────────────┐
│                              GRAPH KERNEL SERVICE                                 │
│                                                                                   │
│   ┌───────────────────┐    ┌───────────────────┐    ┌───────────────────────┐   │
│   │   API Layer       │    │   Slicer Engine   │    │   Token Authority     │   │
│   │                   │    │                   │    │                       │   │
│   │ POST /api/slice   │───▶│ ContextSlicer     │───▶│ AdmissibilityToken    │   │
│   │ POST /api/verify  │    │ SlicePolicyV1     │    │ HMAC-SHA256 Signing   │   │
│   │ GET  /health/*    │    │ GraphStore        │    │ Verification          │   │
│   │ GET  /api/policies│    │                   │    │                       │   │
│   └───────────────────┘    └───────────────────┘    └───────────────────────┘   │
│            │                        │                         │                  │
│            │                        ▼                         │                  │
│            │           ┌───────────────────────┐              │                  │
│            │           │   PostgreSQL Store    │              │                  │
│            │           │   (memory_turns)      │              │                  │
│            │           │   Connection Pool     │              │                  │
│            │           └───────────────────────┘              │                  │
│            │                                                  │                  │
│            ▼                                                  ▼                  │
│   ┌────────────────────────────────────────────────────────────────────────┐    │
│   │                         Observability Stack                             │    │
│   │  ┌─────────────┐  ┌─────────────────┐  ┌────────────────────────────┐  │    │
│   │  │ JSON Logs   │  │ Prometheus      │  │ Health Probes              │  │    │
│   │  │ (tracing)   │  │ Metrics :9000   │  │ /live /ready /startup      │  │    │
│   │  └─────────────┘  └─────────────────┘  └────────────────────────────┘  │    │
│   └────────────────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────────────────┘

flowchart LR
    subgraph Client [Downstream Service]
        RAG[RAG++ Service]
        Orbit[Orbit Server]
    end

    subgraph GraphKernel [Graph Kernel]
        API[Axum Router]
        Slicer[ContextSlicer]
        Policy[PolicyRegistry]
        Store[PostgresGraphStore]
        Token[HMAC Authority]
    end

    subgraph Database [PostgreSQL]
        MT[(memory_turns)]
        CV[(conversations)]
    end

    RAG -->|POST /api/slice| API
    Orbit -->|POST /api/verify| API
    API --> Slicer
    Slicer --> Policy
    Slicer --> Store
    Store --> MT
    Store --> CV
    Slicer --> Token
    Token -->|HMAC-SHA256| API
    API -->|SliceExport| RAG

pub struct ContextSlicer<S: GraphStore> {
    store: Arc<S>,
    policy: SlicePolicyV1,
    hmac_secret: Vec<u8>,  // Kernel-only secret
}

priority_score =
    base_salience * policy.phase_weights[turn.phase] *
    policy.distance_decay.powf(distance as f64)

pub struct SlicePolicyV1 {
    /// Maximum turns in slice
    pub max_nodes: usize,
    /// Maximum graph distance from anchor
    pub max_radius: usize,
    /// Distance decay factor (0.0-1.0)
    pub distance_decay: f64,
    /// Include sibling turns?
    pub include_siblings: bool,
    /// Maximum siblings per node
    pub max_siblings_per_node: usize,
    /// Phase-specific weights
    pub phase_weights: PhaseWeights,
}

// Register a custom policy
let mut registry = PolicyRegistry::new();
let custom_policy = SlicePolicyV1 {
    max_nodes: 100,
    max_radius: 8,
    distance_decay: 0.85,
    ..Default::default()
};
let policy_ref = registry.register(custom_policy);
// policy_ref.params_hash is stable across restarts

[sensitive field redacted]
    secret,
    canonical_string(
        slice_id,
        anchor_turn_id,
        policy_id,
        policy_params_hash,
        graph_snapshot_hash,
        schema_version,
        "admissibility_token_v2_hmac"
    )
)[..16]  // First 128 bits as hex

┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│ RAG++ uses  │      │ Graph Kernel     │      │ Token Valid?    │
│ slice turns │─────▶│ POST /api/verify │─────▶│                 │
│             │      │                  │      │ Yes → Proceed   │
│             │      │                  │      │ No  → Reject    │
└─────────────┘      └──────────────────┘      └─────────────────┘

snapshot_hash = xxHash64(
    edge_count ||
    schema_version ||
    fold(sorted_turns, (turn_id, content_hash))
)

snapshot_hash = canonical_hash(max_updated_at, turn_count, edge_count, schema_version)

pub struct SliceExport {
    pub anchor_turn_id: TurnId,
    pub turns: Vec<TurnSnapshot>,        // Sorted by TurnId
    pub edges: Vec<Edge>,                // Sorted by (parent, child)
    pub policy_id: String,
    pub policy_params_hash: String,
    pub schema_version: String,
    pub slice_id: SliceFingerprint,      // Deterministic selection hash
    pub graph_snapshot_hash: GraphSnapshotHash,  // Content immutability
    pub admissibility_token: AdmissibilityToken, // Unforgeable proof
}

{
  "anchor_turn_id": "550e8400-e29b-41d4-a716-446655440000",
  "policy_ref": {
    "policy_id": "slice_policy_v1",
    "params_hash": "a1b2c3d4e5f6"
  }
}

{
  "slice": {
    "anchor_turn_id": "550e8400-e29b-41d4-a716-446655440000",
    "turns": [...],
    "edges": [...],
    "slice_id": "7f8a9b0c...",
    "graph_snapshot_hash": "c3d4e5f6...",
    "admissibility_token": "1a2b3c4d5e6f7890...",
    "policy_id": "slice_policy_v1",
    "policy_params_hash": "a1b2c3d4e5f6",
    "schema_version": "1.0.0"
  },
  "policy_ref": {
    "policy_id": "slice_policy_v1",
    "params_hash": "a1b2c3d4e5f6"
  }
}

{
  "anchor_turn_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "policy_ref": null
}

{
  "admissibility_token": "1a2b3c4d5e6f7890...",
  "slice_id": "7f8a9b0c...",
  "anchor_turn_id": "550e8400-e29b-41d4-a716-446655440000",
  "policy_id": "slice_policy_v1",
  "policy_params_hash": "a1b2c3d4e5f6",
  "graph_snapshot_hash": "c3d4e5f6...",
  "schema_version": "1.0.0"
}

{
  "valid": true,
  "reason": null
}

{
  "policies": [
    {
      "policy_id": "slice_policy_v1",
      "params_hash": "a1b2c3d4e5f6"
    }
  ],
  "registry_fingerprint": "abc123..."
}

{
  "status": "healthy",
  "version": "0.1.0",
  "schema_version": "1.0.0",
  "policy_count": 1,
  "registry_fingerprint": "a1b2c3d4e5f6",
  "database": {
    "connected": true,
    "pool_size": 5,
    "pool_idle": 3,
    "pool_max": 10
  }
}

pub struct PostgresConfig {
    pub database_url: String,
    pub max_connections: u32,      // Default: 10
    pub min_connections: u32,      // Default: 2
    pub connect_timeout_secs: u64, // Default: 10
    pub idle_timeout_secs: u64,    // Default: 300 (5 min)
    pub max_lifetime_secs: u64,    // Default: 1800 (30 min)
}

#[async_trait]
pub trait GraphStore: Send + Sync {
    async fn get_turn(&self, id: &TurnId) -> Result<Option<TurnSnapshot>, Error>;
    async fn get_parents(&self, id: &TurnId) -> Result<Vec<TurnId>, Error>;
    async fn get_children(&self, id: &TurnId) -> Result<Vec<TurnId>, Error>;
    async fn get_siblings(&self, id: &TurnId, limit: usize) -> Result<Vec<TurnId>, Error>;
    async fn get_edges(&self, turn_ids: &[TurnId]) -> Result<Vec<Edge>, Error>;
}

CREATE TABLE memory_turns (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID REFERENCES conversations(id),
    session_id TEXT,
    role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
    phase TEXT,
    content_text TEXT NOT NULL,
    content_hash TEXT,  -- SHA-256 of content_text
    salience FLOAT DEFAULT 0.5,
    depth INTEGER DEFAULT 0,
    parent_turn_id UUID REFERENCES memory_turns(id),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    trajectory_coord JSONB
);

CREATE INDEX idx_memory_turns_parent ON memory_turns(parent_turn_id);
CREATE INDEX idx_memory_turns_content_hash ON memory_turns(content_hash);

-- migrations/012_content_hash_backfill_incremental.sql
DO $$
DECLARE
    batch_size INTEGER := 10000;
    rows_updated INTEGER;
BEGIN
    LOOP
        UPDATE memory_turns
        SET content_hash = encode(sha256(content_text::bytea), 'hex')
        WHERE id IN (
            SELECT id FROM memory_turns
            WHERE content_hash IS NULL AND content_text IS NOT NULL
            LIMIT batch_size
            FOR UPDATE SKIP LOCKED
        );
        GET DIAGNOSTICS rows_updated = ROW_COUNT;
        IF rows_updated = 0 THEN EXIT; END IF;
        PERFORM pg_sleep(0.1);
    END LOOP;
END $$;

# cloudbuild-service.yaml
steps:
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/graph-kernel:latest',
           '-f', 'Dockerfile.service', '.']

  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/graph-kernel:latest']

  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    entrypoint: gcloud
    args:
      - 'run'
      - 'deploy'
      - 'graph-kernel'
      - '--image=gcr.io/$PROJECT_ID/graph-kernel:latest'
      - '--platform=managed'
      - '--region=us-central1'
      - '--no-allow-unauthenticated'
      - '--port=8001'
      - '--memory=1Gi'
      - '--cpu=1'
      - '--timeout=60'
      - '--concurrency=50'
      - '--min-instances=0'
      - '--max-instances=10'
      - '--cpu-throttling=true'
      - '--set-secrets=KERNEL_HMAC_SECRET=kernel-hmac-[sensitive field redacted],DATABASE_URL=database-url:latest'
      - '--set-env-vars=RUST_LOG=info,HOST=[ip]'

FROM rust:1.80.0-slim as builder
WORKDIR /app
RUN apt-get update && apt-get install -y pkg-config libssl-dev
COPY Cargo.toml Cargo.lock* ./
COPY src ./src
RUN cargo build --release --features service --bin graph_kernel_service

FROM debian:bookworm-slim
WORKDIR /app
RUN apt-get update && apt-get install -y ca-certificates libssl3 curl
COPY --from=builder /app/target/release/graph_kernel_service /app/
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser
ENV PORT=8001 HOST=[ip] RUST_LOG=info
EXPOSE 8001
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
    CMD curl -f http://localhost:8001/health || exit 1
CMD ["/app/graph_kernel_service"]

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

# Grant Cloud Run access
gcloud secrets add-iam-policy-binding kernel-hmac-secret \
    --member="serviceAccount:[email]" \
    --role="roles/secretmanager.secretAccessor"

{
  "timestamp": "2026-01-02T10:00:00.000Z",
  "level": "INFO",
  "target": "graph_kernel_service",
  "trace_id": "abc123def456",
  "message": "slice generated",
  "slice_id": "7f8a9b0c...",
  "anchor_turn_id": "550e8400-...",
  "turn_count": 25,
  "edge_count": 42,
  "latency_ms": 45
}

# High Priority
- alert: GraphKernelSliceBoundaryViolation
  expr: count_over_time({job="graph-kernel"} |= "SLICE_BOUNDARY_VIOLATION" [5m]) > 0
  severity: critical

- alert: GraphKernelHighErrorRate
  expr: sum(rate(graph_kernel_requests_total{status=~"5.."}[5m])) / sum(rate(graph_kernel_requests_total[5m])) > 0.05
  severity: warning

# Medium Priority
- alert: GraphKernelHighLatency
  expr: histogram_quantile(0.95, rate(graph_kernel_slice_latency_ms[5m])) > 5000
  severity: warning

- alert: GraphKernelTokenFailures
  expr: sum(rate(graph_kernel_token_verifications_total{result="invalid"}[5m])) > 0.1
  severity: warning

pub struct AdmissibleEvidenceBundle {
    slice: SliceExport,
    verified_at_unix_ms: i64,
}

impl AdmissibleEvidenceBundle {
    /// ONLY way to construct - requires HMAC verification
    pub fn from_verified(
        slice: SliceExport,
        hmac_secret: &[u8],
    ) -> Result<Self, VerificationError> {
        // Verifies HMAC token before constructing
        if !slice.admissibility_token.verify_hmac(...) {
            return Err(VerificationError::TokenMismatch);
        }
        Ok(Self { slice, verified_at_unix_ms: now() })
    }
}

// OLD (unsafe - accepts any slice):
fn promote_turn(turn_id: TurnId, evidence: Vec<TurnSnapshot>) { ... }

// NEW (type-safe - only accepts verified bundles):
fn promote_turn(turn_id: TurnId, evidence: &AdmissibleEvidenceBundle) { ... }

// Downstream service (RAG++ promotion pipeline)
use cc_graph_kernel::{AdmissibleEvidenceBundle, VerificationError};

async fn promote_turn_lifecycle(
    turn_id: TurnId,
    slice: SliceExport,
    kernel_secret: &[u8],
) -> Result<(), PromotionError> {
    // Verify admissibility
    let bundle = AdmissibleEvidenceBundle::from_verified(slice, kernel_secret)?;

    // Type system guarantees bundle is verified
    promote_turn_internal(turn_id, &bundle)?;

    Ok(())
}

// This function signature makes forgery impossible
fn promote_turn_internal(
    turn_id: TurnId,
    evidence: &AdmissibleEvidenceBundle,  // Must be verified
) -> Result<(), PromotionError> {
    // Can safely use evidence.turn_ids() knowing it's admissible
    let admissible_ids = evidence.turn_ids();
    // ... promotion logic
}

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│ User Query      │────▶│ RAG++ Service    │────▶│ Graph Kernel    │
│                 │     │                  │     │                 │
│                 │     │ 1. Get anchor    │     │ 2. Generate     │
│                 │     │    turn ID       │     │    slice        │
│                 │     │                  │◀────│                 │
│                 │     │ 3. Filter turns  │     │                 │
│                 │◀────│    by slice      │     │                 │
│ Response        │     │                  │     │                 │
└─────────────────┘     └──────────────────┘     └─────────────────┘

# In RAG++ retrieval pipeline
from httpx import AsyncClient

async def get_admissible_context(anchor_turn_id: str, graph_kernel_url: str):
    async with AsyncClient() as client:
        response = await client.post(
            f"{graph_kernel_url}/api/slice",
            json={"anchor_turn_id": anchor_turn_id}
        )
        slice_data = response.json()["slice"]

        # Only use turns from the slice
        admissible_turn_ids = {t["id"] for t in slice_data["turns"]}

        # Carry provenance forward
        provenance = {
            "slice_id": slice_data["slice_id"],
            "admissibility_token": slice_data["admissibility_token"],
            "graph_snapshot_hash": slice_data["graph_snapshot_hash"],
            "schema_version": slice_data["schema_version"],
        }

        return admissible_turn_ids, provenance

cd core/cc-graph-kernel
cargo test --all-features

# Start service locally
KERNEL_HMAC_SECRET=test_secret_32bytes_minimum!! \
DATABASE_URL=postgresql://localhost/orbit_test \
cargo run --release --features service --bin graph_kernel_service

# Test slice generation
curl -X POST http://localhost:8001/api/slice \
    -H "Content-Type: application/json" \
    -d '{"anchor_turn_id": "YOUR_TURN_ID"}'

# Test health
curl http://localhost:8001/health | jq

let snapshot = GraphSnapshot::capture(&store, config).await?;

let slicer = BatchSlicer::new(store, policy);
let results = slicer.slice_all(&anchor_ids).await?;

let analyzer = OverlapAnalyzer::new();
let overlap_graph = analyzer.analyze(&slices)?;

let influence = compute_influence(&slice, &graph)?;
// influence.scores contains per-turn influence metrics

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

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