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
Cross-Repo Module Search
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/**"
Cross-Repo Decision Search
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 federationanalyzeContractImpact- Analyze impact of changing a contractgetContractDependencies- Get contract dependencies for a reposuppressContractEdge- Suppress false positive edgesverifyContractEdge- Verify an edgegetContractStats- 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.
Related: Runtime Telemetry (v6.4)
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
- Configuration#index-server-configuration-v73 — TOML schema, privacy settings, security
- API Reference#remote-index-serving-v73 — REST endpoints with request/response examples
- Authentication — Token management, scopes, rate limiting
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