Skip to content

Federation (v6.3)

Federation enables cross-repository queries and unified visibility across multiple codebases. Transform CKB from a single-repo tool into an organizational code intelligence platform.

v6.3 Theme: Contract-Aware Impact Analysis — cross-repo intelligence through explicit API boundaries

What is Federation?

A federation is a named collection of repositories that can be queried together. Instead of analyzing each repo in isolation, federation lets you:

  • Search for modules across all your microservices
  • Find ownership patterns across the organization
  • Identify hotspots spanning multiple repositories
  • Track architectural decisions at the org level

Quick Start

# Create a federation
ckb federation create platform --description "Our microservices platform"

# Add repositories
ckb federation add platform --repo-id=api --path=/code/api-service
ckb federation add platform --repo-id=auth --path=/code/auth-service
ckb federation add platform --repo-id=web --path=/code/web-app

# Sync the federation index
ckb federation sync platform

# Check status
ckb federation status platform

Core Concepts

Repository Identity

Each repository in a federation has two identifiers:

Identifier Description Mutable?
repo_uid UUID generated on first add No - permanent
repo_id Human-readable alias Yes - can rename

The UUID ensures stable references even if you rename repositories:

# Rename without breaking references
ckb federation rename platform old-api api

Federation Index

When you sync a federation, CKB extracts summaries from each repository's database and stores them in a unified index:

  • Modules - Name, responsibility, owner, tags
  • Ownership - Path patterns and owners
  • Hotspots - Top 20 per repo by score
  • Decisions - ADRs with status and affected modules

This index enables fast cross-repo queries without opening each database.

Schema Compatibility

Federation requires repositories with schema version 6 or higher. Check compatibility:

ckb federation status platform
# Shows: Compatible: 3/4

# See details
ckb federation repos platform --json

For incompatible repos, the fix is:

cd /path/to/repo
ckb refresh --migrate

Staleness Propagation

Federation staleness follows "weakest link" semantics - a federation is only as fresh as its stalest repository.

Level Meaning
fresh All repos synced within 24 hours
aging Some repos 1-7 days old
stale Some repos 7-30 days old
obsolete Some repos over 30 days old

Query results include staleness information so you know when to refresh.

CLI Commands

Create a Federation

ckb federation create <name> [--description "..."]

Creates a new federation with the given name. Federations are stored in ~/.ckb/federation/<name>/.

Delete a Federation

ckb federation delete <name> [--force]

Deletes a federation and its index. Use --force to skip confirmation.

List Federations

ckb federation list [--json]

Lists all available federations.

Federation Status

ckb federation status <name> [--json]

Shows federation details:

  • Name and description
  • Creation date
  • Number of repositories
  • Compatibility status
  • Per-repo sync status

Add Repository

ckb federation add <federation> --repo-id=<id> --path=<path> [--tags=tag1,tag2]

Adds a repository to the federation. The path must be an absolute path to a CKB-initialized repository.

Remove Repository

ckb federation remove <federation> <repo-id>

Removes a repository from the federation.

Rename Repository

ckb federation rename <federation> <old-id> <new-id>

Changes a repository's alias. The UUID remains unchanged.

List Repositories

ckb federation repos <name> [--json]

Lists all repositories in a federation with their paths, tags, and add dates.

Sync Federation

ckb federation sync <name> [--force] [--dry-run] [--json]

Syncs repository data to the federation index:

  • --force - Sync even if data appears fresh
  • --dry-run - Preview what would be synced
  • --json - Output results as JSON

Search Modules

ckb federation search-modules <federation> [--query=<query>] [--repos=<id1,id2>] [--tags=<tag1,tag2>] [--limit=50] [--json]

Search for modules across all repositories in the federation.

# Find all authentication modules
ckb federation search-modules platform --query=auth

# Search within specific repos
ckb federation search-modules platform --query=handler --repos=api,web

# Filter by tags
ckb federation search-modules platform --tags=core,infrastructure

Search Ownership

