Federation

Federation (v6.2)

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

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

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]]
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]]
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

Local only - Federation currently works with local filesystem paths only
Schema v6+ - Requires all repos to have CKB schema version 6 or higher
Manual sync - Index must be explicitly synced (no automatic watching)
No cross-repo symbols - Symbol navigation stays within a single repo
Top 20 hotspots - Only top 20 hotspots per repo are indexed

Future (v6.3+)

Cross-repo dependency tracking
Remote federation (HTTPS endpoints)
Team dashboards
Automatic sync triggers
Symbol resolution across repos

Uh oh!

Uh oh!

Federation

Federation (v6.2)

What is Federation?

Quick Start

Core Concepts

Repository Identity

Federation Index

Schema Compatibility

Staleness Propagation

CLI Commands

Create a Federation

Delete a Federation

List Federations

Federation Status

Add Repository

Remove Repository

Rename Repository

List Repositories

Sync Federation

HTTP API

List Federations

Federation Status

List Repositories

Search Modules

Search Ownership

Get Hotspots

Search Decisions

Sync Federation

MCP Tools

listFederations

federationStatus

federationRepos

federationSearchModules

federationSearchOwnership

federationGetHotspots

federationSearchDecisions

federationSync

Configuration

config.toml Format

Use Cases

Cross-Repo Module Search

Organization-Wide Hotspots

Unified Ownership View

Cross-Repo Decision Search

PR Review Across Repos

Best Practices

1. Keep Repos Synced

2. Use Tags for Filtering

3. Handle Staleness

4. Monitor Compatibility

5. Name Repos Meaningfully

Troubleshooting

Repo Shows as Incompatible

Sync Skipped

Federation Not Found

Path Does Not Exist

Limitations

Future (v6.3+)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!