Federation

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

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)
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.

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.

Future

Remote federation (HTTPS endpoints)
Team dashboards
Automatic sync triggers
GraphQL contract support
AsyncAPI contract support
Telemetry aggregation across federation

Uh oh!

Uh oh!

Federation

Federation (v6.3)

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

Contract-Aware Impact Analysis (v6.3)

Supported Contract Types

Visibility Classification

Evidence Tiers

Contract CLI Commands

List Contracts

Analyze Contract Impact

Get Contract Dependencies

Manage Edges

Contract Statistics

Risk Assessment

MCP Contract Tools

Workflow: Before Changing a Shared API

Proto Import Graph

Related: Runtime Telemetry (v6.4)

Future

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!