ckb federation search-ownership <federation> [--path=<glob>] [--repos=<id1,id2>] [--limit=50] [--json]

Search for ownership patterns across all repositories.

# Find all API ownership
ckb federation search-ownership platform --path="**/api/**"

# Search within specific repos
ckb federation search-ownership platform --repos=api,auth

Get Hotspots

ckb federation hotspots <federation> [--top=20] [--min-score=0.3] [--repos=<id1,id2>] [--json]

Returns merged hotspots (high churn + complexity) across all repositories.

# Top 20 hotspots (default)
ckb federation hotspots platform

# Top 50 with higher threshold
ckb federation hotspots platform --top=50 --min-score=0.5

# Filter to specific repos
ckb federation hotspots platform --repos=api,auth

Search Decisions

ckb federation search-decisions <federation> [--query=<query>] [--module=<module>] [--status=<status1,status2>] [--repos=<id1,id2>] [--limit=50] [--json]

Search for architectural decisions (ADRs) across all repositories.

# Find all database decisions
ckb federation search-decisions platform --query=database

# Filter by status
ckb federation search-decisions platform --status=accepted,proposed

# Filter by affected module
ckb federation search-decisions platform --module=internal/api

HTTP API

List Federations

GET /federations

Returns all available federations.

curl http://localhost:8080/federations
{
  "federations": ["platform", "infrastructure"],
  "count": 2
}

Federation Status

GET /federations/:name/status

Returns detailed federation status.

curl http://localhost:8080/federations/platform/status
{
  "name": "platform",
  "description": "Our microservices platform",
  "createdAt": "2024-12-18T10:00:00Z",
  "repoCount": 4,
  "repos": [...],
  "compatibility": {
    "compatible": 3,
    "incompatible": 1
  }
}

List Repositories

GET /federations/:name/repos[?includeCompatibility=true]

Returns repositories in the federation.

curl http://localhost:8080/federations/platform/repos?includeCompatibility=true

Search Modules

GET /federations/:name/modules?q=<query>&repos=<id1,id2>&tags=<tag1,tag2>&limit=50

Search for modules across all repositories.

# Find all authentication modules
curl "http://localhost:8080/federations/platform/modules?q=auth"

# Search within specific repos
curl "http://localhost:8080/federations/platform/modules?q=handler&repos=api,web"

Response includes staleness information:

{
  "modules": [
    {
      "repoId": "api",
      "moduleId": "internal/auth",
      "name": "auth",
      "responsibility": "User authentication and session management",
      "ownerRef": "@security-team"
    }
  ],
  "total": 1,
  "staleness": {
    "overallStaleness": "fresh",
    "refreshRecommended": false
  }
}

Search Ownership

GET /federations/:name/ownership?path=<glob>&repos=<id1,id2>&limit=50

Search for ownership patterns across repositories.

# Find all API ownership
curl "http://localhost:8080/federations/platform/ownership?path=**/api/**"

Get Hotspots

GET /federations/:name/hotspots?repos=<id1,id2>&top=20&minScore=0.3

Returns merged hotspots across all repositories.

curl "http://localhost:8080/federations/platform/hotspots?top=10"

Search Decisions

GET /federations/:name/decisions?q=<query>&status=accepted&repos=<id1,id2>&module=<module>&limit=50

Search for architectural decisions (ADRs) across repositories.

# Find all accepted authentication decisions
curl "http://localhost:8080/federations/platform/decisions?q=authentication&status=accepted"

Sync Federation

POST /federations/:name/sync
Content-Type: application/json

{
  "force": false,
  "dryRun": false,
  "repoIds": ["api", "auth"]  // optional, default: all
}

Syncs repository data to the federation index.

curl -X POST http://localhost:8080/federations/platform/sync \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

MCP Tools

Federation adds 8 new MCP tools for AI assistant integration.

listFederations

List all available federations.

{
  "name": "listFederations",
  "arguments": {}
}

federationStatus

Get detailed status of a federation.

{
  "name": "federationStatus",
  "arguments": {
    "federation": "platform"
  }
}

federationRepos

List repositories in a federation.

{
  "name": "federationRepos",
  "arguments": {
    "federation": "platform",
    "includeCompatibility": true
  }
}

federationSearchModules

Search for modules across all repositories.

{
  "name": "federationSearchModules",
  "arguments": {
    "federation": "platform",
    "query": "authentication",
    "repos": ["api", "auth"],
    "limit": 20
  }
}

federationSearchOwnership

Search for ownership patterns across repositories.

{
  "name": "federationSearchOwnership",
  "arguments": {
    "federation": "platform",
    "path": "**/api/**",
    "limit": 50
  }
}

federationGetHotspots

Get merged hotspots across all repositories.

{
  "name": "federationGetHotspots",
  "arguments": {
    "federation": "platform",
    "top": 20,
    "minScore": 0.3
  }
}

federationSearchDecisions

Search for architectural decisions across repositories.

{
  "name": "federationSearchDecisions",
  "arguments": {
    "federation": "platform",
    "query": "database",
    "status": ["accepted"],
    "module": "persistence"
  }
}

federationSync

Sync federation index from repository data.

{
  "name": "federationSync",
  "arguments": {
    "federation": "platform",
    "force": true,
    "dryRun": false,
    "repos": ["api"]
  }
}

Configuration

Federation data is stored in ~/.ckb/federation/<name>/:

~/.ckb/federation/
└── platform/
    ├── config.toml    # Federation configuration
    └── index.db       # SQLite index database

config.toml Format

name = "platform"
description = "Our microservices platform"
created_at = "2024-12-18T10:00:00Z"
updated_at = "2024-12-18T14:30:00Z"

[repos](/docs/repos)
repo_uid = "550e8400-e29b-41d4-a716-446655440001"
repo_id = "api"
path = "/code/api-service"
tags = ["backend", "core"]
added_at = "2024-12-18T10:05:00Z"

[repos](/docs/repos)
repo_uid = "550e8400-e29b-41d4-a716-446655440002"
repo_id = "auth"
path = "/code/auth-service"
tags = ["backend", "security"]
added_at = "2024-12-18T10:06:00Z"

Use Cases

Find all "authentication" modules across your organization:

# CLI
ckb federation sync platform
# Then use HTTP/MCP to search

# HTTP
curl "http://localhost:8080/federations/platform/modules?q=auth"

Organization-Wide Hotspots

Identify the most volatile code across all services:

curl "http://localhost:8080/federations/platform/hotspots?top=20"

Unified Ownership View

Find who owns API code across the organization:

curl "http://localhost:8080/federations/platform/ownership?path=**/api/**"

Find all decisions related to databases:

curl "http://localhost:8080/federations/platform/decisions?q=database&status=accepted"

PR Review Across Repos

When reviewing changes that span multiple repositories:

User: "Who should review changes to the auth system?"

AI (using federationSearchOwnership):
Based on the federation data:
- api-service: @security-team, @api-team
- auth-service: @security-team (primary), @platform-team
- web-app: @frontend-team (for auth UI)

Recommended reviewers: @security-team (owns auth across all repos)

Best Practices

1. Keep Repos Synced

Run sync regularly or after significant changes:

# In CI/CD after deployment
ckb federation sync platform

2. Use Tags for Filtering

Tag repositories by domain for focused queries:

ckb federation add platform --repo-id=api --path=/code/api --tags=backend,core
ckb federation add platform --repo-id=web --path=/code/web --tags=frontend

Then filter:

curl "http://localhost:8080/federations/platform/modules?tags=backend"

3. Handle Staleness

Always check staleness in query results:

result = query_federation_modules("platform", "auth")
if result["staleness"]["refreshRecommended"]:
    sync_federation("platform")
    result = query_federation_modules("platform", "auth")

4. Monitor Compatibility

Before critical operations, verify all repos are compatible:

ckb federation status platform
# Ensure Compatible: N/N

5. Name Repos Meaningfully

Use consistent, descriptive repo IDs:

# Good
--repo-id=user-api
--repo-id=payment-service
--repo-id=admin-dashboard

# Avoid
--repo-id=repo1
--repo-id=backend
--repo-id=new

Troubleshooting

Repo Shows as Incompatible

Warning: Schema version 2 is below minimum 6
Action: Run: cd /path/to/repo && ckb refresh --migrate

Run the suggested command to upgrade the schema.

Sync Skipped

REPO ID  STATUS   MODULES  OWNERSHIP  HOTSPOTS  DECISIONS  DURATION
api      skipped  0        0          0         0          0ms

Check repo compatibility:

ckb federation repos platform --json | jq '.compatibility'

Federation Not Found

Error: federation "platform" not found

List available federations:

ckb federation list

Path Does Not Exist

Error: path does not exist: /code/old-location

Update the repo path or remove and re-add:

ckb federation remove platform old-api
ckb federation add platform --repo-id=api --path=/code/new-location

Limitations

  • Schema v6+ - Requires all repos to have CKB schema version 6 or higher
  • Manual sync - Index must be explicitly synced (no automatic watching)
  • Top 20 hotspots - Only top 20 hotspots per repo are indexed

Contract-Aware Impact Analysis (v6.3)

v6.3 adds contract detection and cross-repo dependency tracking through explicit API boundaries. This enables answering questions like "What breaks if I change this shared API?"

Supported Contract Types

Type Extensions Detection
proto .proto Package, imports, services, messages
openapi .yaml, .json (with openapi/swagger key) Version, paths, servers

Visibility Classification

Contracts are classified by visibility:

Visibility Criteria
public Under api/, proto/, versioned package (v1, v2), or has service definitions
internal Under internal/, testdata/, or package name contains "internal"
unknown No clear signals (treated conservatively as public)

Evidence Tiers

Contract dependency edges have confidence tiers:

Tier Confidence Source
Declared (tier 1) 1.0 buf.yaml deps, proto imports, generated code (*.pb.go, *.pb.ts)
Derived (tier 2) 0.7-0.9 Type-matching heuristics, same package references
Heuristic (tier 3) ≤0.5 File naming patterns (hidden by default)

Contract CLI Commands

List Contracts

# List all contracts in a federation
ckb contracts list platform

# Filter by repo
ckb contracts list platform --repo=api

# Filter by type
ckb contracts list platform --type=proto

# Filter by visibility
ckb contracts list platform --visibility=public

# JSON output
ckb contracts list platform --json

Analyze Contract Impact

# Analyze impact of changing a contract
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto

# Include transitive consumers
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --include-transitive

# Include heuristic (tier 3) edges
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --include-heuristic

# Set max depth for transitive analysis
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto --max-depth=5

Output includes:

  • Contract info - Type, visibility, path
  • Direct consumers - Repos that import/use the contract with evidence tier
  • Transitive consumers - Repos reached through contract imports (with depth)
  • Risk assessment - low/medium/high with risk factors
  • Ownership - Who to contact for approval

Get Contract Dependencies

# Show what contracts a repo depends on
ckb contracts deps platform --repo=api --direction=dependencies

# Show what repos consume contracts from this repo
ckb contracts deps platform --repo=api --direction=consumers

# Show both directions (default)
ckb contracts deps platform --repo=api --direction=both

Manage Edges

# Suppress a false positive edge
ckb contracts suppress platform --edge=123 --reason="Not actually used"

# Verify an edge (increase confidence)
ckb contracts verify platform --edge=123

Contract Statistics

# Show contract statistics for a federation
ckb contracts stats platform

Output:

Contract Statistics:
  Total contracts:    45
    Public:           32
    Internal:         13

By type:
  proto        38
  openapi       7

Dependency edges:
  Total:              123
    Declared (tier 1): 89
    Derived (tier 2):  34

Risk Assessment

Impact analysis computes risk based on:

Factor Risk Impact
Direct consumers > 5 High
Direct consumers > 2 Medium
Transitive consumers present +1 level
Public visibility +1 level
Has service definitions +1 level
Versioned (v1, v2) Indicates stable API

MCP Contract Tools

See MCP Integration for the 6 new contract tools:

  • listContracts - List contracts in a federation
  • analyzeContractImpact - Analyze impact of changing a contract
  • getContractDependencies - Get contract dependencies for a repo
  • suppressContractEdge - Suppress false positive edges
  • verifyContractEdge - Verify an edge
  • getContractStats - Get contract statistics

Workflow: Before Changing a Shared API

# 1. Find the contract
ckb contracts list platform --repo=api --type=proto

# 2. Analyze impact
ckb contracts impact platform --repo=api --path=proto/api/v1/user.proto

# 3. Contact owners listed in output

# 4. Make change and re-sync
ckb federation sync platform

Proto Import Graph

For protobuf contracts, CKB builds an import graph that enables transitive consumer detection:

api-service/proto/user.proto
    ↓ imported by
gateway/proto/gateway.proto
    ↓ imported by
web-app/generated/api.ts

When user.proto changes, both gateway and web-app are identified as affected.


v6.4 adds runtime telemetry integration for observed usage analysis. While not federation-specific, telemetry data can enhance contract impact analysis by showing which contracts are actually called at runtime. See Configuration for telemetry setup.


Remote Index Serving (v7.3)

v7.3 adds remote index serving — the first phase of v3 Federation. This enables serving symbol indexes over HTTP so remote clients can query code intelligence without direct database access.

ckb serve --index-server --index-config /path/to/config.toml

Use Cases

Centralized Code Intelligence Server: Run a single CKB instance that serves indexes for multiple repositories, allowing AI tools and IDEs to query code intelligence without local SCIP indexes.

Cross-Team Symbol Lookup: Teams can query symbols from other repositories without needing direct access to those codebases.

Federation Client Foundation: Remote index serving is Phase 1 of v3 Federation. Future phases will add incremental sync, change journals, and full federation client support.

Documentation


Index Upload (v7.3 Phase 2)

Phase 2 adds index upload capability — pushing SCIP indexes to the server via HTTP, eliminating the need for local filesystem paths. CKB transforms from a "bring your database" model to a centralized index hosting service.

# Generate SCIP index locally, then upload
scip-go
curl -X POST http://localhost:8080/index/repos/myorg/myrepo/upload \
  -H "Content-Type: application/octet-stream" \
  --data-binary @index.scip

With allow_create_repo = true, repos are auto-created on first upload.

See Configuration#upload-mode-example-phase-2 for server configuration and API Reference#remote-index-serving-v73 for complete endpoint documentation.


Authentication & API Keys (v7.3)

v7.3 adds scoped API key authentication for the index server. See Authentication for complete documentation including:

  • Token scopes (read/write/admin)
  • Token management CLI (ckb token create/list/revoke/rotate)
  • Configuration options
  • Per-repo restrictions
  • Rate limiting
  • Error responses
  • Use cases for CI/CD, multi-tenant servers, and more

Remote Federation (v7.3 Phase 5)

v7.3 adds remote federation client support — the ability to connect to remote CKB index servers and query them alongside local repositories. This transforms federation from local-only aggregation to a distributed code intelligence network.

Overview

With remote federation, you can:

  • Query symbols across multiple remote CKB servers
  • Combine local and remote results with source attribution
  • Cache remote metadata locally for faster queries
  • Gracefully degrade when remote servers are unavailable

CLI Commands

Add Remote Server

ckb federation add-remote <federation> <name> --url=<url> [--token=<token>] [--cache-ttl=1h] [--timeout=30s]

Adds a remote CKB index server to a federation. The token supports environment variable expansion with ${VAR} syntax.

# Add a production server
ckb federation add-remote platform prod --url=https://ckb.company.com --token=$CKB_TOKEN

# Add a staging server with custom cache TTL
ckb federation add-remote platform staging --url=https://staging-ckb.company.com --cache-ttl=15m

Remove Remote Server

ckb federation remove-remote <federation> <name>

Removes a remote server from the federation.

ckb federation remove-remote platform staging

List Remote Servers

ckb federation list-remote <federation> [--json]

Lists all configured remote servers in a federation.

ckb federation list-remote platform

# Output:
NAME     URL                           ENABLED  LAST SYNC          ERROR
prod     https://ckb.company.com       yes      2024-12-22 10:00   -
staging  https://staging.company.com   yes      never              -

Sync Remote Metadata

ckb federation sync-remote <federation> [name] [--json]

Syncs repository metadata from remote servers. If a server name is provided, only that server is synced. Otherwise, all enabled remote servers are synced.

# Sync specific server
ckb federation sync-remote platform prod

# Sync all servers
ckb federation sync-remote platform

Check Remote Server Status

ckb federation status-remote <federation> <name> [--json]

Checks connectivity and status of a remote server.

ckb federation status-remote platform prod

# Output:
Server: prod
URL: https://ckb.company.com
Enabled: true
Online: true
Latency: 45ms
Last Synced: 2024-12-22 10:00:00
Cached Repos: 12

Enable/Disable Remote Server

ckb federation enable-remote <federation> <name>
ckb federation disable-remote <federation> <name>

Enables or disables a remote server without removing it.

# Disable temporarily for maintenance
ckb federation disable-remote platform staging

# Re-enable
ckb federation enable-remote platform staging

Remote Server Configuration

Remote servers are stored in the federation's config.toml:

[remote_servers](/docs/remote_servers)
name = "prod"
url = "https://ckb.company.com"
token = "${CKB_PROD_TOKEN}"  # Environment variable expansion
cache_ttl = "1h"
timeout = "30s"
enabled = true
added_at = "2024-12-22T10:00:00Z"

Configuration options:

Option Default Description
name required Unique server name
url required Server URL (https:// or http://)
token "" Auth token (supports ${VAR} expansion)
cache_ttl "1h" How long to cache remote data
timeout "30s" Request timeout
enabled true Whether to include in queries

Caching

Remote metadata is cached locally to reduce latency:

Data Type Default TTL
Repository list 1 hour
Repo metadata 1 hour
Symbol searches 15 minutes
References Not cached (always fresh)
Call graph Not cached (always fresh)

Cache is stored in the federation's index database and automatically cleaned up.

Hybrid Queries

When you search symbols across a federation with remote servers, CKB queries both local and remote sources in parallel:

# Searches local federation repos AND remote servers
ckb federation search-modules platform --query=auth

Results include source attribution showing where each result came from:

{
  "modules": [
    {"repoId": "api", "source": "local", ...},
    {"repoId": "auth-service", "source": "prod", ...}
  ],
  "sources": [
    {"name": "local", "repos": 3, "latency": "5ms"},
    {"name": "prod", "repos": 12, "latency": "45ms"}
  ]
}

MCP Tools

Seven new MCP tools for remote federation:

Tool Description
federationAddRemote Add a remote server to a federation
federationRemoveRemote Remove a remote server
federationListRemote List remote servers in a federation
federationSyncRemote Sync metadata from remote servers
federationStatusRemote Get status of a remote server
federationSearchSymbolsHybrid Search symbols across local + remote
federationListAllRepos List repos from local and remote sources

Graceful Degradation

Queries succeed even if some remote servers are unavailable:

  • Unreachable servers are skipped with a warning
  • Results indicate which servers responded vs failed
  • Cached data is used when available
  • Servers are marked offline after repeated failures

Error Handling

Error Behavior
Connection refused Skip server, return cached data if available
Auth failure (401) Clear error message, don't retry
Timeout Retry with exponential backoff (max 3 retries)
Rate limited (429) Back off and retry
Invalid response Log error, skip server

Future

  • Team dashboards
  • Automatic sync triggers
  • GraphQL contract support
  • AsyncAPI contract support
  • Telemetry aggregation across federation